Use in Docker

Use a Boat API key for Docker images, servers, CI jobs, and hosted workers. Create and store the key as BOAT_API_KEY; see API Keys for setup, rotation, and deletion.

Docker image

Install the Boat CLI and OpenSSH client in the image. Authenticate at runtime.

Debian / Ubuntu

FROM debian:bookworm-slim

RUN apt-get update \
    && apt-get install -y --no-install-recommends \
        ca-certificates \
        curl \
        openssh-client \
    && rm -rf /var/lib/apt/lists/*

RUN set -eux; \
    arch="$(uname -m)"; \
    case "$arch" in \
        x86_64|amd64) sandbox_arch="x64" ;; \
        arm64|aarch64) sandbox_arch="arm64" ;; \
        *) echo "Unsupported arch: $arch" >&2; exit 1 ;; \
    esac; \
    curl -fsSL "https://boat.dev/api/boat/cli/download?platform=linux-${sandbox_arch}&channel=prod" \
        -o /usr/local/bin/boat; \
    chmod +x /usr/local/bin/boat; \
    mkdir -p /root/.config/ascii/boat; \
    printf '{\n  "api_url": "https://ascii.dev",\n  "channel": "prod"\n}\n' \
        > /root/.config/ascii/boat/config.json

Alpine

FROM alpine:3.20

RUN apk add --no-cache ca-certificates curl openssh-client

RUN set -eux; \
    arch="$(uname -m)"; \
    case "$arch" in \
        x86_64|amd64) sandbox_arch="x64" ;; \
        arm64|aarch64) sandbox_arch="arm64" ;; \
        *) echo "Unsupported arch: $arch" >&2; exit 1 ;; \
    esac; \
    curl -fsSL "https://boat.dev/api/boat/cli/download?platform=linux-${sandbox_arch}&channel=prod" \
        -o /usr/local/bin/boat; \
    chmod +x /usr/local/bin/boat; \
    mkdir -p /root/.config/ascii/boat; \
    printf '{\n  "api_url": "https://ascii.dev",\n  "channel": "prod"\n}\n' \
        > /root/.config/ascii/boat/config.json

Run boat login before the first sandbox command in your process:

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

For a Railway start command, use the same pattern:

boat login --key-stdin --json <<< "$BOAT_API_KEY" && npm start

If your app starts sandboxes directly, keep login in the entrypoint:

#!/usr/bin/env sh
set -eu

boat login --key-stdin --json <<< "$BOAT_API_KEY"
exec node server.js

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

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

For scripts, prefer --json on login too. It keeps stdout machine-readable and makes failed auth return the standard JSON error line. See API Keys for key setup guidance.

JSON and JSONL

Most read/update commands emit one JSON object:

boat list --json
boat info bx_8pqt6dup --json
boat limits --json
boat stop bx_8pqt6dup --json

Long-running commands emit JSON Lines:

boat new --json
boat prompt --provider codex bx_8pqt6dup "summarize this repo" --json
boat events bx_8pqt6dup --follow --json

Each line is a complete JSON object with an event field. Most runtime failures in --json mode emit a final {"event":"error",...} line. Argument parsing errors can still be emitted by the CLI parser on stderr before Boat’s JSON error handler runs. See Use in Code for exact schemas, error formats, and parsers. When every user of your product needs a sandbox with the same stack pre-installed, build it once and fork it per user. See Template Sandboxes. For secrets used inside sandboxes, see Environments.

​Docker image

​Runtime login

​JSON and JSONL

Docker image

Runtime login

JSON and JSONL