What is what
Cradle Studio, cradle-server and the cradle CLI — three parts of the system, where each one is installed, and what you do not need to install at all.
Before installing anything, it helps to tell three things apart. The names look alike, but the roles differ — and they go on different machines.
The three components
| What it is | Where it lives | Installed from | |
|---|---|---|---|
cradle-server | The daemon. Holds the SQLite database, the models, RAG and the channels (Telegram, widget, HTTP API). The only component that actually does work | on the server | the cradle-cli package |
cradle | A thin HTTP client. It has no database and loads no models — every command is a call to some server's /admin/* namespace | anywhere: on the server and on your laptop | the same cradle-cli package |
| Cradle Studio | The desktop app (Electron + React). Same engine inside, but embedded — with its own local database and models | on your workstation | a separate DMG / EXE installer |
The package is called cradle-cli, but it ships both binaries — the daemon
and the client. The name is historical: it comes from the prefix in the
downloads bucket.
Why the CLI ends up on the server too
cradle is not the "desktop half". It is the tool for driving a server from
anywhere: on the server itself it talks to localhost:31416, from a laptop to
http://<server-address>:31416. The commands are identical.
It is also how deployment happens: cradle server init is not data work but an
operator command that creates the database, the first API key and the systemd
unit. That is why the CLI is needed on the server from the start.
What is not connected to what
The desktop app and the server are not parts of one installation. They are two independent ways to run the same engine:
- Laptop only, working locally → install Cradle Studio.
No server deployment needed: the app starts an embedded
cradle-serveritself. - Shared server, heavy models, several people →
deploy
cradle-serverand connect to it from Studio or the CLI. The DMG does not belong on the server.
The usual sequence
- On the server (once) — the installer puts
cradle-serverandcradlein place, creates the database and issues the first admin key. - Start the daemon — through systemd (with root) or by hand with
cradle-server. - Connect a client — either:
cradle login --url http://<server-address>:31416 --key ck_live_..., thencradle agents,cradle models pull,cradle health;- or Cradle Studio if you prefer a GUI.
Step 3 works the same from the server and from a laptop — one command, different
--url.