Install the server
The server is one container with SurrealDB and Valkey beside it, plus an S3-compatible bucket for recordings. Everything stays in your environment.
What you need
- A Docker host. Linux with Docker Engine 24+ and the Compose plugin. 2 vCPU and 4–8 GB RAM is plenty for hundreds of hosts. The server relays web terminal and gateway sessions, so give it more if many run at once.
- Registry access.
docker login harbor.sageisg.comforharbor.sageisg.com/keyreeve/server(amd64 and arm64). - Two DNS names: one for the web interface, behind your TLS reverse proxy, and one for the agent service (see Two addresses, not one).
- A TLS reverse proxy for the web address. It terminates TLS and forwards plain HTTP to port 4382, including WebSockets — the browser terminal needs them.
- An OIDC identity provider such as Entra ID or Keycloak. SSH certificates are only issued to people who signed in with SSO.
- An S3-compatible bucket for session recordings.
- A licence. Without one, a server allows a single named user — enough to sign in and install the licence. See Licensing.
[!TIP] Turn on versioning or object lock on the bucket if you want recordings protected from deletion at the storage layer. Keyreeve detects tampering, but it cannot prevent it.
Set it up
cp deploy/.env.production.example deploy/.env && chmod 600 deploy/.env
# generate the secrets (Linux sed; on macOS use: sed -i '')
for v in SURREAL_PASS REDIS_PASSWORD BOOTSTRAP_ADMIN_PASSWORD; do
sed -i "s|^$v=$|$v=$(openssl rand -hex 32)|" deploy/.env; done
sed -i "s|^KEYREEVE_ENC_KEY=$|KEYREEVE_ENC_KEY=$(openssl rand -base64 32)|" deploy/.env
# then edit deploy/.env: KEYREEVE_VERSION and KEYREEVE_DOMAIN
docker login harbor.sageisg.com
docker compose -f deploy/docker-compose.production.yml --env-file deploy/.env up -d
docker compose -f deploy/docker-compose.production.yml --env-file deploy/.env ps
Compose refuses to start while any required value is empty. The server waits for SurrealDB and Valkey to be healthy, then creates the SSH user CA and host CA on its first start.
[!WARNING] Copy
KEYREEVE_ENC_KEYinto your secret manager now. It seals both SSH CA keys and every stored secret. Without it a database backup cannot be restored: every person would need new certificates and every host would have to be enrolled again under new CAs.
To scan uploads for malware, also start the bundled ClamAV with --profile antivirus on the same up -d command (the first start downloads the signature database).
Two addresses, not one
Keyreeve answers on two addresses, and they should be different hostnames.
- The web address is what people use in a browser. It can sit behind a WAF that asks them to sign in. Set it as the External URL under Admin → Settings → Security.
- The agent service address (port 4388) is what host agents, the agent installer, the CLI and the desktop app use. Machines cannot pass a WAF login, so publish port 4388 directly or through a TCP passthrough (nginx
stream, HAProxymode tcp) — never a proxy that terminates TLS, because agents use mutual TLS with the server. Set it under Admin → Agent service, where Test checks that it answers. Install commands aren't given out until it is set.
After the first start
- Sign in as the bootstrap administrator from
deploy/.env. - Under Admin → Settings → Security, set the External URL (sign-in redirects are built from it), turn on Trust X-Forwarded-Proto / X-Forwarded-For, and list your proxy under Trusted reverse proxies — until then, rate limits and the audit log see the proxy's address for everyone.
- Install your licence under Admin → License.
- Add your identity provider under Admin → OIDC providers (the redirect URI is shown on the form), then map an identity-provider group to the
adminrole under Admin → Role mappings and sign in with SSO. - Point Admin → Settings → S3 storage at your bucket, and use Test. If you started ClamAV, set the clamd address to
clamav:3310under Settings → File uploads & antivirus and turn scanning on. - Set the Agent service address, then the fleet's defaults under Admin → Fleet settings before enrolling hosts.
The bootstrap administrator is re-created from the environment on every start. That is deliberate: it is the way back in when SSO is unavailable.
More than one server
With an Enterprise licence, several Keyreeve servers can run as one cluster for high availability, set up under Admin → Cluster with one-time join tokens. Servers talk to each other on port 4387 over mutual TLS; every server is a full peer, and host agents and the desktop app fail over between them.

