#Daemons in Hub

A daemon is one of your machines running the Clisbot daemon. Enroll it once with your Hub organization, then Routes and Automations can run agents on it, and Members you grant can use it.

#Connect

Run this on the machine with the daemon already running:

clisbot hub connect https://hub.example.com

Open the printed URL (the code is filled in automatically) and approve the Host, organization and Hub permissions as an organization owner/admin. The CLI then enrolls the Host and returns its current status. If it says connecting, the daemon finishes in the background and this page follows its progress. There is no preliminary login or second terminal confirmation. Non-TTY/Docker exec -T and --json follow the same flow; keep the command running while approving in a browser.

The single-use token is bound to this Host's identity and approved permission set, and expires with the request after 10 minutes. The daemon retains its own relationship credential. This flow does not create a CLI administration credential or use a previously stored CLI login. Default Hub-on-Host permissions are hub.execute, daemon.read, workspace.read, workspace.write, workspace.manage; override with --permission <permission...>. Human Host/Project access is managed separately.

Follow a slow connection in Hub → Hosts. After enrollment, hub status and rerunning connect require an authorized daemon connection (local IPC or a managed access ticket). If the approval result was lost before enrollment, start a new request. See Quickstart for the rest of setup.

A daemon's identity (its server ID and key) lives in its CLISBOT_HOME. Copying that directory to another computer, cloning a VM, or baking it into a container image copies the identity too. Hub refuses to enroll a second daemon with a server ID another Host in the organization already uses, and names that Host. On the copied computer, reset the identity and connect again:

clisbot daemon stop
clisbot daemon reset-identity
clisbot daemon start
clisbot hub connect https://hub.example.com

reset-identity removes server-id, daemon-keypair.json, and hub-relationship.json from CLISBOT_HOME. It refuses while the daemon runs or while CLISBOT_SERVER_ID is set, since that variable would restore the same ID. Hub also accepts connection details from a daemon only for the identity it enrolled with.

Hub derives the daemon's initial slug from its hostname. If that slug is already used in the organization, Hub adds a short daemon ID suffix. You can rename the daemon later in Hub.

Each daemon has two identifiers: an immutable generated ID and a friendly slug. Hub normalizes slugs with lowercase words joined by hyphens, so Build Studio becomes build-studio. The dashboard shows the slug. Configuration accepts either the slug or the immutable ID.

You can rename the slug later without changing the daemon ID. Configuration referencing the slug must be updated after a rename; references using the immutable ID remain valid.

In Clisbot, open Settings → Hosts → Rename with an organization Owner or Admin account. The dialog changes the shared Hub name and reports name conflicts inline. Daemon Administrator access alone does not grant organization configuration authority. Hosts following the shared name update without reconnecting; a local name chosen in Host Appearance stays personal to that app.

For team use, check the Host's Managed access setting, then grant Members or Teams the Host or Projects they need. Creating Projects needs Full access on the Host within its folder policy, or Owner/Administrator authority. Developer on an existing Project creates Workspaces/worktrees there. See Managed access for levels, Agent limits and reviewing older grants.

For unattended setup, inject an organization API key restricted to daemons:enroll without storing it:

CLISBOT_HUB_URL=https://hub.example.com CLISBOT_HUB_API_KEY=clisbot_pk_... clisbot hub connect

Origin precedence is explicit [origin], CLISBOT_HUB_URL, then active stored login; with none of these it stops and asks for a Hub URL. An explicit --api-key <secret> takes precedence over CLISBOT_HUB_API_KEY. Stored CLI credentials are not used for connection.

Check and undo:

clisbot hub status
clisbot hub disconnect
clisbot hub disconnect --force   # drop local authority when Hub is unreachable

One daemon has one Hub relationship. Repeating connect for the same Hub reuses it without changing permissions; connecting to a different Hub requires an explicit disconnect first.

clisbot hub logout removes the active CLI login. The daemon's relationship is a separate identity and stays connected.

In an interactive terminal, logout offers to disconnect a daemon enrolled with the same Hub. Accepting disconnects first and then deletes the login, so a failed disconnection keeps your credential. Declining removes only the login.

Noninteractive and --json logout never disconnect implicitly:

clisbot hub logout --disconnect-daemon           # remove both identities
clisbot hub logout --disconnect-daemon --force   # drop local authority when Hub is unreachable

#Let Hub run agents on it

hub.execute lets Hub start agents on the daemon. clisbot hub connect grants it by default. Revoke or grant it from the machine at any time:

clisbot hub permissions list
clisbot hub permissions grant hub.execute
clisbot hub permissions revoke hub.execute

Without it, Hub keeps the daemon for identity and presence only. Hub security covers what the permission allows once granted.

#Reference it from configuration

environments:
  dev:
    kind: daemon
    daemon: my-macbook
    cwd: /Users/you/code/your-repo

daemon accepts the friendly slug or immutable ID within the same organization. It resolves to the immutable daemon ID when the configuration activates, so a daemon that no longer exists fails activation instead of failing at dispatch.

cwd is a path on that machine. Hub does not clone anything for you; the directory must already exist.

To keep executions off your working tree, add a worktree:

worktree:
  mode: branch-off
  newBranch: trigger-${{ clisbot.execution.id }}
  base: origin/main

${{ clisbot.execution.id }} renders the execution's UUID, so every execution gets its own branch off origin/main.

Environment fields lists what newBranch accepts. See Git worktrees for setup hooks and scripts.

#What Hub owns

For agents it dispatched, Hub owns creation, reconnect recovery, output observation, and completion. Agents you start yourself are untouched.

If Hub loses the create response, or the daemon restarts mid-execution, Hub resends the same create intent with the same execution id. The daemon returns the existing agent rather than running the prompt again. An agent that closed or errored is recorded as interrupted; Hub never silently starts a second one.

#Status

Status	Meaning
Approval required	The CLI is waiting for you to approve the code
Connected	Online and accepting dispatch
Offline	Enrolled but not currently connected
Revoked	Access removed from Hub

An Automation event that arrives while a daemon is offline fails dispatch with daemon_not_connected. Its run shows in Runs; the trigger must fire again. This differs from the channel's durable ingress queue. Current app/API Automation saves do not check live provider/model availability. The legacy configuration-bundle installer checks named agents against the daemon and can refuse activation while it is offline.

Revoking from Daemons → Revoke daemon ends the relationship from Hub's side. The daemon keeps running your local agents.

#Advanced CLI login

Use hub login only when intentionally granting durable CLI administration access, such as configuration export or supported API operations. It grants all five Public API scopes, has no automatic expiry, and does not add a Host. Read API authentication before using it. hub logout only removes the local credential; revoke it in Hub → Configuration → API keys to end its server-side authority. Credentials from older onboarding versions remain valid until revoked.