Use in Code

Use --json and parse stdout when automating the Boat CLI. For typed HTTP clients, use the Python SDK or TypeScript/JavaScript SDK. Some commands emit one JSON object. Long-running commands emit JSON Lines: one JSON object per line. Argument parsing errors can still be emitted by the CLI parser on stderr before Boat’s JSON error handler runs. For non-interactive environments, create a Boat API key with boat api-key create and pass it as BOAT_API_KEY; see API Keys for setup. For runtime secrets inside sandboxes, use Dashboard > Environment. Dashboard secrets are injected as environment variables and secret files; configure them before running setup scripts or prompts that need credentials. See Environments for the dashboard workflow and setup-script guidance.

Treat desktopUrl and viewerUrl as secrets. They can include short-lived desktop access tokens.

Authenticate

Authenticate once before the first command in a process or container:

boat login --key-stdin --json <<< "$BOAT_API_KEY"

--key-stdin reads the token from standard input, so it never reaches the process arguments, where any other user on the host can read it with ps or /proc/<pid>/cmdline while the command runs. Passing the token positionally (boat login "$BOAT_API_KEY") still works and is still supported, but it discloses the key on a shared or multi-tenant host. --key-stdin needs a Boat CLI newer than 0.1.211; check yours with boat --version. Older binaries only accept the positional form. Output:

{
  "event": "login_complete",
  "data": {
    "user": {
      "login": "octocat",
      "email": "octocat@example.com"
    }
  }
}

To provision the key itself per project, use a browser-authenticated session. An admin-scoped API key can also create a child key when every child action, resource, and expiry stays within the parent grant:

BOAT_API_KEY="$(boat api-key create my-project --json | jq -r '.secret')"

The secret is only ever present in this one response; boat api-key list --json returns metadata without secrets. If you run boat login --json with no key at all, the CLI starts the browser flow instead:

{
  "event": "login_url",
  "url": "https://boat.dev/api/boat/auth/github?state=...",
  "pollToken": "opaque_poll_token",
  "nextCommand": "boat onboard --json",
  "instruction": "Ask the user to open this URL and sign in with GitHub. After the browser says it is complete, run nextCommand."
}

Output contract

Commands that return a single JSON object:

Command	Shape
`sandbox config --json`	`ConfigResult`
`boat list --json`	`SandboxListResult`
`boat info <id> --json`	`SandboxInfoResult`
`boat limits --json`	`LimitsResult`
`boat usage <id> --json`	`SandboxUsageResult`
`boat stop <id> --json`	`SandboxActionResult`
`boat resume <id> --json`	`SandboxActionResult`
`boat fork <id> --json`	`SandboxActionResult`
`boat steer <id> <message> --json`	`SteerResult` (`conversationId`, `promptId`, `native`, `mode`)
`boat interrupt <id> --json`	`SandboxActionResult`
`boat host <id> <port> --json`	`HostResult`
`boat desktop <id> --json`	`DesktopResult`
`boat desktop <id> --vnc --json`	`VncDesktopResult`
`boat api-key create <name> --json`	`ApiKeySecretResult`
`boat api-key rotate <id> --json`	`ApiKeySecretResult`
`boat api-key list --json`	`ApiKeyListResult`
`boat api-key usage <id> --json`	`ApiKeyUsageResult`
`boat api-key revoke <id> --json`	`{ ok: true }`

Commands that emit JSONL:

Command	Lines
`boat new --json`	`created`, zero or more `state`, then `ready` or `error`
`boat prompt [id] ... --json`	`queued` (carries `conversationId`), then `chat` lines until the prompt finishes
`boat events <id> --json`	zero or more `chat` lines and then exits
`boat events <id> --follow --json`	`chat` lines until interrupted
`boat conversations <id> --json`	one `conversation` line per conversation, newest first: `id`, `createdAt`, `lastPromptAt`, `prompts`, `running`, `lastHarness`, `lastModel`, `lastPromptPreview`, `current` (the sandbox’s), `shellCurrent` (this shell’s)

boat prompt takes an optional --provider (codex, claude, pi, opencode, prime, kimi), --model, and --reasoning-effort; --attach <path> (repeatable) to attach files/images; and the conversation flags --new, --resume <id>, and (on events/interrupt) --convo <id>. A single sandbox runs many conversations in parallel; every queued and chat line carries a conversationId, and boat conversations --json lists the ids to resume.

Setup Scripts and Secrets

The usual setup flow is:

Configure secrets in Dashboard > Environment.
Create a sandbox with boat new --json and wait for the ready event.
Run a non-interactive command with boat ssh.

Secrets configured in the dashboard are available as process environment variables and configured secret files inside the sandbox. Prefer this over passing secret values in prompts, URLs, or command arguments. boat ssh <id> <command> prepares and registers the CLI-managed SSH key, then runs the command without opening an interactive shell. It streams stdin, stdout, and stderr, so a setup script can run without copying it into the sandbox first.

