Deploy with Docker Compose

The packaged Compose path creates one isolated Nautilo stack: Nautilo, Logto, two PostgreSQL services, persistent volumes, and one first owner. Run it on your machine or on a Docker host reached over SSH.

Stable release

Install the current signed stable CLI from the Administrator quickstart. Check deploy --help before creating infrastructure. The CLI verifies the signed stable Server channel for bare deploy and upgrade commands; an exact immutable image remains available as an explicit override.

Choose your setup path

Manual setup: create a profile, deploy with browser claim, then add API keys in Server admin. No TOML file is needed.
Automated setup: create a profile, then use the protected config path to create the owner and supply optional API keys from a file.

Choose one path for a new Server. Once its owner exists, use Server admin to change keys rather than running the other setup path.

Before you begin

You need the Nautilo CLI, Docker Engine with the docker compose plugin, and a password manager. A remote deployment also needs a dedicated operator SSH key, an SSH-accessible Docker host, DNS, and firewall preparation.

nautilo --version
nautilo profile --help
nautilo deploy --help
docker version
docker compose version

Local Docker

nautilo profile add my-nautilo \
  --transport=local \
  --lifecycle=compose \
  --instance-id=my-nautilo \
  --yes

Do not invent a port. The named instance allocates its complete collision-safe port bundle.

Remote SSH/Docker

nautilo profile add my-nautilo \
  --transport=remote \
  --lifecycle=compose \
  --instance-id=my-nautilo \
  --ssh-host=203.0.113.10 \
  --ssh-user=nautilo \
  --ssh-identity-file="$HOME/.ssh/nautilo_operator" \
  --remote-path=/opt/nautilo \
  --domain=nautilo.example.com \
  --base-url=https://nautilo.example.com \
  --https=letsencrypt \
  [email protected] \
  --yes

Use generic, dedicated key names. Keep host authority in SSH/Docker; Nautilo application ownership does not grant Linux administrator access.

For a public VPS, complete the Linux Server and Let's Encrypt preparation before creating this profile. For a private network with no HTTPS, use the narrower LAN-only HTTP guide; do not adapt the public browser-claim command to a plaintext LAN address.

Manual setup: deploy and claim

nautilo deploy \
  --profile my-nautilo \
  --owner-mode claim \
  --finish guide

Bare deploy verifies the signed stable Server manifest and selects its exact immutable image digest before creating deployment state. To choose a specific release, add --image ghcr.io/agentsea/nautilo-runtime@sha256:<64-lowercase-hex-digest> to the deploy command. The image selection belongs to that operation, not to the profile.

--owner-mode claim selects browser setup even if ~/.config/nautilo/deploy.toml already exists. The file is not used for this path. The CLI opens setup automatically in an interactive terminal.

Follow Create the first owner. Deployment is complete only when the target reports owner-bound; healthy containers alone are not completion.

Add API keys in Server admin

After claiming the Server, sign in as an Owner or Admin and open Server admin → API Keys. The Server Guide's API Keys button opens the same page. Choose Add key for a service, paste its key, choose Save, then Validate all. You can complete this step without a TOML file.

See the API Keys screenshot and full steps.

Verify and resume

nautilo status --profile my-nautilo
nautilo claim resume --profile my-nautilo --finish guide

Require the expected instance, healthy runtime, claimRequired: false, a working owner sign-in, and one useful model-backed action. Resume the same profile after interruption; never create a second stack to escape an expired claim.

Automated setup with a protected file

Use this alternative for a new, unclaimed Server, after creating either the local or remote profile above. Skip the manual deploy-and-claim command.

Download and fill the Local / Docker Compose setup file on the computer running the CLI. Supply the permanent owner password and approval PIN, and fill or remove each optional provider block. Save the password before deployment; first sign-in does not force a replacement. Keep passwords and PINs out of terminal commands.
Choose a new, nonexistent result filename in that private folder, outside Server storage and backups. The CLI creates the result with mode 0600; do not pre-create it.

Run:

nautilo deploy \
  --profile my-nautilo \
  --owner-mode config \
  --owner-config "$HOME/.config/nautilo/deploy.toml" \
  --owner-result "$HOME/.config/nautilo/my-nautilo-owner-result.json" \
  --finish guide

Require owner-bound and the recovery result path. Save the one-time codes from that private file in your password manager. Sign in with the owner handle and permanent password supplied in the TOML.
Validate supplied keys in Server admin → API Keys, connect a client, and complete one model-backed action. Check status and sign in again as described above.

For unattended deployment, add --json --no-open-browser. Recovery codes are written to --owner-result, not the JSON summary. If interrupted, follow the exact recovery command printed by the CLI, keeping the same config and result paths. Do not switch ownership paths or delete an existing result to retry.

Day two

nautilo logs --profile my-nautilo --follow
nautilo upgrade --profile my-nautilo
nautilo destroy --profile my-nautilo

upgrade is the safe day-two transaction with backup, acceptance, and rollback. Bare upgrade selects the latest signed stable release; use upgrade --image <immutable-digest> for an intentional exact-image move. A soft destroy preserves volumes. nautilo destroy --hard --yes is destructive and removes volumes and first-owner custody.

Read secret custody and advanced operations before moving important work onto the Server.

Deploy with Docker Compose

On this page