> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcliq.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Realms

> One daemon, one realm — the enrollment model, realm switching, and what happens to your data.

<div className="cliq-kicker">Architecture</div>

A **realm** is a fleet boundary on CliqHub: an `org.slug` namespace that owns daemons, teams, runs, and a team list. Every daemon belongs to **exactly one realm** (or none, if running locally).

***

## One daemon, one realm

When you run `cliq login`, cliqd enrolls in a realm and stays there:

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
cliqd                          # start the daemon
cliq login --realm acme.ops    # enroll in acme.ops
```

After enrollment:

* cliqd registers with CliqHub and heartbeats every 30 seconds.
* Runs, teams, workspaces, and events sync to the realm.
* The realm is **locked** — a subsequent `cliq login` keeps the same realm.

To see which realm a daemon belongs to:

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
cliq whoami
```

***

## Local mode (no realm)

A daemon without a login has no realm. It runs entirely locally:

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
cliqd --no-login     # start in local-only mode
```

In local mode:

* No CliqHub enrollment, no sync, no outbox delivery.
* Teams install under `@local` scope.
* HUG gates use the local review API instead of CliqHub.
* Everything works — you just don't see runs in the CliqHub dashboard.

This is the recommended mode for [local development](/local-development).

***

## Switching realms

The realm is locked after enrollment. To move a daemon to a different realm:

1. Start cliqd with `--allow-realm-override` (or `CLIQ_ALLOW_REALM_OVERRIDE=1`):

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
cliqd --allow-realm-override
```

2. Log in to the new realm:

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
cliq login --realm acme.staging
```

**This wipes all local data**: teams, runs, workspaces, and workspace bindings are deleted. The daemon gets a fresh start in the new realm. This is intentional — runs from one realm should never leak into another.

***

## Logging out

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
cliq logout
```

Logging out clears the CliqHub session but **keeps the daemon token and realm**. The daemon stays enrolled and continues heartbeating. Log back in with `cliq login` to restore the session.

***

## Going from local to enrolled

When a daemon in local mode runs `cliq login`:

1. cliqd enrolls in the realm and gets a daemon token.
2. **All local teams, runs, and workspaces are cleared** — the daemon starts fresh in the realm.
3. cliqd restarts in place and begins syncing with CliqHub.

The wipe happens because local data has no realm context. To avoid losing work, publish your teams before enrolling.

***

## Going from enrolled to local

Starting an enrolled daemon with `--no-login` (or `--standalone`):

1. cliqd warns that you were previously enrolled.
2. If you confirm (or pass `--yes`), **all teams, runs, and workspaces from the realm are cleared**.
3. cliqd starts in local mode.

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
cliqd --no-login --yes    # confirm the realm reset
```

***

## Realm team list

A realm has a **team list**: the set of teams that Hub pushes to every daemon in the realm. When a daemon enrolls, Hub installs the team list onto it automatically. When a realm admin adds a team to the list, Hub fans the install to all online daemons.

You can also install teams locally with `cliq team install`. A locally-installed team that isn't on the realm's team list still runs, but its runs don't sync to CliqHub until a realm admin adds it.

To resolve unsyncable teams:

| Action | Effect |
| - | - |
| Add the team in CliqHub (realm admin) | Held runs sync |
| `cliq team uninstall @scope/slug --yes` | Remove the team from this daemon |

***

## Hub API

Realm management is done through the CliqHub web UI or the Hub API. See the **Hub API** tab → **Realms** for the full API reference:

| Endpoint | Purpose |
| - | - |
| `POST /v1/realms/create` | Create a realm |
| `POST /v1/realms/get`, `/get_by_id` | List / fetch realms |
| `POST /v1/realms/add_member`, `/remove_member` | Manage members |
| `POST /v1/realms/add_team`, `/remove_team` | Manage the team list |
| `POST /v1/realms/a2a` | A2A configuration |

Enroll tokens: `POST /v1/auth/generate_token` with `{ "type": "realm", "realm_id": "…" }`, or `cliq auth token <name> --realm <realm_id>`.

***

## Related

* Local dev workflow → [Local Development](/local-development)
* CLI commands → [CLI](/cli)
* Daemon options → [cliqd](/cliqd)
* Credentials → [Auth](/auth)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.