Setup

Keys and models

Local models, providers by key, a GPU server, model roles, the team contour and the team's models — in the order you set them up.

An agent needs a model. It comes from one of three places: downloaded to the server (GGUF), a provider by key (Claude, OpenAI, Gemini, Grok), or a GPU server. Which agent gets which model is decided by model roles and "Team models".

1. What you need at minimum

  • one chat model — it is also the risk classifier: the cradle takes qwen3-4b-q4 if it is installed, otherwise a model with the role classifier, otherwise the smallest chat model;
  • for knowledge bases, a model with the role embedding (Knowledge bases);
  • for voice messages, a model with the role stt.

How to check.

cradle models list

A table with the columns REF, PROVIDER, ROLE, EXTERNAL-ID, CTX, SIZE. An empty table prints "no models installed or registered".

If it did not work. Without a chat model a message is not lost, but no agent answers it: the ticket waits for an operator with the reason Агент не сформировал черновик ответа. (the server writes it in Russian; it means "the agent did not produce a draft reply"; see Waiting for decision).

2. Download a local model

In the console: Cradles → the cradle's card → Keys and models → the link + Add a model. The GGUF catalog opens with a verdict for the server's hardware; the model you need has a Download button.

The same with commands:

cradle models list --catalog
cradle models check qwen3-4b-q4
cradle models pull qwen3-4b-q4
cradle models pull qwen3-embedding-0.6b-q8

