Sandbox work and access

Prompt Sandbox

Queue a natural-language work item for an agent harness (Codex, Claude Code, pi, OpenCode, or Prime Agent) inside the sandbox. Observe progress with GET /sandboxes/{sandboxId}/events.

A Sandbox runs many conversations in parallel. Set new: true to start a fresh one, conversationId to continue a specific one, or omit both to continue the most-recently-active conversation; the response returns the conversationId. See Integrated agents.

POST

sandboxes

{sandboxId}

prompt

curl --request POST \
  --url https://boat.dev/api/v1/sandboxes/{sandboxId}/prompt \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "provider": "codex",
  "model": "gpt-5.4",
  "reasoningEffort": "medium",
  "prompt": "Work on the selected repo, run tests, fix failures, commit the result, and report any hosted preview URL."
}
'

{
  "ok": true,
  "type": "prompt.queued",
  "id": "bx_23456789",
  "promptId": "prompt_123",
  "conversationId": "8f1c2b7a-3d4e-4f5a-9b0c-1d2e3f4a5b6c",
  "promptRun": {
    "id": "prompt_123",
    "promptId": "prompt_123",
    "sandboxId": "bx_23456789",
    "status": "queued",
    "done": false,
    "conversationId": "8f1c2b7a-3d4e-4f5a-9b0c-1d2e3f4a5b6c"
  },
  "status": "queued",
  "provider": "codex",
  "model": "gpt-5.4",
  "reasoningEffort": "medium",
  "fast": false
}

{
  "ok": false,
  "type": "sandbox.error",
  "status": 400,
  "code": "invalid_json",
  "message": "Request body must be valid JSON.",
  "error": {
    "code": "invalid_json",
    "message": "Request body must be valid JSON.",
    "status": 400
  },
  "requestId": "req_01HX..."
}

{
  "ok": false,
  "type": "sandbox.error",
  "status": 401,
  "code": "unauthorized",
  "message": "Unauthorized",
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized",
    "status": 401
  },
  "requestId": "req_01HX..."
}

{
  "ok": false,
  "type": "sandbox.error",
  "status": 409,
  "code": "provider_not_configured",
  "message": "Prompting is locked until Codex is configured on the Agents page.",
  "requestId": "req_01HX...",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  }
}

{
  "ok": false,
  "type": "sandbox.error",
  "status": 409,
  "code": "provider_not_configured",
  "message": "Prompting is locked until Codex is configured on the Agents page.",
  "requestId": "req_01HX...",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  }
}

{
  "ok": false,
  "type": "sandbox.error",
  "status": 409,
  "code": "provider_not_configured",
  "message": "Prompting is locked until Codex is configured on the Agents page.",
  "requestId": "req_01HX...",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  }
}

Authorizations

Authorization

string

header

required

Boat bearer token in the form boat_.... Service API keys authenticate sandbox operations.

Path Parameters

sandboxId

string

required

Public Sandbox id returned by create/list/get sandbox calls.

Pattern: ^bx_[23456789abcdefghjkmnpqrstuvwxyz]{8}$

Body

application/json

Work item to queue inside an existing sandbox. Provider credentials must already be configured in the Boat dashboard.

Providers (harnesses): codex, claude-code (alias claude), pi, opencode, prime-agent (alias prime), kimi (Kimi Code CLI, alias kimi-code), mistral (Mistral Vibe). Omit provider to use the harness the user selected on the Agents dashboard.

