CLI and MCP operations
Dispatch, continue, and inspect Devboxes work with explicit project selection and structured results.
Run devboxes login before using account-backed CLI or MCP operations. The stored account and selected organization determine access. Do not place credentials in MCP configuration when the existing sign-in flow can supply them.
Start the MCP server
Configure the client to execute devboxes mcp over stdio. Keep stdout reserved for the MCP protocol. Add --project <project-id> to fix dispatch, reads, and continuation to one Project. Without that option, Organization-wide reads remain available but Run dispatch is not admitted.
| MCP tool | Purpose | Required inputs |
|---|---|---|
dispatch_run | Start a Run in the project fixed by the server command. | UUID operationId, non-empty task |
continue_session | Start a fresh Run in an existing Agent Session. | agentSessionId, task, UUID clientMessageId |
get_agent_session | Read an Agent Session and its current Run. | agentSessionId |
get_run | Read one Run, including status, usage, steps, and outcome. | runId |
devboxes_describe | Discover admitted operations and their current schemas. | query |
devboxes_request | Invoke an admitted operation by stable API operation ID. | operationId, input |
Select the project explicitly when possible
For MCP, select the project when starting the server: devboxes mcp --project <project-id>. Project identity is trusted server context and is not a tool argument. The same fixed scope applies to Run and Agent Session reads and to continuation.
The standalone devboxes dispatch command still accepts --project and --repo. Without either, it can use the working-directory Git origin or the organization's only project. Inspect projectSelection and inferredFromGitRemote in its JSON response when selection was implicit.
Supply branch explicitly when a Run must use a particular base branch. Select blueprintVersionId when the task requires a particular workflow. Use the schema returned by the MCP server rather than assuming that CLI-only defaults or repository inference apply to MCP.
Poll without duplicating work
Save the returned agentSessionId and runId. Read get_run with a bounded polling strategy. A blocked Run needs attention, not repeated dispatch.
Read status, errorMessage, and outcome. Succeeded, failed, and cancelled are terminal states. A published result exists only when the outcome records it; do not invent a pull request URL from the branch name. Reuse the same operationId or clientMessageId when retrying a dispatch or continuation after a lost response.
CLI equivalents
Replace owner/repo#123 with an existing issue in the selected project's repository. The default Implement GitHub Issue blueprint reads that issue. The CLI adds the issue URL and destination branch to its input. For a free-form task, select a compatible blueprint with --blueprint-version <version-id>.
devboxes dispatch --project <project-id> --branch <base-branch> --json "owner/repo#123"
devboxes status <session-id> --json
devboxes result <session-id> --json
devboxes continue <session-id> --json "Follow-up instructions"The CLI result command exits with status 1 while work is not terminal. Machine clients must inspect the JSON status even when a command exits successfully. Human-readable messages may change; IDs, fields, and command options are the integration contract.