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

# custosd CLI

> Host daemon subcommands and flags.

```
usage: custosd <install|uninstall|enroll|run|exec|authkeys|apply-update|status|version> [flags]
```

## Paths

| Path | Purpose | Flag default | Used by `install` |
| - | - | - | - |
| state directory | enrollment, keys, key cache | `/var/lib/custos` | `/var/lib/custos` |
| authkeys socket | queried by sshd | `/run/custosd.sock` | `/run/custos/custosd.sock` |
| secrets socket | queried by `custosd exec` | `/run/custos/secrets.sock` | `/run/custos/secrets.sock` |

<Note>
  The authkeys socket's compiled-in flag default and the path a standard `install` deployment actually
  uses differ. `install` writes `RuntimeDirectory=custos` into the unit — so systemd creates
  `/run/custos` owned by `custos` — and passes `--socket /run/custos/custosd.sock` explicitly in both
  `ExecStart` and the sshd drop-in. Only a hand-rolled `custosd run` falls back to `/run/custosd.sock`.
</Note>

## `install`

One-time root setup: creates the `custos` system user, copies the binary to
`/usr/local/bin/custosd`, creates the state directory owned by `custos`, writes the systemd unit,
then writes, validates, and reloads the sshd drop-in. Idempotent.

```bash theme={null}
sudo custosd install
```

| Flag | Default | Notes |
| - | - | - |
| `--ssh-user` | `custos` | the `AuthorizedKeysCommandUser` |

Must run as root. The drop-in it writes bakes in the `--dir` and `--socket` values so `authkeys`
works on non-default layouts.

## `enroll`

Registers the host with the control plane. Generates the host's Ed25519 identity key and X25519
encryption key and sends only the public halves. Runs unprivileged, as the `custos` user.

```bash theme={null}
sudo -u custos custosd enroll \
  --control-plane https://custos.example.com \
  --token "$ENROLLMENT_TOKEN" \
  --dir /var/lib/custos
```

| Flag | Default | Notes |
| - | - | - |
| `--control-plane` | — | control-plane base URL |
| `--token` | — | admin-issued, single-use enrollment token |
| `--hostname` | system hostname | name to register |
| `--dir` | `/var/lib/custos` | state directory |

<Warning>
  Always pass an absolute `--dir`, and run as `custos` rather than root. Under `sudo`, `~` expands to
  the wrong home and the state ends up unreadable by the service user.
</Warning>

Keys are persisted before config, so a rejected enroll leaves a working identity intact.

## `run`

Runs the daemon in the foreground: holds the WebSocket to the control plane and serves both local
sockets. Normally started by systemd; run it directly to skip `install` during development.

```bash theme={null}
custosd run --dir /var/lib/custos
```

| Flag | Default | Notes |
| - | - | - |
| `--dir` | `/var/lib/custos` | state directory |
| `--socket` | `/run/custosd.sock` | authkeys socket path |
| `--secret-socket` | `/run/custos/secrets.sock` | secrets socket path |
| `--dbq-bin` | `dbq` | executable used for backup jobs |

## `exec`

Fetches a bound secret set from the local daemon, injects it into the environment, and replaces
itself with the given command.

```bash theme={null}
custosd exec --set app-prod -- /usr/local/bin/app
```

| Flag | Default | Notes |
| - | - | - |
| `--set` | — | secret set to inject as environment variables |
| `--secret-socket` | `/run/custos/secrets.sock` | daemon secrets socket |
| `--timeout` | `30s` | how long to wait for the daemon to have the set |

The caller must belong to the `custos` Unix group. Supports the `{{custos.expand:...}}` placeholder
for passing variable names to wrapper commands — see [Machine secrets](/custos/custos/guides/machine-secrets).

## `authkeys`

Prints the authorized key line for a login attempt. sshd calls this; you would only run it by hand
to debug.

```bash theme={null}
custosd authkeys <user> <keytype> <keyblob>
```

All three positional arguments are required — sshd supplies them from the connection via the
drop-in's token expansion.

| Flag | Default | Notes |
| - | - | - |
| `--dir` | `/var/lib/custos` | state directory |
| `--socket` | `/run/custosd.sock` | daemon socket path |

The drop-in written by `install` passes `--dir` and `--socket` explicitly, so `authkeys` keeps
working on non-default layouts.

Retries the socket, then falls back to the last-known-good cache file, so a control-plane outage
does not lock out every host.

## `status`

Reports enrollment state, connection state, and cached key count.

```bash theme={null}
sudo -u custos custosd status --dir /var/lib/custos
```

| Flag | Default | Notes |
| - | - | - |
| `--dir` | `/var/lib/custos` | state directory |

## `apply-update`

Verifies and swaps in a staged binary. Runs as root from the unit's
`ExecStartPre=+custosd apply-update`; not meant to be run by hand. See
[Daemon updates](/custos/custos/hosts/updates).

## `uninstall`

Notifies the control plane, marks the host revoked, stops the service, removes the sshd hook, and
removes the binary.

```bash theme={null}
sudo custosd uninstall --purge
```

| Flag | Default | Notes |
| - | - | - |
| `--purge` | off | also remove the state directory and the `custos` user |
| `--skip-control-plane` | off | do not notify the control plane |

Details in [Remove Custos from a host](/custos/custos/hosts/uninstall).

## `version`

```bash theme={null}
custosd version
```

The daemon also reports this build string to the control plane on every connect, which is what
`hosts.agent_version` reflects.


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