Skip to main content
An agent with no instabox credentials and nobody at the keyboard registers by itself, prints a code for the account owner, and keeps working. Once the owner approves, from any device, the agent holds an ordinary API key of the owner’s account with the scopes the owner granted.
1

The agent registers

The default name is agent@<hostname>, and the default scopes are machines:read machines:write machines:delete images:read. The command prints a claim page and a code:
Relay the page and the code to the person and wait. The code works for 24 hours.
2

The owner approves

Open the page. If you are signed out, sign in or sign up with GitHub or Google first, and the page comes back. It shows the agent’s name, when and from which address it registered, and what it asks to do. Untick the permissions you do not want to give, then choose Approve or Deny.To decide from your own computer instead, sign in there and run:
3

The agent carries on

The command finishes on its own and stores the key in ~/.config/instabox/credentials.json. Every later instabox command uses it.
Approve only an agent you started yourself. The key appears on your API keys page under the agent’s name. When the agent is done, revoke the key there or with instabox keys rm.
Before approval, the agent has no account and no credential, so it cannot read or create anything. What it needs to plan with (templates, sizes, prices, and limits) is in these docs and in /llms.txt. An agent’s key never manages keys, workspaces, or billing. An account holds at most 20 active keys.
  • --no-wait prints the page and code and exits. With --json, it prints them as JSON. Running instabox login --agent again resumes the same registration instead of printing a second code.
  • A denial or an expired code ends with an error. Register again.
  • If the key cannot be stored, such as on a full disk, the command says so without printing the key and exits non-zero. Run it again within 10 minutes and the server hands over the same key. A key neither used nor stored within those 10 minutes is revoked.
--json prints the key itself, and --no-wait --json prints the claim token. Keep that output out of transcripts and logs.
POST /v1/auth/agent takes {"name", "email", "scopes", "expiresInDays"}, all optional. It answers claimToken, userCode, verificationUri, verificationUriComplete, interval, and expiresIn.Poll POST /v1/auth/agent/token with {"claimToken"} every interval seconds. It answers 400 with one of these errors:Then, once, it answers 200 with key (the secret, ibk_...), apiKey (its ID, name, and scopes), and the account’s userId and login. From then on, send the key as X-API-Key.

API keys

Scopes, workspaces and revoking.

Coding agents

Give each agent a machine of its own.