> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ascii.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Use in Docker

> Install Box in Docker images and authenticate the CLI with an API key.

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](/box/api-keys) for setup, rotation, and deletion.

## Docker image

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

```dockerfile Debian / Ubuntu theme={null}
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
```

```dockerfile Alpine theme={null}
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:

```bash theme={null}
box login "$BOX_API_KEY" --json
box list --json
```

For a Railway start command, use the same pattern:

```bash theme={null}
box login "$BOX_API_KEY" --json && npm start
```

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

```bash theme={null}
#!/usr/bin/env sh
set -eu

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

`box login "$BOX_API_KEY" --json` emits:

```json theme={null}
{
  "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](/box/api-keys) for key setup guidance.

## JSON and JSONL

Most read/update commands emit one JSON object:

```bash theme={null}
box list --json
box info bx_8pqt6dup --json
box limits --json
box stop bx_8pqt6dup --json
```

Long-running commands emit JSON Lines:

```bash theme={null}
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](/box/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](/box/templates).

For secrets used inside Boxes, see [Secrets & Setup](/box/secrets).