Daemon (cliqd)

Reference

cliqd is a separate binary — the long-lived daemon process that executes pipelines. The CLI (cliq) is a thin client that talks to cliqd over HTTP on 127.0.0.1:4900.

cliqd &
cliq login

Start cliqd first, then log in. The first cliq login enrolls cliqd in a realm and restarts it in place; it then registers with CliqHub and heartbeats every 30 seconds. Runs, teams, workspaces, settings and the login session all live in the daemon’s SQLite store at ~/.cliqrc/data/daemon.db.

Options

Option	Description
`--hub <url>`	CliqHub API URL for this daemon (remembered; default `https://api.cliqhub.io`)
`--allow-realm-override`	Let `cliq login --realm` move this daemon to another realm. Off by default: the realm is locked once enrolled.
`-n, --name <name>`	Sticky display name for this daemon (generated if omitted)
`--standalone`	Skip CliqHub enroll/register — local only
`--no-login`	Alias for `--standalone`
`--no-sync`	Disable the CliqHub sync relay (`hub_connect.sync=false`)
`--reset-db`	Wipe local state (workspaces, runs, teams); keeps identity, realm and login
`--reset-id`	Wipe everything, including identity and realm; enroll again with `cliq login` (implies `--reset-db`)
`-y, --yes`	Skip confirmation prompts (e.g. with `--reset-db`)
`-V, --version`	Print the version

cliqd --realm was removed. Choose the realm when you log in: cliq login --realm <org.slug> (moving an enrolled daemon needs --allow-realm-override).

Examples

cliqd                                  # start; connects if already enrolled
cliqd --allow-realm-override           # personal laptop: let `cliq login --realm` move it
cliqd --hub http://127.0.0.1:3001      # use (and remember) a local CliqHub
cliqd --name laptop                    # set a sticky display name
cliqd --standalone                     # local only, no CliqHub
cliqd --no-sync                        # enroll but skip the sync relay
cliqd --reset-db --yes                 # wipe local state; keep identity, realm and login
cliqd --reset-id --yes                 # wipe everything; enroll again with `cliq login`

Modes

Mode	What happens
Connected	cliqd has a daemon token (stored, or `CLIQ_DAEMON_TOKEN`). It registers in that token’s realm, loads the realm’s dispatch key, heartbeats every 30s and syncs to CliqHub. A restart never moves it to another realm.
Local-only	No daemon token and no login yet. cliqd runs locally until `cliq login` enrolls it (the login restarts it in place).
Standalone (`--standalone`)	Runs locally without CliqHub — no enrollment, no sync, no outbox delivery.

If CliqHub rejects a stored daemon token (revoked), cliqd mints a new one for the same realm using your login. It never re-enrolls a token you set with CLIQ_DAEMON_TOKEN.

How teams get installed

When cliqd enrolls in a realm, it starts with an empty team catalog. Teams arrive in two ways:

Hub pushes the realm’s team list. On enrollment (and on each heartbeat), Hub installs the realm’s declared teams onto the daemon — manifests, agent settings, and all. A realm admin manages this list in CliqHub (realms/add_team / realms/remove_team). When a team is added to the list, Hub fans it out to every online daemon in the realm.
Local install. You can also install teams directly with cliq team install ./my-team or cliq team install @scope/slug. These are local additions to the daemon’s catalog.

Teams not on the realm’s team list

When a locally-installed team is not on the realm’s team list, Hub refuses to sync it:

The team still runs on this machine.
Its runs are queued locally and don’t appear in CliqHub.
cliq run warns that the run won’t sync.
cliq whoami lists the teams whose runs are waiting.
cliqd rechecks every minute. Once a realm admin adds the team to the list, held runs sync.

Other teams’ runs are unaffected — one unlisted team never blocks the rest. To resolve it:

Action	Effect
Add the team to the realm in CliqHub (realm admin)	Held runs sync within about a minute
`cliq team uninstall @scope/slug --yes`	Removes the team from this daemon

Stopping a run

cliq instance stop <run>, or Cancel in CliqHub, marks the run cancelled and stops its work right away: cliqd kills the running agent process, ends any wait for inputs, and cancels the active sub-team run. The run does not go on to its next phase.

Artifacts

Agents can upload artifacts up to the artifact size limit, 50 MB by default. Set CLIQ_ARTIFACT_MAX_MB to change it. A larger artifact is refused with 413 PAYLOAD_TOO_LARGE. Other requests to cliqd are limited to 10 MB.

Local tokens

A local token (cliq_…) is a credential minted by cliqd itself. A caller on another host sends it as Authorization: Bearer cliq_…. It works whether or not cliqd is connected to CliqHub, so it is the way in when cliqd is not connected — for example a cliqd in Docker reached through a port mapping. The token is checked against a stored hash, is never passed on to CliqHub, and a revoked token is refused. There is no cliq command for local tokens. Use the HTTP routes. They answer only callers on the machine running cliqd (403 SETTING_LOCAL_ONLY otherwise):