sandbox_id="$(boat new --json | jq -r 'select(.event == "ready") | .id')"
boat ssh "$sandbox_id" -- bash -s < ./setup.sh
boat ssh "$sandbox_id" "cd /home/user/ariana-ide-private && npm install"
boat ssh "$sandbox_id" -- bash -lc "cd /home/user/ariana-ide-private && npm test"

On Windows PowerShell:

$sandboxId = $null
boat new --json | ForEach-Object {
  $event = $_ | ConvertFrom-Json
  if ($event.event -eq "ready") { $sandboxId = $event.id }
}
cmd /c "type setup.sh | boat ssh $sandboxId -- bash -s"
boat ssh $sandboxId "cd /home/user/ariana-ide-private && npm install"

PowerShell’s native pipeline can keep stdin open for native executables in some environments. For Windows automation, run setup through Node, Python, WSL, Git Bash, or cmd.exe. If you need the sandbox to keep running for a long uninterrupted workflow, disable auto-stop when creating it:

sandbox_id="$(boat new --no-auto-stop --json | jq -r 'select(.event == "ready") | .id')"

See Long-Running Tasks. Do not rely on runtime processes surviving resume or fork. After boat resume or boat fork, check app servers, workers, dev servers, tunnels, and desktop sessions, and run your setup or start command again if needed.

Prompt and events

boat prompt --provider codex <id> "..." --json first emits a queued line:

{
  "event": "queued",
  "data": {
    "id": "bx_chm52eme",
    "promptId": "09690a68-5aee-4b35-a2e7-eb1b64e3e104",
    "status": "queued",
    "provider": "codex",
    "model": null,
    "reasoningEffort": null
  }
}

Then it emits chat lines until the prompt finishes. boat events --json emits the same chat line shape for persisted events. It may return fewer lines than boat prompt --json; in a live check, boat prompt emitted queued, queued-prompt, running-prompt, finished-prompt, and response lines, while boat events later returned the persisted finished-prompt and response lines.

{
  "event": "chat",
  "final": true,
  "data": {
    "id": "a75c1426-23bf-4eae-9131-c957046a2af5",
    "taskId": "09690a68-5aee-4b35-a2e7-eb1b64e3e104",
    "type": "response",
    "timestamp": 1779986896114,
    "data": {
      "content": "sandbox-jsonl-audit-ok",
      "is_reverted": false,
      "model": "gpt-5.4"
    }
  }
}

Schema:

type QueuedLine = {
  event: "queued";
  data: {
    id: string;
    promptId: string;
    status: "queued";
    provider: "codex" | "claude-code" | string;
    model?: string | null;
    reasoningEffort?: string | null;
  };
}

type ChatLine = {
  event: "chat";
  final: boolean;          // false for streaming partial response events
  data: {
    id?: string;
    type: "prompt" | "response" | "usage_limit" | string;
    timestamp?: number;   // Unix epoch milliseconds
    taskId?: string;
    data: Record<string, unknown>;
  };
}

response chat events can include tool data in data.tools; keep the full object if you need exact agent traces.

Bash JSONL parser

set -euo pipefail

boat login --key-stdin --json <<< "$BOAT_API_KEY" >/dev/null

sandbox_id=""
while IFS= read -r line; do
  event="$(printf '%s\n' "$line" | jq -r '.event')"
  case "$event" in
    created)
      sandbox_id="$(printf '%s\n' "$line" | jq -r '.id')"
      ;;
    ready)
      ip="$(printf '%s\n' "$line" | jq -r '.ip // empty')"
      echo "ready: $sandbox_id $ip"
      ;;
    error)
      printf '%s\n' "$line" >&2
      exit 1
      ;;
  esac
done < <(boat new --ttl 3600 --json)

boat info "$sandbox_id" --json
boat stop "$sandbox_id" --json

Node.js

Use a single-object helper for commands like info, and a JSONL helper for commands like new.

import { spawnSync, spawn } from "node:child_process";
import { createInterface } from "node:readline";

class SandboxCliError extends Error {
  constructor(line, fallback) {
    super(line?.error || fallback);
    this.name = "SandboxCliError";
    this.code = line?.code;
    this.status = line?.status;
    this.line = line;
  }
}

function parseErrorLine(output) {
  const lastLine = output.trim().split(/\r?\n/).filter(Boolean).at(-1);
  if (!lastLine) return null;
  try {
    const parsed = JSON.parse(lastLine);
    return parsed.event === "error" ? parsed : null;
  } catch {
    return null;
  }
}

function sandboxJson(args, { stdin } = {}) {
  const result = spawnSync("boat", [...args, "--json"], {
    encoding: "utf8",
    input: stdin,
    stdio: ["pipe", "pipe", "pipe"],
  });

  if (result.status !== 0) {
    throw new SandboxCliError(
      parseErrorLine(result.stdout),
      result.stderr || `sandbox ${args.join(" ")} failed`
    );
  }

  return JSON.parse(result.stdout);
}

