Skip to main content
End to end this is: run the control plane, enroll a host, register an SSH key, grant host.access. Each step links to its full reference. Custos ships a web app alongside the API, and everything here that is not a shell command on a server — creating the enrollment token, registering a key, granting access — can be done there instead of with curl. This page uses curl so each step is unambiguous about what is actually being asked of the control plane.
1

Install the control plane

Download the latest Linux amd64 control-plane binary:
See Control plane install for the full procedure.
2

Generate keys and set the environment

This prints CUSTOS_MASTER_KEY, CUSTOS_SIGNING_PRIVATE_KEY, and CUSTOS_SERVER_TRANSPORT_PRIVATE_KEY, plus CUSTOS_SERVER_TRANSPORT_PUBLIC_KEY to configure on clients. Supply those, along with CUSTOS_DATABASE_URL and CUSTOS_LISTEN_ADDR, through your shell, service manager, or deployment platform — Custos does not read .env files itself. Full list in Configuration.
3

Migrate, seed an admin, and serve

migrate up must run before create-admin. create-admin prints a generated password if you did not pass --password.
4

Install the daemon on the host

This runs as root once: it installs /usr/local/bin/custosd, creates the custos system user and /var/lib/custos, writes the systemd unit, and wires sshd’s AuthorizedKeysCommand. Nothing talks to the control plane yet.Manual and pinned-version alternatives in Host install.
5

Create an enrollment token

Do this in the web app, or against the API directly. Either way you are creating the same single-use token carrying the host’s managed Unix accounts:
Save the returned token. Accounts are declared here and stamped into every snapshot the host receives.
6

Enroll the host and start it

Enrollment generates the host’s Ed25519 identity key and X25519 encryption key and registers only the public halves.
Enroll as the custos user, not with plain sudo custosd enroll. Plain sudo writes root-owned state under /var/lib/custos, and the service runs as custos.
7

Grant SSH access

Register the user’s SSH public key with POST /keys, then grant them host.access on the host with POST /grants — or do both in the web app. ssh in: the login is now gated by Custos.If a connected daemon still reports cached ssh keys: 0, force a resync with POST /hosts/{id}/refresh. The response includes key_count; 0 means the control plane has no active host.access grant plus matching public key for that host. See Grant SSH access.

​
Next

​
Local development shortcut

Skip install and systemd entirely and run the daemon directly:
Set CUSTOS_ENCRYPTION=off to disable Custos’s additional API payload encryption in local development. This does not disable HTTPS/TLS or at-rest vault encryption.