> ## 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.

# Daemon (cliqd)

> The long-lived daemon process that executes pipelines — options, modes, signals, tokens, and data paths.

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

`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`.

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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:

1. **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.

2. **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 |

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
# 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](/guides/logging).

***

## Related

* CLI client → [CLI](/cli)
* Local development → [Local Development](/local-development)
* Realm architecture → [Realms](/realms)
* Credentials and enroll tokens → [Auth](/auth)
* HTTP API → **Daemon API** tab
* Hub control plane → [Hub API](/hub-api)


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