async function* sandboxJsonLines(args) {
  const child = spawn("boat", [...args, "--json"], {
    stdio: ["ignore", "pipe", "pipe"],
  });
  const rl = createInterface({ input: child.stdout });
  let lastError = null;

  for await (const line of rl) {
    if (!line.trim()) continue;
    const parsed = JSON.parse(line);
    if (parsed.event === "error") lastError = parsed;
    yield parsed;
  }

  const exitCode = await new Promise((resolve) => child.on("close", resolve));
  if (exitCode !== 0) {
    throw new SandboxCliError(lastError, `sandbox ${args.join(" ")} exited with ${exitCode}`);
  }
}

sandboxJson(["login", "--key-stdin"], { stdin: process.env.BOAT_API_KEY });

let sandboxId;
for await (const line of sandboxJsonLines(["new", "--ttl", "3600"])) {
  if (line.event === "created") sandboxId = line.id;
  if (line.event === "ready") console.log("ready", line);
}

console.log(sandboxJson(["info", sandboxId]));
sandboxJson(["stop", sandboxId]);

Python

import json
import os
import subprocess


class SandboxCliError(Exception):
    def __init__(self, line, fallback):
        super().__init__((line or {}).get("error") or fallback)
        self.line = line
        self.code = (line or {}).get("code")
        self.status = (line or {}).get("status")


def parse_error_line(output):
    lines = [line for line in output.splitlines() if line.strip()]
    if not lines:
        return None
    try:
        parsed = json.loads(lines[-1])
    except json.JSONDecodeError:
        return None
    return parsed if parsed.get("event") == "error" else None


def sandbox_json(*args, stdin=None):
    result = subprocess.run(
        ["boat", *args, "--json"],
        input=stdin,
        text=True,
        capture_output=True,
    )
    if result.returncode != 0:
        raise SandboxCliError(
            parse_error_line(result.stdout),
            result.stderr or f"sandbox {' '.join(args)} failed",
        )
    return json.loads(result.stdout)


def sandbox_json_lines(*args):
    process = subprocess.Popen(
        ["boat", *args, "--json"],
        text=True,
        stdout=subprocess.PIPE,
        stderr=subprocess.PIPE,
    )
    assert process.stdout is not None
    last_error = None
    for line in process.stdout:
        if line.strip():
            parsed = json.loads(line)
            if parsed.get("event") == "error":
                last_error = parsed
            yield parsed
    exit_code = process.wait()
    if exit_code != 0:
        stderr = process.stderr.read() if process.stderr else ""
        raise SandboxCliError(last_error, stderr or f"sandbox {' '.join(args)} exited with {exit_code}")


sandbox_json("login", "--key-stdin", stdin=os.environ["BOAT_API_KEY"])

sandbox_id = None
for event in sandbox_json_lines("new", "--ttl", "3600"):
    if event["event"] == "created":
        sandbox_id = event["id"]
    if event["event"] == "ready":
        print("ready", event)

print(sandbox_json("info", sandbox_id))
sandbox_json("stop", sandbox_id)

Direct SSH

The CLI manages the SSH key. For an interactive shell, prefer:

boat ssh "$sandbox_id"
boat scp ./local-file.txt "$sandbox_id:/home/user/local-file.txt"

For boat scp, remote paths are passed through to OpenSSH scp after the <sandbox-id>: prefix. Absolute paths such as /home/user/setup.sh are the safest. Relative remote paths are resolved from the SSH user’s home directory (/home/user on hosted sandboxes). Avoid relying on ~ in automation because expansion can vary by local shell and scp mode. For non-interactive commands, pass the command after the sandbox ID:

boat ssh "$sandbox_id" "cd /home/user/ariana-ide-private && npm test"
boat ssh "$sandbox_id" -- bash -lc "cd /home/user/ariana-ide-private && npm test"
boat ssh "$sandbox_id" -- bash -s < ./setup.sh

For direct SSH, inspect the sandbox for its IP and use the CLI-managed key:

ip="$(boat info "$sandbox_id" --json | jq -r '.sandbox.ip // empty')"
ssh -i ~/.ssh/ascii_box_ed25519 "user@$ip"

Errors

Most failed CLI commands in --json mode emit one final JSON line to stdout and exit non-zero. Commands that normally emit one JSON object still use this JSONL error line on runtime failure. Argument parsing failures, such as missing required flags or invalid numeric flag values, are emitted by the CLI parser on stderr and may not be JSON.

The error line

{
  "event": "error",
  "error": "Human-readable error message"
}

Backend API failures include code and status. The backend field is named error; the CLI exposes that backend code as code so error can stay human-readable.

{
  "event": "error",
  "error": "not found (404). check the sandbox ID with `boat list` (or use `current` if you created one in this shell)",
  "code": "not_found",
  "status": 404
}

Local CLI failures do not include code or status because no Boat API error response was received:

{
  "event": "error",
  "error": "invalid provider \"nope\". Use codex, claude, pi, opencode, prime or kimi."
}

Network failures also use the local shape:

{
  "event": "error",
  "error": "could not reach the Boat API at http://127.0.0.1:9: error sending request for url (...)"
}

Type:

type CliErrorLine = {
  event: "error";
  error: string;
  code?: string;    // backend `error` code, present only for Boat API failures
  status?: number;  // HTTP status, present only for Boat API failures
}

