Skip to main content

​
Paths

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.

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

​
exec

Fetches a bound secret set from the local daemon, injects it into the environment, and replaces itself with the given command.
The caller must belong to the custos Unix group. Supports the {{custos.expand:...}} placeholder for passing variable names to wrapper commands — see Machine secrets.

​
authkeys

Prints the authorized key line for a login attempt. sshd calls this; you would only run it by hand to debug.
All three positional arguments are required — sshd supplies them from the connection via the drop-in’s token expansion. 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.

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

​
uninstall

Notifies the control plane, marks the host revoked, stops the service, removes the sshd hook, and removes the binary.
Details in Remove Custos from a host.

​
version

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