CLI, MCP server, and HTTP API
The CLI, the MCP server, and the HTTP API run the same operations.
CLI commands
| Command | What it does |
|---|---|
devboxes signup | Creates an account and signs you in. With an email and a password, the six-digit code that devboxes emails you finishes the account. |
devboxes login | Signs in. |
devboxes logout | Signs out. |
devboxes commands | Lists all operations. |
devboxes describe <operation> | Shows what one operation takes and returns. |
devboxes invoke <operation> | Runs an operation. In a terminal without --input, it asks for the input field by field, and then for the Blueprint inputs and the issue that the task needs. Scripts pass the JSON input with --input. |
devboxes connect [provider] | Connects a model account by signing in with the provider or with an API key. In a terminal, it asks for the provider, the Organization and the account's name. Outside a terminal, it fails with PROVIDER_REQUIRED, ORGANIZATION_REQUIRED or LABEL_REQUIRED. |
devboxes mcp | Starts the MCP server for a coding agent. |
devboxes machine add | Adds this computer as a Runner of an Organization and saves its key. In a terminal, it asks for the Organization and the machine's name. Outside a terminal, it fails with ORGANIZATION_REQUIRED or NAME_REQUIRED. |
devboxes runner listen | Runs agents on this machine with the key that devboxes machine add saved. |
devboxes auth [path] | Manages the security of your account, including a password and two-factor authentication. With no path, it lists the account endpoints. |
--help after any command shows its options.
CLI options
| Option | Applies to | What it does |
|---|---|---|
--json | all commands | Writes results and errors as one line of JSON. |
--api <url> | all commands | Sets the API origin. DEVBOXES_API_URL sets it too. When neither is set, the CLI uses the origin of the account you signed in with. |
--config <path> | all commands | Reads and writes the CLI's configuration file at this path. |
--input - | devboxes invoke, devboxes auth | Reads the JSON input from stdin. --input @<file> reads it from a file. devboxes invoke requires it outside a terminal. |
--github | devboxes signup, login | Signs in with GitHub. devboxes signup --github also creates an account when no devboxes account uses this GitHub account yet. |
--google | devboxes signup, login | Signs in with Google. devboxes signup --google also creates an account when no devboxes account uses this Google account yet. |
--email <email> | devboxes signup, login | devboxes login emails a sign-in code to this address and asks for it. devboxes signup asks for a password, creates the account and asks for the code it emails. |
--code-stdin | devboxes signup, login | Reads the emailed code from stdin and finishes the sign-in, or the sign-up started on the same computer. |
--password-stdin | devboxes signup, login | With --email, reads the password from stdin. |
--organization <id> | devboxes connect | The Organization that gets the model account. In a terminal, devboxes asks for it. |
--label <label> | devboxes connect | The model account's name. In a terminal, devboxes asks for it. |
--account <id> | devboxes connect | Replaces the key or sign-in of this model account. |
--api-key | devboxes connect | Connects an API key instead of signing in. |
--organization <id> | devboxes machine add | The Organization whose tasks the machine runs. In a terminal, devboxes asks for it. |
--name <name> | devboxes machine add | The machine's name. In a terminal, devboxes asks for it. |
--token-file <path> | devboxes runner listen | Reads the Runner's key from this file instead of the one devboxes machine add saved. |
--state-directory <path> | devboxes runner listen | Where the Runner keeps its downloads and failed tasks' folders. |
--docker-socket <path> | devboxes runner listen | The Docker socket to use. |
--method <method> | devboxes auth | GET or POST, for an endpoint that accepts both. |
Outside a terminal and with no sign-in flag, devboxes signup and devboxes login list the sign-in methods and exit.
CLI results
devboxes invoke prints the status and the operation's result in data:
{
"status": 201,
"data": {
"organization": {
"id": "60696aa6-fb8e-4b48-88a2-aa54bbd39486",
"name": "My team",
"slug": "my-team"
}
}
}When a call fails, the CLI prints what went wrong and exits with status 1.
MCP server
devboxes mcp gives a coding agent two tools:
| Tool | What it does |
|---|---|
devboxes_describe | Lists the devboxes operations, or shows what one operation takes and returns. |
devboxes_invoke | Runs an operation with JSON input and returns its result. |
These are the operations that devboxes invoke runs. The agent acts with the account you signed in with. With DEVBOXES_TOKEN set to a delegation token, it acts with that token instead.
When an operation answers SESSION_NOT_FRESH (see HTTP API), run devboxes login in a terminal. devboxes mcp reads your sign-in for every call, so its next call uses the new one.
HTTP API
An operation <group>.<name> takes a POST request with its JSON input at https://api.devboxes.ai/api/commands/<group>/<name>. Requests carry a delegation token in the Authorization header. The response body is the operation's result.
{ "organizationId": "<organization id>", "sessionId": "<session id>" }curl -X POST https://api.devboxes.ai/api/commands/sessions/inspect \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d @session.jsonThe token runs only the operations listed in its delegation. Start tasks from CI shows how to create one.
GET https://api.devboxes.ai/api/catalogue returns the Blueprint templates with their steps, the bundles that group them, the tools devboxes works with and the kinds of company they suit. It takes no token. Add ?kind=team or ?kind=solo for the tools that kind of Organization is offered, with the ones it is suggested first.
GET https://api.devboxes.ai/api/prices returns what Basic and Premium cost a month and a year, in euros before discounts and tax, with the usage each month includes and how many tasks each runs at once, and the credit packs. It takes no token, and its answer is at most five minutes behind Stripe. billing.prices returns the same for a member of an Organization.
The OpenAPI document at https://api.devboxes.ai/api/openapi/json describes all operations. https://api.devboxes.ai/api/openapi shows it as a page.
A failed call returns an HTTP error status. error.code in the response body names the failure, and error.message says what went wrong. Some failures add error.details: when a task needs operations that your delegation or the Chat policy does not allow, error.details.missingOperations lists them.
An operation that spends money, changes access, hands over a credential, or can't be undone needs a recent sign-in. A signed-in session older than 10 minutes gets SESSION_NOT_FRESH. A delegation token gets DELEGATION_NOT_FRESH unless the delegation was created within 10 minutes of a sign-in; create it again after signing in.
In Chat, such an operation waits for a person instead: devboxes answers ELEVATION_REQUIRED, and error.details.elevation holds the request's requestId and its approvalUrl. A member with a role the request names opens the link, signed in within the last 10 minutes, and approves it, or runs elevation.approve. The same call from the same person in the same thread then runs once, within 10 minutes of the approval.