Backend error shapes

The backend error object for Boat CLI API paths is one of these shapes:

type SandboxApiError =
  | BasicSandboxApiError
  | BlockedSandboxApiError
  | RateLimitedSandboxApiError
  | ProviderNotConfiguredError
  | SandboxNotPromptableError
  | StopFailedError
  | SshKeyError;

type BasicSandboxApiError = {
  error:
    | "unauthorized"
    | "forbidden"
    | "not_found"
    | "method_not_allowed"
    | "account_not_ready"
    | "prompt_required"
    | "provider_required"
    | "invalid_name"
    | "no_changes"
    | "resume_failed"
    | "fork_failed"
    | "machine_not_running"
    | "desktop_not_ready"
    | "boat_starting"
    | "invalid_timeout"
    | "invalid_path"
    | "invalid_setup_script";
  message?: string;
}

type SandboxLimitFields = {
  activeStates: ["provisioned", "cloning", "ready", "idle", "running"];
  activeSandboxes: number;
  maxActiveSandboxes: number;
  maxCreationRequestsPerMinute: number;
  maxCreationRequestsPerDay: number | null;
  startLimits: { perMinute: number; perHour: number; perDay: number } | null;
  starts: {
    unlimited: boolean;
    minute: { limit: number; used: number; remaining: number } | null;
    hour: { limit: number; used: number; remaining: number } | null;
    day: { limit: number; used: number; remaining: number } | null;
  };
  currentLimits: {
    activeSandboxes: number;
    creationRatePerMinute: number;
    creationRequestsPerDay: number | null;
  };
  standardLimits: {
    activeSandboxes: number;
    creationRatePerMinute: number;
    creationRequestsPerDay: number | null;
  };
  trialLimits: {
    activeSandboxes: number;
    creationRatePerMinute: number;
    creationRequestsPerDay: number | null;
  };
}

type SandboxBillingFields = {
  hasSubscription: boolean;
  hasPaymentHistory: boolean;
  accountPlan: "user" | "service" | string;
  plan: "service" | string | null;
  planName: string | null;
  serviceAccount: boolean;
  unlimited: boolean;
  billingStatus: string;
  subscriptionStatus: string;
  subscriptionCancelAtPeriodEnd: boolean;
  subscriptionTrialEndsAt: string | null;
  subscriptionCurrentPeriodEnd: string | null;
  checkoutRequired: boolean;
  canStart: boolean;
  startBlockedReason: "subscription_required" | "usage_depleted" | string | null;
  blockedReason: "subscription_required" | "usage_depleted" | string | null;
  accessTier: "trial" | "standard" | "service" | string;
  creditBalanceSeconds: number;
  creditBalanceHours: number | null;
  subscriptionQuotaSeconds: number;
  subscriptionRemainingSeconds: number;
  packBalanceSeconds: number;
  packBalanceHours: number;
  packBalanceDollars: number;
  creditPurchasedSeconds: number;
  creditUsedSeconds: number;
  liveUsageSeconds: number;
  creditSecondsPerDollar: number;
  package: {
    dollars: number;
    seconds: number;
    secondsPerDollar: number;
  };
  upgradeEffects: {
    startTrial: {
      canCreate: true;
      activeSandboxes: number;
      creationRequestsPerDay: number;
      note: string;
    };
    endTrialOrFirstPayment: {
      activeSandboxes: number;
      creationRequestsPerDay: null;
      note: string;
    };
    pack: {
      seconds: number;
      persistsAcrossMonths: true;
      note: string;
    };
  };
  contactMessage: string;
}

type BlockedSandboxApiError = (SandboxLimitFields & SandboxBillingFields) & {
  error: "billing_required" | "boat_access_inactive" | "limit_reached";
  status: "blocked";
  message: string;
  billingUrl: string;
}

type RateLimitedSandboxApiError = {
  error: "rate_limited";
  status: "blocked";
  message: string;
  // Which start window was hit, and its cap.
  window: "minute" | "hour" | "day";
  limit: number;
  // The full ladder for the account: per-minute, per-hour, per-day.
  startLimits: { perMinute: number; perHour: number; perDay: number };
  starts: {
    unlimited: boolean;
    minute: { limit: number; used: number; remaining: number } | null;
    hour: { limit: number; used: number; remaining: number } | null;
    day: { limit: number; used: number; remaining: number } | null;
  };
  maxCreationRequestsPerMinute: number;
}

type ProviderNotConfiguredError = {
  error: "provider_not_configured";
  provider: "codex" | "claude-code" | "pi" | "opencode" | "prime-agent" | "kimi";
  setupUrl: string;
  message: string;
}

type SandboxNotPromptableError = {
  error: "sandbox_not_promptable";
  state: string;
  message: string;
}

type StopFailedError = {
  error: "stop_failed";
  message: string;
  sandbox: Sandbox | null;
}

type SshKeyError = {
  success: false;
  error: "unauthorized" | "not_found" | "machine_not_running" | "invalid_ssh_key";
  message?: string;
}