Route	Body	Does
`POST /v1/tokens/create`	`{ "label": "…" }`	Mint a token. The value is returned once.
`POST /v1/tokens/get`	`{}`	List active tokens (no values)
`POST /v1/tokens/revoke`	`{ "token_id": "…" }`	Revoke a token

# On the machine running cliqd (in Docker: docker exec into the container)
curl -s http://127.0.0.1:4900/v1/tokens/create \
  -H 'Content-Type: application/json' -d '{"label":"laptop-cli"}'
# → { "ok": true, "data": { "token": { "id": "…", "name": "laptop-cli", … }, "value": "cliq_…" } }

# From another host
export CLIQ_DAEMON_HOST=build-box.internal CLIQ_DAEMON_TOKEN=cliq_…
cliq status --all

For cliqd to accept connections from other hosts it must listen on a non-loopback address (CLIQ_DAEMON_HOST=0.0.0.0 or the daemon.host setting).

Who can reach cliqd

Caller	Needs
Same machine	Nothing
Another host, cliqd connected to CliqHub	A dispatch JWT CliqHub signed for this daemon, a `cliq_tok_…` user PAT whose user is in the daemon’s realm, or a local token
Another host, cliqd not connected	A local token (anything else is refused with `403 LOCAL_ONLY`)
A web page (request with an `Origin` header)	Refused

Signals

Signal	Effect
`SIGINT` / `SIGTERM`	Graceful shutdown — stops the outbox and sync, deregisters from CliqHub, closes the store, exits
`SIGHUP`	In-place restart — tears down and re-runs startup without exiting the process

Environment variables

Variable	Purpose
`CLIQ_API_URL`	CliqHub API base (default `https://api.cliqhub.io`; `--hub` sets and remembers it)
`CLIQ_DAEMON_TOKEN`	Realm enroll token (`cliq_dt_…`). Stored as the daemon token on boot; cliqd never re-enrolls over it.
`CLIQ_DAEMON_ID`	Preferred daemon id when the store has none
`CLIQ_DAEMON_NAME`	Display name (overrides `--name`)
`CLIQ_DAEMON_PUBLIC_URL`	Public URL for this daemon (for Hub-dispatched runs)
`CLIQ_DAEMON_HOST`, `CLIQ_DAEMON_PORT`	Bind address (default `127.0.0.1:4900`; overrides `daemon.host` / `daemon.port`)
`CLIQ_DAEMON_WORKSPACE_ROOT`	Root for daemon-created workspaces (default `~/.cliqrc/workspaces`)
`CLIQ_DAEMON_LOG_DIR`	Log directory (default `~/.cliqrc/logs`)
`CLIQ_DAEMON_LOG_LEVEL`	`debug` \| `info` \| `warn` \| `error` (overrides `logging.level`)
`CLIQ_AGENTS_PATH`	Agents search path, colon-separated (`~/.cliqrc/agents` is always added last)
`CLIQ_ARTIFACT_MAX_MB`	Artifact size limit in MB (default `50`)
`CLIQ_ALLOW_REALM_OVERRIDE=1`	Same as `--allow-realm-override`
`CLIQ_STORE_SQLITE_PATH`	Override the database path (tests/CI)
`CLIQ_HOME`	Override the `~/.cliqrc` home directory (database, pid file)
`CLIQ_TELEMETRY_OFF=1`	Turn off telemetry
`NO_SYNC=1`	Same as `--no-sync`

Data

Path	Contents
`~/.cliqrc/data/daemon.db`	SQLite store — workspaces, teams, runs, settings, login session, local tokens, outbox
`~/.cliqrc/cliqd.pid`	PID file — prevents a second cliqd from starting
`~/.cliqrc/logs/daemon.log`	Daemon log
`~/.cliqrc/logs/runs/<daemon_id>/<run_id>.log`	Per-run logs
`~/.cliqrc/agents/`	Agents directory (always on the agents path)
`~/.cliqrc/daemon.json`	Optional, legacy: bind host/port, workspace root, log dir and level before the store loads. Prefer `cliq settings`.

There is no ~/.cliqrc/settings.json. More on logs: Logging.

CLI client → CLI
Local development → Local Development
Realm architecture → Realms
Credentials and enroll tokens → Auth
HTTP API → Daemon API tab
Hub control plane → Hub API

​Options

​Examples

​Modes

​How teams get installed

​Teams not on the realm’s team list

​Stopping a run

​Artifacts

​Local tokens

​Who can reach cliqd

​Signals

​Environment variables

​Data

​Related