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 run | When to choose it | What to read |
|---|---|---|
| Your computer (macOS or Linux) | one person, a trial, the model fits in memory | step 2 below, Run Cradle on your machine, Local deployment |
| Linux server | a shared cradle for several people | step 3 below, Remote server |
| GPU server | heavy models; the console connects through an SSH tunnel | Keys and models, Set up a GPU server |
| Docker Compose | server, Postgres, vLLM, SearXNG and file storage as one stack | step 4 below |
| Cradle cloud | no server of your own | step 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.1The 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/healthThe 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--portflag for another port. cradle: command not found: add~/.local/bintoPATH.
3. Linux server
curl -fsSL https://download.opencradle.ai/cradle-cli/latest/cradle-cli-install.sh | sudo shAs 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/healthIf 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 statusThe 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 healthHow 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 loginhas 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 --applyThe 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 updaterefuses to run: update there withgit pull && bun install. - The line
note: … failed … restart the server manually— the service was not restarted: restart it yourself or restart thecradle-serverprocess. - 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:
| What | Why |
|---|---|
pgdata/ | the embedded database (PGlite). With DATABASE_URL the database is not here — take a pg_dump of that database |
secret.key | the encryption key of provider keys; without it (or without CRADLE_SECRET_KEY) the stored keys cannot be decrypted |
auth/issuer.key | the signing key of people's tokens; without it the issued tokens stop working |
app-state.json, skills-custom.json | cradle 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.