The CLI uses message when present. If there is no message, it humanizes known backend codes such as unauthorized, not_found, account_not_ready, method_not_allowed, and rate_limited; otherwise it formats the backend code and HTTP status. For backend errors that include billingUrl, setupUrl, or dashboardUrl, the CLI appends that URL to the human-readable error string. Those URLs carry no credential: opening one lands on a signed-out dashboard.

Backend error codes

Common backend codes used by the Boat CLI paths:

Code	HTTP status	Where it comes from
`unauthorized`	401	Missing, invalid, expired, or revoked Boat auth.
`billing_required`	402	Creating, resuming, forking, or prompting is blocked by inactive plan or depleted usage.
`boat_access_inactive`	402	Reading events or accessing an existing sandbox is blocked by inactive plan or depleted time.
`not_found`	404	The Sandbox ID or API key was not found for the current user.
`account_not_ready`	409	GitHub/Ascii account setup is incomplete.
`boat_starting`	409	A command was sent while the sandbox was still provisioning. Retryable: wait for the sandbox to reach `ready`, then send it again.
`resume_failed`	409	Backend could not resume the sandbox.
`boat_restoring`	409	SSH/desktop access requested in the first seconds of a resume, before the filesystem is being served. Retry after a moment.
`fork_failed`	409	Backend could not fork the sandbox.
`provider_not_configured`	409	Prompting was requested before the selected provider was configured.
`sandbox_not_promptable`	409	Prompting was requested while the sandbox is in an unsupported state.
`prompt_required`	400	Prompt request body had no non-empty prompt.
`provider_required`	400	Prompt request body had no supported provider.
`machine_not_running`	400	Command, desktop, or SSH key setup was requested before the machine was running.
`desktop_not_ready`	400	Desktop streaming metadata was not ready.
`invalid_ssh_key`	400	SSH key registration received a missing or invalid public key.
`invalid_timeout`	400	Command `timeoutSeconds` was not an integer in 1–600.
`invalid_path`	400	File read/write path did not resolve under `/home/user` or `/tmp`.
`invalid_setup_script`	400	Boat create received a `setupScript` that was not a string or exceeded 64KB.
`invalid_name`	400	Boat rename received an empty name.
`no_changes`	400	Boat update request did not include a supported change.
`stop_failed`	400	Stop was requested while the sandbox was in a state that cannot transition to stopping.
`trial_auto_stop_required`	400	Auto-stop was disabled, or a TTL above 2 hours requested, on a trial account.
`trial_machine_class_not_allowed`	403	`large` was requested on a trial account.
`team_member_cap_reached`	402	The organization owner’s per-member usage cap for this billing window is spent.
`member_limit_reached`	429	The organization owner’s per-member concurrent-sandbox cap is reached.
`org_suspended`	403	The organization wallet this sandbox would bill is suspended.
`rate_limited`	429	A machine-start limit was hit. `window` (`minute`, `hour` or `day`) and `limit` name which cap; `starts` carries remaining counts for all three windows.
`limit_reached`	429	Concurrent sandbox limit reached.
`method_not_allowed`	405	API key management route received an unsupported method/action.

Local CLI errors

Local CLI validation can fail before the backend is called. These errors have no stable code today. Examples from the current CLI source include invalid provider, invalid model, invalid reasoning effort, empty API key, missing local login, unsupported HTTP method, invalid local JSON from the API, SSH/SCP exit failures, and unreachable API host.

Common types

Boat

type Sandbox = {
  id: string;                    // bx_...
  name: string;
  state: "init" | "provisioning" | "cloning" | "ready" | "idle" | "running" | "stopping" | "stopped" | "error" | string;
  url: string | null;            // public HTTPS URL for services
  ip: string | null;             // direct SSH IPv6 or IPv4 when available
  desktopAvailable: boolean;
  desktopUrl: string | null;     // secret-bearing desktop stream URL
  snapshotAvailable: boolean;
  snapshotCompletedAt: string | null;
  createdAt: string | null;      // ISO timestamp
  updatedAt: string | null;      // ISO timestamp
  archiveAfter: string | null;   // ISO timestamp, null means no automatic stop
  self?: boolean;                // only added by `boat list --json`
}

The CLI presents backend states for users: provisioned becomes ready, archiving becomes stopping, and archived becomes stopped.

SandboxListResult

type SandboxListResult = {
  sandboxes: Sandbox[];
  pageInfo?: {
    hasMore: boolean;
    limit: number;
    nextCursor: string | null;
  };
}

boat list --json defaults to up/running sandboxes, the same as boat list --filter r --json. Use boat list --filter s --json for stopped sandboxes, combine groups like --filter sr, or use --all --json to include every state. Example:

{
  "sandboxes": [
    {
      "id": "bx_8pqt6dup",
      "name": "Boat 2026-05-28 16:00",
      "state": "idle",
      "url": "https://example-sandbox.on.boat.dev",
      "ip": "203.0.113.10",
      "desktopAvailable": true,
      "desktopUrl": "https://example-desktop.on.boat.dev/stream.html?hostId=...&token=...",
      "snapshotAvailable": true,
      "snapshotCompletedAt": "2026-05-28T16:39:33.012Z",
      "createdAt": "2026-05-28T16:00:33.143Z",
      "updatedAt": "2026-05-28T16:00:39.535Z",
      "archiveAfter": "2026-05-28T17:00:33.162Z",
      "self": false
    }
  ]
}