Models & reasoning effort are harness- and model-specific and change over time. Fetch the live catalog (every provider's models and which reasoning-effort levels each accepts) from GET /provider-models. Some models accept no reasoning control. pi, opencode and prime-agent also expose models routed through OpenRouter and llmgateway (ids like openrouter:anthropic/claude-sonnet-4.5).

Conversations: a sandbox runs many conversations in parallel, each with its own history. Set new: true to start a fresh conversation, or conversationId to continue a specific one; omit both to continue the sandbox's most-recently-active conversation. The response returns the conversationId this prompt ran in. Conversations run concurrently up to a per-sandbox limit that scales with the sandbox's memory; beyond it, prompts queue.

provider

enum<string>

required

Available options:

codex,

claude-code,

claude,

pi,

opencode,

prime-agent,

prime,

kimi,

kimi-code,

mistral

prompt

string

required

Natural-language task for the sandbox, including repo, preview, or browser-use instructions.

Minimum string length: 1

model

string | null

Optional provider model id from GET /provider-models. Omit to use the model selected for that harness on the Agents dashboard. Unknown explicit ids are currently forwarded rather than rejected by request validation.

Examples:

"gpt-5.6-terra"

"claude-sonnet-5"

"openrouter:anthropic/claude-sonnet-4.5"

reasoningEffort

string | null

Optional reasoning/thinking level (e.g. none, low, medium, high, xhigh, max). Which levels a given model accepts is listed per model in GET /provider-models; some models accept none.

Example:

"high"

fast

boolean | null

Optional. true runs this prompt in fast mode. The model stays the same and gives output faster. The provider bills fast mode at its higher fast rate. Omit to use the choice saved on the Agents dashboard for that model. false forces standard speed. Only models with fastMode set to true in GET /provider-models accept true. Other models return 400 fast_mode_not_supported.

Example:

true

new

boolean

Start a NEW conversation on the sandbox (runs in parallel with any existing ones) instead of continuing the most-recently-active one. Mutually exclusive with conversationId.

Example:

true

conversationId

string<uuid> | null

Continue a specific conversation by id (as returned by a previous prompt). Omit (and omit new) to continue the sandbox's most-recently-active conversation.

Response

Prompt queued.

boolean

required

Example:

true

type

string

required

Stable success envelope discriminator added by v1.

Allowed value: "prompt.queued"

string

required

Sandbox id.

promptId

string

required

promptRun

object

required

Show child attributes

status

enum<string>

required

Available options:

queued

provider

string

required

conversationId

string | null

The conversation this prompt was queued in. A new one when new was set, the one named by conversationId, or the sandbox's most-recently-active conversation. See Integrated agents.

model

string | null

reasoningEffort

string | null

fast

boolean

The prompt runs in fast mode.

curl --request POST \
  --url https://boat.dev/api/v1/sandboxes/{sandboxId}/prompt \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "provider": "codex",
  "model": "gpt-5.4",
  "reasoningEffort": "medium",
  "prompt": "Work on the selected repo, run tests, fix failures, commit the result, and report any hosted preview URL."
}
'

{
  "ok": true,
  "type": "prompt.queued",
  "id": "bx_23456789",
  "promptId": "prompt_123",
  "conversationId": "8f1c2b7a-3d4e-4f5a-9b0c-1d2e3f4a5b6c",
  "promptRun": {
    "id": "prompt_123",
    "promptId": "prompt_123",
    "sandboxId": "bx_23456789",
    "status": "queued",
    "done": false,
    "conversationId": "8f1c2b7a-3d4e-4f5a-9b0c-1d2e3f4a5b6c"
  },
  "status": "queued",
  "provider": "codex",
  "model": "gpt-5.4",
  "reasoningEffort": "medium",
  "fast": false
}

{
  "ok": false,
  "type": "sandbox.error",
  "status": 400,
  "code": "invalid_json",
  "message": "Request body must be valid JSON.",
  "error": {
    "code": "invalid_json",
    "message": "Request body must be valid JSON.",
    "status": 400
  },
  "requestId": "req_01HX..."
}

{
  "ok": false,
  "type": "sandbox.error",
  "status": 401,
  "code": "unauthorized",
  "message": "Unauthorized",
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized",
    "status": 401
  },
  "requestId": "req_01HX..."
}

{
  "ok": false,
  "type": "sandbox.error",
  "status": 409,
  "code": "provider_not_configured",
  "message": "Prompting is locked until Codex is configured on the Agents page.",
  "requestId": "req_01HX...",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  }
}

{
  "ok": false,
  "type": "sandbox.error",
  "status": 409,
  "code": "provider_not_configured",
  "message": "Prompting is locked until Codex is configured on the Agents page.",
  "requestId": "req_01HX...",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  }
}

{
  "ok": false,
  "type": "sandbox.error",
  "status": 409,
  "code": "provider_not_configured",
  "message": "Prompting is locked until Codex is configured on the Agents page.",
  "requestId": "req_01HX...",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  }
}