Skip to main content
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

​
Runtime login

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 lifecycle 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. For secrets used inside Boxes, see Secrets & Setup.