SandboxInfoResult

type SandboxInfoResult = {
  sandbox: Sandbox;
}

SandboxActionResult

Used by stop, resume, fork, and interrupt.

type SandboxActionResult = {
  id: string;
  status: "stopping" | "resuming" | "forking" | string;
  sandbox: Sandbox | null;
}

DesktopResult

type DesktopResult = {
  success: true;
  desktopUrl: string;        // secret-bearing stream URL
  viewerUrl: string;         // secret-bearing dashboard viewer URL
  ip: string | null;
}

HostResult

type HostResult = {
  sandboxId: string;
  port: number;
  url: string;                // HTTPS URL for the exposed port
  access: "private" | "public";
  isProtected: boolean;       // true when url includes or requires _token
  title: string | null;
}

VncDesktopResult

type VncDesktopResult = {
  desktopUrl: string;        // secret-bearing noVNC URL
  mode: "vnc";
}

ApiKeySecretResult

Returned by boat api-key create --json and boat api-key rotate --json. The secret exists only in this response and can never be retrieved again.

type ApiKeyMetadata = {
  id: string;
  name: string;
  keyPrefix: string;           // first 12 characters
  keyLastFour: string;
  sandboxId: string | null;    // set on platform-managed per-sandbox keys
  createdAt: string;           // ISO timestamp
  lastUsedAt: string | null;   // ISO timestamp
  usage: { requests: number; windowDays: 30 };
  resources: { total: number; sandboxes: number; agents: number };
}

type ApiKeySecretResult = {
  apiKey: ApiKeyMetadata;
  secret: string;              // full key, shown once
}

ApiKeyListResult

boat api-key list --json returns keys you created; add --all to include platform-managed per-sandbox machine keys (sandboxId set).

type ApiKeyListResult = {
  apiKeys: ApiKeyMetadata[];
}

boat api-key usage <id> --json returns the same totals. Add --verbose to keep createdResources. The command still works after the key is revoked.

type ApiKeyCreatedResource = {
  kind: "boat" | "agent";
  id: string;
  name: string;
  state: string;
  createdAt: string | null;
}

type ApiKeyUsageResult = ApiKeyMetadata & {
  createdResources?: ApiKeyCreatedResource[];
}

SandboxUsageResult

boat usage <id> --json returns the API payload unchanged. seconds already includes the sandbox type’s multiplier; dollars is seconds / secondsPerDollar. See Per-sandbox usage.

type SandboxUsageResult = {
  sandboxId: string;
  sandboxType: "small" | "default" | "large" | "xlarge";
  billingMultiplier: number;
  since: string;             // ISO timestamp; sandbox creation unless --since was passed
  until: string;             // ISO timestamp; now unless --until was passed
  seconds: number;           // billable machine-seconds inside the window
  dollars: number;           // seconds at list price
  secondsPerDollar: number;  // 100000
  running: boolean;          // the meter is still moving (false while a refused stop holds it paused)
}

ConfigResult

type ConfigResult = {
  path: string;
  apiUrl: string | null;
  channel: string | null;
  loggedIn: boolean;
}

LimitsResult

type LimitsResult = {
  activeSandboxes: number;
  maxActiveSandboxes: number;
  maxCreationRequestsPerMinute: number;
  maxCreationRequestsPerDay: number | null;
  startLimits: { perMinute: number; perHour: number; perDay: number } | null;
  starts: {
    unlimited: boolean;
    minute: { limit: number; used: number; remaining: number } | null;
    hour: { limit: number; used: number; remaining: number } | null;
    day: { limit: number; used: number; remaining: number } | null;
  };
  activeStates: string[];
  hasSubscription: boolean;
  hasPaymentHistory: boolean;
  accountPlan: "user" | "service" | string;
  plan: "service" | string | null;
  planName: string | null;
  serviceAccount: boolean;
  unlimited: boolean;
  billingStatus: string;
  subscriptionStatus: string;
  subscriptionCancelAtPeriodEnd: boolean;
  subscriptionTrialEndsAt: string | null;
  subscriptionCurrentPeriodEnd: string | null;
  checkoutRequired: boolean;
  canStart: boolean;
  startBlockedReason: "subscription_required" | "usage_depleted" | string | null;
  blockedReason: "subscription_required" | "usage_depleted" | string | null;
  accessTier: "trial" | "standard" | "service" | string;
  creditBalanceSeconds: number;
  creditBalanceHours: number | null;
  subscriptionQuotaSeconds: number;
  subscriptionRemainingSeconds: number;
  packBalanceSeconds: number;
  packBalanceHours: number;
  packBalanceDollars: number;
  creditPurchasedSeconds: number;
  creditUsedSeconds: number;
  liveUsageSeconds: number;
  creditSecondsPerDollar: number;
  package: {
    dollars: number;
    seconds: number;
    secondsPerDollar: number;
  };
  currentLimits: {
    activeSandboxes: number;
    creationRatePerMinute: number;
    creationRequestsPerDay: number | null;
  };
  standardLimits: {
    activeSandboxes: number;
    creationRatePerMinute: number;
    creationRequestsPerDay: number | null;
  };
  trialLimits: {
    activeSandboxes: number;
    creationRatePerMinute: number;
    creationRequestsPerDay: number | null;
  };
  upgradeEffects: Record<string, unknown>;
  contactMessage: string;
}

