Sandbox work and access

Steer a running turn

Send a new message to a turn that is already running, without losing what the agent is doing. This is what typing into a coding agent while it works does: the instruction is taken into account and the work continues.

Where the harness has a native mid-turn primitive (Claude Code, Codex, pi, Prime Agent) nothing is interrupted and the response has native: true. Where it does not (OpenCode), Boat interrupts that turn and immediately continues the SAME conversation with the instruction, keeping the session and its memory, and the response has native: false.

Refused with 409 no_running_turn when the conversation has nothing in flight; queue work with POST /prompt instead. The steer shows up in GET /events as a steer event. See Integrated agents.

POST

sandboxes

{sandboxId}

steer

curl --request POST \
  --url https://boat.dev/api/v1/sandboxes/{sandboxId}/steer \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "message": "Also write /home/user/steered.txt containing the word STEERED, then finish."
}
'

{
  "ok": true,
  "type": "prompt.steered",
  "id": "bx_23456789",
  "conversationId": "8f1c2b7a-3d4e-4f5a-9b0c-1d2e3f4a5b6c",
  "promptId": "prompt_456",
  "native": true,
  "mode": "native",
  "status": "steered"
}

{
  "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}$

Query Parameters

conversation

string

Conversation id to steer. Also accepted in the body. Omit to steer the sandbox's most-recently-active conversation.

Body

application/json

A message for a turn that is ALREADY RUNNING. The agent takes it into account and keeps what it was doing, instead of queueing behind the turn (POST /prompt) or stopping it (POST /interrupt).

Conversations: omit conversation to steer the sandbox's most-recently-active conversation, exactly like POST /prompt chooses one. Pass a conversation id to steer a specific one while the others keep running.

The response's native says how the harness took it. See Integrated agents.

message

string

required

The extra instruction for the running turn.

Minimum string length: 1

conversation

string<uuid> | null

Conversation id to steer. Omit to steer the sandbox's most-recently-active conversation.

Response

Message delivered to the running turn.

boolean

required

Example:

true

type

string

required

Stable success envelope discriminator added by v1.

Allowed value: "prompt.steered"

string

required

Sandbox id.

conversationId

string

required

The conversation whose running turn was steered.

promptId

string

required

Id of the steer record. It appears in GET /events as a steer event; it is not a prompt run and has no lifecycle to poll.

native

boolean

required

true when the harness accepted the message into the turn that was already running, so nothing was interrupted. false when Boat interrupted that turn and immediately continued the SAME conversation with the instruction, which keeps the harness session and all of its memory but may repeat a little of the work in flight.

status

enum<string>

required

Available options:

steered

mode

enum<string>

How the message was delivered. native and fallback mirror the native field; late means the turn finished between the request and its delivery, so the message ran as an ordinary new turn on the conversation. A steer reported native here can settle as native-continued on the steer event: the harness accepted it but its turn ended without acting on it, so Boat continued it immediately as its own turn on the same session. Read the event for the settled mode.

Available options:

native,

fallback,

late

curl --request POST \
  --url https://boat.dev/api/v1/sandboxes/{sandboxId}/steer \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "message": "Also write /home/user/steered.txt containing the word STEERED, then finish."
}
'

{
  "ok": true,
  "type": "prompt.steered",
  "id": "bx_23456789",
  "conversationId": "8f1c2b7a-3d4e-4f5a-9b0c-1d2e3f4a5b6c",
  "promptId": "prompt_456",
  "native": true,
  "mode": "native",
  "status": "steered"
}

{
  "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": {}
  }
}