Setup

Install and update

Which install path to choose, how to check the server, how to update it and what a backup has to contain.

This page picks the install path and covers what is the same for every path: CLI login, the check, updating and the backup. Detailed steps for each path are on the pages the links lead to.

1. Choose an install path

Where the server will runWhen to choose itWhat to read
Your computer (macOS or Linux)one person, a trial, the model fits in memorystep 2 below, Run Cradle on your machine, Local deployment
Linux servera shared cradle for several peoplestep 3 below, Remote server
GPU serverheavy models; the console connects through an SSH tunnelKeys and models, Set up a GPU server
Docker Composeserver, Postgres, vLLM, SearXNG and file storage as one stackstep 4 below
Cradle cloudno server of your ownstep 5 below

2. Your own computer

You need curl. The installer sets up bun 1.4+ itself if it is missing. No root: everything goes under ~/.local/share/cradle.

curl -fsSL https://download.opencradle.ai/cradle-cli/latest/cradle-cli-install.sh | CRADLE_BIND=127.0.0.1 sh && ~/.local/bin/cradle-server --data-dir ~/.local/share/cradle/data --port 31416 --bind 127.0.0.1

The installer unpacks the server, creates the database, writes the key to ~/.local/share/cradle/data/client-credentials.json and puts the cradle and cradle-server commands into ~/.local/bin. If the machine has a user systemd session, the installer starts the server as a service itself, and the second part of the command answers that the port is taken — that is expected.

How to check.

curl http://127.0.0.1:31416/api/v1/health

The answer contains "ok":true, "serverVersion":"0.9.2" and "kind":"local".

If it did not work.

  • No answer: the server is not running — run the second part of the command (~/.local/bin/cradle-server …).
  • Port taken: it is held by the service (systemctl --user status cradle-server) or by another process; use the --port flag for another port.
  • cradle: command not found: add ~/.local/bin to PATH.

3. Linux server

curl -fsSL https://download.opencradle.ai/cradle-cli/latest/cradle-cli-install.sh | sudo sh

As root the installer puts the code into /opt/cradle and the data into /var/lib/cradle, creates the system service cradle-server and the links /usr/local/bin/cradle and /usr/local/bin/cradle-server. The key is in /var/lib/cradle/client-credentials.json. The installer reads the variables CRADLE_PORT, CRADLE_BIND, CRADLE_DATA_DIR, CRADLE_USER, CRADLE_SERVICE, CRADLE_INSTALL_DIR and CRADLE_SKIP_SYSTEMD=1.

Without CRADLE_BIND=127.0.0.1 the installer binds the server to 0.0.0.0:31416, that is, to every network interface and without TLS. Put a reverse proxy in front of it as described on the remote server page. The console treats a cradle whose API listens on anything but 127.0.0.1 as a GPU server — see Keys and models.

How to check.

systemctl status cradle-server
curl http://127.0.0.1:31416/api/v1/health

If it did not work. The service log is journalctl -u cradle-server; for an install without root, journalctl --user -u cradle-server.

4. Docker

The stack is described in the Docker Compose file of the repository clone: cradle-server, postgres (with pgvector), seaweedfs (files), searxng (search for agents) and inference (vLLM — needs an NVIDIA GPU and the nvidia-container-toolkit). The cradle server docker … commands look for this file from the repository root, and the installer archive does not contain it, so run them from a clone of the Cradle repository:

bun run cli:dev server docker build
bun run cli:dev server docker up
bun run cli:dev server docker status

The other subcommands are down and logs; running from a clone with bun run cli:dev is the same as calling cradle server docker ….

The administrator key is printed to the log once, at the first start:

bun run cli:dev server docker logs cradle-server | grep -i 'admin api key'

Default ports are 31416 (API) and 31417 (MCP). An external database instead of the bundled postgres is the DATABASE_URL variable plus the compose file for an external database (it sits next to the stack's main compose file in the repository clone) in CRADLE_COMPOSE_OVERRIDE.

How to check. docker compose … ps (or cradle server docker status) shows the services running, and curl http://127.0.0.1:31416/api/v1/health answers "ok":true.

If it did not work. cradle server docker logs cradle-server is the server log (logs keeps the stream open; leave it with Ctrl+C).

5. Cradle cloud

In the console: Cradles → the Cradle cloud card → Connect. The Free plan works with your own Claude, OpenAI and Kimi keys, Pro with the models of the cradle's pool (Keys and models).

How to check. The card shows the Reconnect and Disconnect buttons, and the team appears on the "Teams" page.

If it did not work. "The cloud is not configured on this site." means the site you opened the console on is not connected to the cloud. "Could not connect: …" carries the reason; for a 403 not_a_member see Sign-in, people and keys.

6. Log the CLI in and check the server

The cradle commands are a thin HTTP client: they call the server with a key. Take the apiKey field from client-credentials.json (it is a key with the admin:* scope):

cradle login --url http://127.0.0.1:31416 --key ck_live_...
cradle health

How to check. cradle login prints ✓ saved as "default" — server http://127.0.0.1:31416 v0.9.2 and team: <slug>; cradle health prints ✓ server … (v0.9.2) and the line agents: 0, models: 0, knowledge bases: 0.

If it did not work.

  • error: unauthorized — the key is wrong.
  • error: ECONNREFUSED … — nothing answers at that address.
  • error: No server configured — cradle login has not been run yet.

cradle login saves the address and the key before it checks them: after an error, run it again with the right values. Several servers — cradle servers list | use <name> | remove <name> and the --name flag of login.

7. Updating

cradle update
cradle update --apply

The first command only checks: it compares the version with the latest release and changes nothing. The second downloads the archive, verifies SHA256, installs the dependencies and restarts the service.

More flags: --no-restart (do not restart the service), --service-name <name> (cradle-server by default), --install-dir <path>. The service is restarted through systemctl --user if the unit is a per-user one, and through the system manager otherwise.

How to check. After --apply the command prints ✓ updated to <version> and restarted cradle-server, and cradle health shows the new version.

If it did not work.

  • Inside a git repository cradle update refuses to run: update there with git pull && bun install.
  • The line note: … failed … restart the server manually — the service was not restarted: restart it yourself or restart the cradle-server process.
  • The console says "Server … is outdated, need ≥ …" — update the server with this command.

8. What a backup contains

Copy the data directory (~/.local/share/cradle/data, /var/lib/cradle or the --data-dir value) with the service stopped while you copy:

WhatWhy
pgdata/the embedded database (PGlite). With DATABASE_URL the database is not here — take a pg_dump of that database
secret.keythe encryption key of provider keys; without it (or without CRADLE_SECRET_KEY) the stored keys cannot be decrypted
auth/issuer.keythe signing key of people's tokens; without it the issued tokens stop working
app-state.json, skills-custom.jsoncradle settings and your own skills
files/, skills/reply files and skill packages
models/downloaded GGUF files; they can be downloaded again

client-credentials.json and admin-key.txt contain keys — keep them as secrets.