Create a sandbox

boat new --json emits JSONL, not a single JSON object.

{"event":"created","id":"bx_8pqt6dup","ttlSeconds":3600}
{"event":"state","id":"bx_8pqt6dup","state":"provisioning"}
{"event":"state","id":"bx_8pqt6dup","state":"ready"}
{"event":"ready","id":"bx_8pqt6dup","state":"ready","url":"https://example-sandbox.on.boat.dev","ip":"203.0.113.10","desktopUrl":"https://example-desktop.on.boat.dev/stream.html?hostId=...&token=...","archiveAfter":"2026-05-28T17:00:33.162Z","commands":{"ssh":"boat ssh bx_8pqt6dup","forward":"boat forward bx_8pqt6dup --remote 3000 --local 3000"}}

Schema:

type NewCreatedLine = {
  event: "created";
  id: string;
  ttlSeconds: number | null;
}

type NewStateLine = {
  event: "state";
  id: string;
  state: Sandbox["state"];
}

type NewReadyLine = {
  event: "ready";
  id: string;
  state: Sandbox["state"];
  url: string | null;
  ip: string | null;
  desktopUrl: string | null;
  archiveAfter: string | null;
  commands: {
    ssh: string;
    forward: string;
  };
}

Prompt and events

boat prompt --provider codex <id> "..." --json first emits a queued line:

{
  "event": "queued",
  "data": {
    "id": "bx_chm52eme",
    "promptId": "09690a68-5aee-4b35-a2e7-eb1b64e3e104",
    "status": "queued",
    "provider": "codex",
    "model": null,
    "reasoningEffort": null
  }
}

{
  "event": "chat",
  "final": true,
  "data": {
    "id": "a75c1426-23bf-4eae-9131-c957046a2af5",
    "taskId": "09690a68-5aee-4b35-a2e7-eb1b64e3e104",
    "type": "response",
    "timestamp": 1779986896114,
    "data": {
      "content": "sandbox-jsonl-audit-ok",
      "is_reverted": false,
      "model": "gpt-5.4"
    }
  }
}

Schema:

type QueuedLine = {
  event: "queued";
  data: {
    id: string;
    promptId: string;
    conversationId: string;  // the conversation this prompt runs in
    status: "queued";
    provider: "codex" | "claude-code" | "pi" | "opencode" | "prime-agent" | "kimi" | string;
    model?: string | null;
    reasoningEffort?: string | null;
  };
}

type ChatLine = {
  event: "chat";
  final: boolean;          // false for streaming partial response events
  data: {
    id?: string;
    type: "prompt" | "response" | "usage_limit" | string;
    timestamp?: number;   // Unix epoch milliseconds
    taskId?: string;
    conversationId?: string | null;  // which conversation this event belongs to
    data: Record<string, unknown>;
  };
}

response chat events can include tool data in data.tools; keep the full object if you need exact agent traces.

Bash JSONL parser

set -euo pipefail

boat login "$BOAT_API_KEY" --json >/dev/null

sandbox_id=""
while IFS= read -r line; do
  event="$(printf '%s\n' "$line" | jq -r '.event')"
  case "$event" in
    created)
      sandbox_id="$(printf '%s\n' "$line" | jq -r '.id')"
      ;;
    ready)
      ip="$(printf '%s\n' "$line" | jq -r '.ip // empty')"
      echo "ready: $sandbox_id $ip"
      ;;
    error)
      printf '%s\n' "$line" >&2
      exit 1
      ;;
  esac
done < <(boat new --ttl 3600 --json)

boat info "$sandbox_id" --json
boat stop "$sandbox_id" --json

Node.js

Use a single-object helper for commands like info, and a JSONL helper for commands like new.

import { spawnSync, spawn } from "node:child_process";
import { createInterface } from "node:readline";

class SandboxCliError extends Error {
  constructor(line, fallback) {
    super(line?.error || fallback);
    this.name = "SandboxCliError";
    this.code = line?.code;
    this.status = line?.status;
    this.line = line;
  }
}

function parseErrorLine(output) {
  const lastLine = output.trim().split(/\r?\n/).filter(Boolean).at(-1);
  if (!lastLine) return null;
  try {
    const parsed = JSON.parse(lastLine);
    return parsed.event === "error" ? parsed : null;
  } catch {
    return null;
  }
}

function sandboxJson(args) {
  const result = spawnSync("boat", [...args, "--json"], {
    encoding: "utf8",
    stdio: ["ignore", "pipe", "pipe"],
  });

  if (result.status !== 0) {
    throw new SandboxCliError(
      parseErrorLine(result.stdout),
      result.stderr || `sandbox ${args.join(" ")} failed`
    );
  }

  return JSON.parse(result.stdout);
}

