Use in Docker

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

Docker image

Install the Box 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) box_arch="x64" ;; \
        arm64|aarch64) box_arch="arm64" ;; \
        *) echo "Unsupported arch: $arch" >&2; exit 1 ;; \
    esac; \
    curl -fsSL "https://ascii.dev/api/box/cli/download?platform=linux-${box_arch}&channel=ascii-prod" \
        -o /usr/local/bin/box; \
    chmod +x /usr/local/bin/box; \
    mkdir -p /root/.config/ascii/box; \
    printf '{\n  "api_url": "https://ascii.dev",\n  "channel": "ascii-prod"\n}\n' \
        > /root/.config/ascii/box/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) box_arch="x64" ;; \
        arm64|aarch64) box_arch="arm64" ;; \
        *) echo "Unsupported arch: $arch" >&2; exit 1 ;; \
    esac; \
    curl -fsSL "https://ascii.dev/api/box/cli/download?platform=linux-${box_arch}&channel=ascii-prod" \
        -o /usr/local/bin/box; \
    chmod +x /usr/local/bin/box; \
    mkdir -p /root/.config/ascii/box; \
    printf '{\n  "api_url": "https://ascii.dev",\n  "channel": "ascii-prod"\n}\n' \
        > /root/.config/ascii/box/config.json

Run box login before the first Box command in your process:

box login "$BOX_API_KEY" --json
box list --json

For a Railway start command, use the same pattern:

box login "$BOX_API_KEY" --json && npm start

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

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

box login "$BOX_API_KEY" --json
exec node server.js

box login "$BOX_API_KEY" --json 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:

box list --json
box info bx_8pqt6dup --json
box limits --json
box stop bx_8pqt6dup --json

Long-running commands emit JSON Lines:

box new --json
box prompt --provider codex bx_8pqt6dup "summarize this repo" --json
box 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 Box’s JSON error handler runs. See Use in Code for exact schemas, error formats, and parsers. When every user of your product needs a Box with the same stack pre-installed, build it once and fork it per user. See Template Boxes. For secrets used inside Boxes, see Secrets & Setup.

​Docker image

​Runtime login

​JSON and JSONL

Docker image

Runtime login

JSON and JSONL