Use in Code

box login "$BOX_API_KEY" --json

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

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

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

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

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

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

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

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

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

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

type BoxApiError =
  | BasicBoxApiError
  | BlockedBoxApiError
  | RateLimitedBoxApiError
  | ProviderNotConfiguredError
  | BoxNotPromptableError
  | StopFailedError
  | SshKeyError;

type BasicBoxApiError = {
  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";
  message?: string;
}

type BoxLimitFields = {
  activeStates: ["provisioned", "cloning", "ready", "idle", "running"];
  activeBoxes: number;
  maxActiveBoxes: number;
  maxCreationRequestsPerMinute: number;
  maxCreationRequestsPerDay: number | null;
  currentLimits: {
    activeBoxes: number;
    creationRatePerMinute: number;
    creationRequestsPerDay: number | null;
  };
  standardLimits: {
    activeBoxes: number;
    creationRatePerMinute: number;
    creationRequestsPerDay: number | null;
  };
  trialLimits: {
    activeBoxes: number;
    creationRatePerMinute: number;
    creationRequestsPerDay: number | null;
  };
}

type BoxBillingFields = {
  hasSubscription: boolean;
  hasPaymentHistory: 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" | string;
  creditBalanceSeconds: number;
  subscriptionQuotaSeconds: number;
  subscriptionRemainingSeconds: number;
  packBalanceSeconds: number;
  creditPurchasedSeconds: number;
  creditUsedSeconds: number;
  liveUsageSeconds: number;
  creditSecondsPerDollar: number;
  package: {
    dollars: number;
    seconds: number;
    secondsPerDollar: number;
  };
  upgradeEffects: {
    startTrial: {
      canCreate: true;
      activeBoxes: number;
      creationRequestsPerDay: number;
      note: string;
    };
    endTrialOrFirstPayment: {
      activeBoxes: number;
      creationRequestsPerDay: null;
      note: string;
    };
    pack: {
      seconds: number;
      persistsAcrossMonths: true;
      note: string;
    };
  };
  contactMessage: string;
}

type BlockedBoxApiError = (BoxLimitFields & BoxBillingFields) & {
  error: "billing_required" | "box_access_inactive" | "daily_limit_reached" | "limit_reached";
  status: "blocked";
  message: string;
  billingUrl: string;
}

type RateLimitedBoxApiError = {
  error: "rate_limited";
  status: "blocked";
  message: string;
  maxCreationRequestsPerMinute: number;
}

type ProviderNotConfiguredError = {
  error: "provider_not_configured";
  provider: "codex" | "claude-code";
  setupUrl: string;
  message: string;
}

type BoxNotPromptableError = {
  error: "box_not_promptable";
  state: string;
  message: string;
}

type StopFailedError = {
  error: "stop_failed";
  message: string;
  box: Box | null;
}

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

type Box = {
  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 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 `box list --json`
}

type BoxListResult = {
  boxes: Box[];
  pageInfo?: {
    hasMore: boolean;
    limit: number;
    nextCursor: string | null;
  };
}

{
  "boxes": [
    {
      "id": "bx_8pqt6dup",
      "name": "Box 2026-05-28 16:00",
      "state": "idle",
      "url": "https://example-box.on.ascii.dev",
      "ip": "203.0.113.10",
      "desktopAvailable": true,
      "desktopUrl": "https://example-desktop.on.ascii.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
    }
  ]
}

type BoxInfoResult = {
  box: Box;
}

type BoxActionResult = {
  id: string;
  status: "stopping" | "resuming" | "forking" | string;
  box: Box | null;
}

type DeleteResult = {
  id: string;
  status: "deleted";
}

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

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

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

type LimitsResult = {
  activeBoxes: number;
  maxActiveBoxes: number;
  maxCreationRequestsPerMinute: number;
  maxCreationRequestsPerDay: number | null;
  activeStates: string[];
  hasSubscription: boolean;
  hasPaymentHistory: 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" | string;
  creditBalanceSeconds: number;
  subscriptionQuotaSeconds: number;
  subscriptionRemainingSeconds: number;
  packBalanceSeconds: number;
  creditPurchasedSeconds: number;
  creditUsedSeconds: number;
  liveUsageSeconds: number;
  creditSecondsPerDollar: number;
  package: {
    dollars: number;
    seconds: number;
    secondsPerDollar: number;
  };
  currentLimits: {
    activeBoxes: number;
    creationRatePerMinute: number;
    creationRequestsPerDay: number | null;
  };
  standardLimits: {
    activeBoxes: number;
    creationRatePerMinute: number;
    creationRequestsPerDay: number | null;
  };
  trialLimits: {
    activeBoxes: number;
    creationRatePerMinute: number;
    creationRequestsPerDay: number | null;
  };
  upgradeEffects: Record<string, unknown>;
  contactMessage: string;
}

{"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-box.on.ascii.dev","ip":"203.0.113.10","desktopUrl":"https://example-desktop.on.ascii.dev/stream.html?hostId=...&token=...","archiveAfter":"2026-05-28T17:00:33.162Z","commands":{"ssh":"box ssh bx_8pqt6dup","forward":"box forward bx_8pqt6dup --remote 3000 --local 3000"}}

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

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

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

{
  "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": "box-jsonl-audit-ok",
      "is_reverted": false,
      "model": "gpt-5.4"
    }
  }
}

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" | "git_checkpoint" | string;
    timestamp?: number;   // Unix epoch milliseconds
    taskId?: string;
    data: Record<string, unknown>;
  };
}

set -euo pipefail

box login "$BOX_API_KEY" --json >/dev/null

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

box info "$box_id" --json
box stop "$box_id" --json

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

class BoxCliError extends Error {
  constructor(line, fallback) {
    super(line?.error || fallback);
    this.name = "BoxCliError";
    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 boxJson(args) {
  const result = spawnSync("box", [...args, "--json"], {
    encoding: "utf8",
    stdio: ["ignore", "pipe", "pipe"],
  });

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

  return JSON.parse(result.stdout);
}

async function* boxJsonLines(args) {
  const child = spawn("box", [...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 BoxCliError(lastError, `box ${args.join(" ")} exited with ${exitCode}`);
  }
}

boxJson(["login", process.env.BOX_API_KEY]);

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

console.log(boxJson(["info", boxId]));
boxJson(["stop", boxId]);

import json
import os
import subprocess


class BoxCliError(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 box_json(*args):
    result = subprocess.run(
        ["box", *args, "--json"],
        text=True,
        capture_output=True,
    )
    if result.returncode != 0:
        raise BoxCliError(
            parse_error_line(result.stdout),
            result.stderr or f"box {' '.join(args)} failed",
        )
    return json.loads(result.stdout)


def box_json_lines(*args):
    process = subprocess.Popen(
        ["box", *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 BoxCliError(last_error, stderr or f"box {' '.join(args)} exited with {exit_code}")


box_json("login", os.environ["BOX_API_KEY"])

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

print(box_json("info", box_id))
box_json("stop", box_id)

box ssh "$box_id"
box scp ./local-file.txt "$box_id:/home/user/local-file.txt"

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

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