async function* sandboxJsonLines(args) {
  const child = spawn("boat", [...args, "--json"], {
    stdio: ["ignore", "pipe", "pipe"],
  });
  const rl = createInterface({ input: child.stdout });
  let lastError = null;

  for await (const line of rl) {
    if (!line.trim()) continue;
    const parsed = JSON.parse(line);
    if (parsed.event === "error") lastError = parsed;
    yield parsed;
  }

  const exitCode = await new Promise((resolve) => child.on("close", resolve));
  if (exitCode !== 0) {
    throw new SandboxCliError(lastError, `sandbox ${args.join(" ")} exited with ${exitCode}`);
  }
}

sandboxJson(["login", process.env.BOAT_API_KEY]);

let sandboxId;
for await (const line of sandboxJsonLines(["new", "--ttl", "3600"])) {
  if (line.event === "created") sandboxId = line.id;
  if (line.event === "ready") console.log("ready", line);
}

console.log(sandboxJson(["info", sandboxId]));
sandboxJson(["stop", sandboxId]);

Python

import json
import os
import subprocess


class SandboxCliError(Exception):
    def __init__(self, line, fallback):
        super().__init__((line or {}).get("error") or fallback)
        self.line = line
        self.code = (line or {}).get("code")
        self.status = (line or {}).get("status")


def parse_error_line(output):
    lines = [line for line in output.splitlines() if line.strip()]
    if not lines:
        return None
    try:
        parsed = json.loads(lines[-1])
    except json.JSONDecodeError:
        return None
    return parsed if parsed.get("event") == "error" else None


def sandbox_json(*args):
    result = subprocess.run(
        ["boat", *args, "--json"],
        text=True,
        capture_output=True,
    )
    if result.returncode != 0:
        raise SandboxCliError(
            parse_error_line(result.stdout),
            result.stderr or f"sandbox {' '.join(args)} failed",
        )
    return json.loads(result.stdout)


def sandbox_json_lines(*args):
    process = subprocess.Popen(
        ["boat", *args, "--json"],
        text=True,
        stdout=subprocess.PIPE,
        stderr=subprocess.PIPE,
    )
    assert process.stdout is not None
    last_error = None
    for line in process.stdout:
        if line.strip():
            parsed = json.loads(line)
            if parsed.get("event") == "error":
                last_error = parsed
            yield parsed
    exit_code = process.wait()
    if exit_code != 0:
        stderr = process.stderr.read() if process.stderr else ""
        raise SandboxCliError(last_error, stderr or f"sandbox {' '.join(args)} exited with {exit_code}")


sandbox_json("login", os.environ["BOAT_API_KEY"])

sandbox_id = None
for event in sandbox_json_lines("new", "--ttl", "3600"):
    if event["event"] == "created":
        sandbox_id = event["id"]
    if event["event"] == "ready":
        print("ready", event)

print(sandbox_json("info", sandbox_id))
sandbox_json("stop", sandbox_id)

Direct SSH

The CLI manages the SSH key. For an interactive shell, prefer:

boat ssh "$sandbox_id"
boat scp ./local-file.txt "$sandbox_id:/home/user/local-file.txt"

boat ssh "$sandbox_id" "cd /home/user/ariana-ide-private && npm test"
boat ssh "$sandbox_id" -- bash -lc "cd /home/user/ariana-ide-private && npm test"
boat ssh "$sandbox_id" -- bash -s < ./setup.sh

For direct SSH, inspect the sandbox for its IP and use the CLI-managed key:

ip="$(boat info "$sandbox_id" --json | jq -r '.sandbox.ip // empty')"
ssh -i ~/.ssh/ascii_box_ed25519 "user@$ip"

​Authenticate

​Output contract

​Setup Scripts and Secrets

​Prompt and events

​Bash JSONL parser

​Node.js

​Python

​Direct SSH

​Errors

​The error line

​Backend error shapes

​Backend error codes

​Local CLI errors

​Common types

​Boat

​SandboxListResult

​SandboxInfoResult

​SandboxActionResult

​DesktopResult

​HostResult

​VncDesktopResult

​ApiKeySecretResult

​ApiKeyListResult

​SandboxUsageResult

​ConfigResult

​LimitsResult

​Create a sandbox

​Prompt and events

​Bash JSONL parser

​Node.js

​Python

​Direct SSH

​Related

Authenticate

Output contract

Setup Scripts and Secrets

Prompt and events

Bash JSONL parser

Node.js

Python

Direct SSH

Errors

The error line

Backend error shapes

Backend error codes

Local CLI errors

Common types

Boat

SandboxListResult

SandboxInfoResult

SandboxActionResult

DesktopResult

HostResult

VncDesktopResult

ApiKeySecretResult

ApiKeyListResult

SandboxUsageResult

ConfigResult

LimitsResult

Create a sandbox

Prompt and events

Bash JSONL parser

Node.js

Python

Direct SSH

Related