Realms

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

Architecture

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:

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:

cliq whoami

---

Local mode (no realm)

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

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.

---

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):

cliqd --allow-realm-override

2. Log in to the new realm:

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

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.

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
• CLI commands → CLI
• Daemon options → cliqd
• Credentials → Auth