Setup

Sign-in, people and keys

Signing in to the console, connecting a cradle, the first owner, inviting people, roles, and API keys with scopes.

Cradle has two kinds of access. People sign in to the console without a key: with their site account or with an e-mail code, and their rights come from their role in the organization of the cradle. Programs (bots, integrations, the CLI) call with an API key and scopes. A key is never typed into the console.

1. Sign in to the site

Open https://opencradle.ai/en/console. Enter your e-mail, press Send code, type the code from the e-mail and press Sign in. The Continue with Google button is not available on every site.

How to check. The console opens: on the left "Teams", "Cradles", "Security", "Settings".

If it did not work.

  • "You are on the waiting list" — the site administrator opens access to the console; the e-mail will come to your address.
  • "Too many requests. Wait a minute." — wait and request the code again.
  • "Code expired or missing. Request a new code." and "Invalid code." — request a new code with Send again.

2. Connect a cradle

Open Cradles.

  • A server on this very computer: the This computer card → Connect.
  • A server behind the SSH tunnel of a GPU server: the GPU server card → Connect (Keys and models).
  • Any other server: Add cradle → in the "New cradle" window fill in Name and URL (for example http://<host>:31416), press Test, then Add server.

A cradle that trusts the site (all of them do by default) lets you in without a second sign-in. Publish an address outside your computer over HTTPS — see Remote server.

How to check. The cradle card says "online", and the "TEAM → CRADLE" table below lists its teams.

If it did not work.

  • "unreachable" — there is no server at that address or the network blocks it: check curl <URL>/api/v1/health.
  • "Sign-in needed" — the cradle did not accept the site's token; press Sign in and follow step 4.
  • "You are not in any organization on this cradle" — nobody added you; steps 3 and 5.

3. The first owner

A cradle with no members at all goes to the first person with a valid token who comes from this same machine (an SSH tunnel to a GPU server counts too). That person becomes the owner of the organization default. Pressing Connect on the This computer card is enough for that.

For a server you reach over the network this does not happen — you get a 403 not_a_member. The operator with an admin:* key (for example, the installer's key) creates the owner in one of two ways:

A service environment variable — the owner is created at every server start:

CRADLE_BOOTSTRAP_OWNER=you@example.com

Or a command:

cradle members add --org default --email you@example.com --role owner

A new organization instead of default: cradle members create-org <slug> --owner <e-mail> [--name <name>] [--plan free|pro]. The list of organizations is cradle members orgs.

How to check.

cradle members list --org default

The table has your e-mail with the role owner.

If it did not work. error: organization not found — wrong organization slug: look at cradle members orgs. If members already exist there will be no automatic owner: add people with the command above.

4. Signing in to the cradle with a code

It is needed when the cradle does not trust the site (in a closed contour the trust is switched off with CRADLE_CONSOLE_ISSUER=off) or when you were added with cradle members add. The card says "Sign-in needed": press Sign in, enter the E-mail, press Get a code, enter "Code from the e-mail — 6 digits" and press Sign in.

The code is 6 digits, lives 10 minutes and allows 5 attempts. If the cradle has no mail configured (settings.smtp in app-state.json: host, port, secure, user, password, from), there is no e-mail, and the operator fetches the code:

cradle users code you@example.com

The same code is printed to the server log as the line [auth] login code for <e-mail>: <code>. Only a person who has been created can get a code: cradle users add <e-mail> or cradle members add ….

How to check. The cradle card says "online", the teams open.

If it did not work.

  • "The code did not match or has expired." — request a new one (Another e-mail, then Get a code again).
  • "The account is disabled by the operator." — cradle users enable <e-mail>.
  • "You are in no organization of this cradle. Ask its owner to add you" — step 5.
  • "The cradle did not answer." — check the address and the server.

5. Invite people

The operator with an admin:* key (<subject> in the last command comes from the SUBJECT column of the list):

cradle members add --org default --email colleague@example.com --role member
cradle members list --org default
cradle members remove --org default --subject <subject>

The person then adds the cradle in the console and signs in with a code (step 4). To close access temporarily use cradle users disable <e-mail> (sessions are revoked); cradle users enable <e-mail> brings it back; the list of people is cradle users list.

The role sets a person's rights:

RoleWhat it can do
memberthe working set of the console: messages, agents (read, change, run), knowledge bases, tickets (read, approve), conversations, models, reading teams, channels and settings
adminall of that plus managing the organization: teams, channels, risk rules, budgets, settings; adds and removes only members
ownereverything admin can; changes roles and removes admins; the last owner cannot be removed

The console has no members screen: manage them with the cradle members … commands above.

How to check. cradle members list --org default shows the person with the right role.

If it did not work. The person sees a 403 not_a_member — they are not in the organization or they sign in to another cradle; check the e-mail in the list.

6. API keys and scopes

A bot, an integration, a script or an MCP client needs a key. The operator with an admin:* key issues it. A key is bound to one team — by its id (not its slug):

cradle teams list --json
cradle keys create --name "site-bot" --scopes messages:read,messages:write --team <team-id>

In the teams list --json answer the team you need has an id field — put it into --team.

Without --team the command answers error: team not found: personal. The key is printed once (plaintext), the server keeps only the hash. An optional expiry is --expires-at <Unix milliseconds>. The list is cradle keys list, revoking is cradle keys revoke <id> (the full id is in cradle keys list --json).

A key can only hold these scopes:

ScopeWhat it opens
messages:writesend a message to the HTTP API: POST /api/v1/messages; MCP cradle_submit_issue
messages:readcollect replies GET /api/v1/messages/:chatId, GET /api/v1/admin/health, the event stream GET /api/v1/events
agents:read, agents:write, agents:executeread agents; create and change them; run one without a ticket (POST /api/v1/admin/agents/:id/execute)
kb:read, kb:writeread knowledge bases and search; create, upload, delete
models:read, models:writeread models and provider keys; register models and save keys
models:inferPOST /v1/messages and GET /v1/models (the Anthropic-compatible endpoint)
tickets:read, tickets:approveread tickets; approve, reject, reassign
conversations:readconversations and tasks; reply files GET /api/v1/files/:id
teams:read, channels:readsee teams and channel status
settings:read, settings:writeread and change cradle settings
admin:*everything, including issuing keys and managing people

The org:admin scope is part of a person's role; it cannot be given to a key (the answer is 400). A key with admin:* can choose the team with the header X-Cradle-Team: <slug>; other keys work only in their own team.

How to check.

curl -s -H "Authorization: Bearer ck_live_..." http://127.0.0.1:31416/api/v1/auth/me

The answer has "kind":"key", teamSlug and the list of your key's scopes.

If it did not work. 401 unauthorized — the key is wrong, revoked or expired; 403 with a missing field — the scope named there is not granted; unknown scope: … when issuing — the scope is not in the table above.