list --catalog shows the catalog with a hardware verdict (fits, tight, won't run), check gives the verdict for one model. qwen3-4b-q4 is the chat model and the classifier, ~2.5 GB, needs ~6 GB of RAM; qwen3-embedding-0.6b-q8 is an embedding model, ~0.7 GB.

The files live in <data directory>/models. bge-m3-q4 works instead of qwen3-embedding-0.6b-q8.

The console shows the GGUF catalog only for a cradle it considers local. A cradle whose API listens on anything but 127.0.0.1 (an install under root with the default 0.0.0.0) is treated by the console as a GPU server and gets no catalog: download with cradle models pull. The cradle kind can be set explicitly with the service environment variable CRADLE_KIND=local.

How to check. cradle models list shows the model with PROVIDER llama-cpp, and it appears in the "Models" list of the cradle's card.

If it did not work. The verdict won't run means the model does not fit in memory: pick a smaller one. When a download fails, cradle models pull prints the reason in its progress line.

3. Connect provider keys

In the console: Cradles → the cradle's card → Keys and models → the "PROVIDER KEYS" block. Expand a provider (OpenAI, Anthropic, Gemini, Grok (xAI), Remote GPU (llama.cpp/vLLM)), enter a Label and the key in the "Add API key" block, press Save & verify. Then Load models, tick the models you need and press Add N to catalog — they appear in the "Models" list of this cradle.

The block is there for a cradle of the "local" and "cloud" kinds. For a GPU server (and for a cradle the console considers a GPU server, see above) it is replaced by "Model services on the server"; to get the keys block, set CRADLE_KIND=local on the service.

Keys are stored encrypted: the encryption key is CRADLE_SECRET_KEY or the file secret.key in the data directory (it is created by itself; put it into the backup). If the console says "Encrypted credential storage unavailable", give the keys as service environment variables: OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, XAI_API_KEY — the server picks them up at start.

Amazon Bedrock needs no key: the cradle calls it under the AWS role of its host, and in the console it is visible to the operator only (admin:*).

A model can also be registered with a command, without the console:

cradle models add claude-sonnet-5-5:cloud --provider anthropic --external-id claude-sonnet-5-5 --role general

--role defaults to coding; set it explicitly.

How to check. Next to the provider there is the mark "✓ verified", the added models are in the card's "Models" list; cradle models list shows them with PROVIDER anthropic (or another).

If it did not work. Next to the key there is the mark "error", the reason is visible on hover; the message "Verify failed: …" means the provider rejected the key.

Team contour

A team has a contour: closed (external providers are unavailable) or cloud. A team on a local cradle is created as closed, on a cloud cradle as cloud. An agent of a closed-contour team does not get a cloud model: the request to it fails with Команда «…» — закрытый контур: провайдер «…» недоступен… (the team is a closed contour: the provider is unavailable), and the model placement reports Модель «…» внешняя, а команда в закрытом контуре. (the model is external, and the team is in a closed contour). The console has no switch; the operator changes the contour:

cradle teams update <slug> --contour cloud

When creating: cradle teams create <slug> --contour cloud.

4. Connect a GPU server

Details and screenshots are on the page Set up a GPU server. In short, step by step:

On the GPU server install Cradle (the server listens on 127.0.0.1 only), log the CLI in (apiKey is in ~/.local/share/cradle/data/client-credentials.json) and connect the models that are already running (vLLM, Ollama, llama.cpp, TGI):

curl -fsSL https://download.opencradle.ai/cradle-cli/latest/cradle-cli-install.sh | CRADLE_BIND=127.0.0.1 sh
cradle login --url http://127.0.0.1:31416 --key <apiKey>
cradle models discover --connect gpu

The command asks the Docker ports and the 127.0.0.1 ports from the list 8000, 8001, 8080, 8081, 11434, 1234, 5000, 30000 (your own list is the variable CRADLE_INFERENCE_PORTS) at /v1/models and downloads nothing. The key of a protected container (VLLM_API_KEY, API_KEY, --api-key) is read by the cradle itself from docker inspect. A server on another machine: cradle models discover --base-url http://host:8000 --key <key> --connect <name>. Whisper and Parakeet get the role stt; bge, e5, nomic and gte get embedding.

On your own computer open the tunnel and keep it open while you work in the console:

ssh -N -L 31420:127.0.0.1:31416 user@gpu-host

In the console: Cradles → the GPU server card → Connect. You sign in with the same account as on the site; the first person through the tunnel becomes the owner (Sign-in, people and keys).

How to check. The card says "tunnel open", and the "MODEL SERVICES ON THE SERVER" block lists services with the status "Available"; on the server cradle models list shows rows with PROVIDER remote-gpu. The occupied video memory is shown by cradle gpu who --totals (needs nvidia-smi).

If it did not work.

  • No model servers found … — no port on the server answers: start a model or give the address with --base-url.
  • The status "Key required" — connect again with --key (or enter the key in the Connect dialog).
  • "tunnel closed" — the ssh command ended; run it again.
  • error: No server configured on the server — cradle login was not run.

5. Model roles

Every model has a role: classifier, general, coding, reasoning, embedding, stt, stt-stream. The role is set by the catalog (GGUF), by the automatic detection in models discover, by a provider's catalog, or by the --role flag of cradle models add. The role stt-stream is streaming speech recognition over a WebSocket.

A requirement of an agent or a team picks models by roles:

Requirement (as in the console)Matching roles
"General"general, coding, reasoning, classifier
"Coding"coding
"Reasoning"reasoning or a model marked as reasoning
"Embedding"embedding
"Speech-to-text (stt)"stt

6. Team models

Open the team page (the Team tab, the "Canvas" view): while no agent is selected, the "Team models" block is visible on the right — one select per requirement; "Any suitable" by default. In an agent's form there is the field "Requirement" ("General", "Coding", "Reasoning") and the field Model: the value "By the team's requirement" leaves the choice to the map.

The order of picking for an agent: the model named on the agent itself → the "Team models" map → the first suitable installed model of the cradle (recently used first). An explicit choice that does not match by role is not forbidden but comes with a warning.

How to check. On the team page no agent shows a model warning.

If it did not work. An agent's warning names the reason: Нет модели для требования general на этой колыбели — установите чат-модель или задайте модель агенту. (there is no model for the requirement on this cradle) — install a model (steps 2–4); Модель … внешняя, а команда в закрытом контуре. (the model is external, and the team is in a closed contour) — switch the contour (step 3).