Docker

Running blaise-agent inside Docker makes it easy to deploy on any cloud provider, keep the agent isolated from the host, and manage secrets via environment variables. The container only makes outbound connections to Blaise — no published ports, TLS certificates or tunnels are needed.

This page puts the whole runner in a container, so the runner token lives in the container with the agent. To keep the token outside and run only the agent in a container, use the blaise:docker plug instead.

How it works

Dockerfile

FROM node:22-slim

# Install Claude Code and its ACP adapter globally (the adapter version matches the CLI's)
RUN npm install -g @anthropic-ai/claude-code @agentclientprotocol/[email protected]

# Install Bun, which the Blaise CLI runs on, and then the CLI itself
COPY --from=oven/bun:1 /usr/local/bin/bun /usr/local/bin/bun
ENV BUN_INSTALL=/usr/local
RUN bun add -g @blaiseagent/cli

# Non-root user for security
RUN useradd -m agent
USER agent
WORKDIR /home/agent

# The runner configuration; add plugs to the setup list as needed
COPY --chown=agent blaise.yml ./blaise.yml

CMD ["blaise-agent", "listen"]

Put a blaise.yml next to the Dockerfile. The smallest one has no plugs:

version: 1

Build it:

docker build -t blaise-agent:latest .

Getting a runner token

Containers have no keychain or browser, so create the runner token elsewhere and pass it in:

blaise-agent login --name docker-prod --print-token

The token is printed once and not stored. Keep it in your secret manager; revoke the runner in the dashboard to invalidate it.

Running the container

Pass secrets as environment variables — never bake them into the image.

docker run -d \
  --name blaise-agent \
  -e BLAISE_RUNNER_TOKEN="blr_..." \
  -e LOG_FORMAT=json \
  blaise-agent:latest

docker-compose example

For a typical production setup with automatic restarts and a named secret:

services:
  blaise-agent:
    image: blaise-agent:latest
    build: .
    restart: unless-stopped
    environment:
      BLAISE_RUNNER_TOKEN: "${BLAISE_RUNNER_TOKEN}"
      LOG_FORMAT: json
      LOG_LEVEL: info

Run with:

BLAISE_RUNNER_TOKEN=blr_... docker compose up -d

Environment variables reference

Run more replicas with the same runner token to add capacity: each session is claimed by exactly one of them, and the dashboard counts them as instances of one runner. Replicas should share what paused sessions need (see How sessions find a runner).