Avernet

Docker Guide

简体中文

This guide shows how to build a Docker image from docker/minibcn/Dockerfile.ocb and start a local Avernet stack.

Current limitation: docker/ocb-entrypoint.sh still passes the removed --local flag to Singlebox, so the current container startup fails. The paths below match the repository layout, but do not constitute a verified working Docker startup. Until the Docker entrypoint is updated, use native Quick Start.

The Docker path has two steps:

What is in the image?

Component Description
BCS server Bot Coordination Service written in Rust, exposed on :21000
Frontend workbench Static Avernet frontend built from apps/frontend, exposed on :8000
bcs-cli Command-line tool at /opt/ocb/apps/bcs/target/debug/bcs-cli
Global openclaw command Installed from the public npm registry so OpenClaw can run inside the container or on the host
BCN plugin openclaw-channel-bcn, built from source and symlinked to /root/.openclaw/extensions/openclaw-channel-bcn so OpenClaw can connect to BCS
5 OpenClaw instances After container startup, 5 OpenClaw demo roles run in the container (CEO / 产品经理 / 研发 / 验证 / 客服). Each connects to BCS through the BCN plugin, onboards automatically, and listens on :30001/:30011/:30021/:30031/:30041

The frontend serves the built apps/frontend/dist files and proxies same-origin /bcnproxy/* requests to the BCS server inside the container.

What you need

Install these on your machine first:

Do not write API keys into docker/minibcn/Dockerfile.ocb, and do not commit them to Git. Pass them at container runtime with -e.

Step 1: Build the image

Run this from the repository root:

docker build -f docker/minibcn/Dockerfile.ocb -t ocb:local .

This will:

Network acceleration in mainland China (optional)

The default build uses official sources. Developers outside mainland China can usually run docker build directly. If apt / cargo / npm / Rust toolchain downloads are slow in mainland China, add one build argument:

docker build -f docker/minibcn/Dockerfile.ocb -t ocb:local \
  --build-arg USE_CN_MIRROR=1 \
  .

When enabled, apt uses Aliyun mirrors, cargo uses the Aliyun crates.io sparse index, npm uses npmmirror, and Rust rustup-init plus toolchain dist use the USTC rust-static mirror.

If your registry certificate is temporarily broken, you can disable npm TLS verification for this build:

docker build -f docker/minibcn/Dockerfile.ocb -t ocb:local \
  --build-arg NPM_STRICT_SSL=false \
  .

Open-source defaults should keep TLS verification enabled. Use this only when you clearly understand why it is needed.

Step 2: Start BCS

Replace the three values below with your own values if you want real model calls. They are optional. Without them, the container can still start and is useful for validating BCS / BCN connection / onboard flows; features that require real model calls will not be available.

Build ocb:local from the repository root using Step 1 first. The Compose file is at docker/minibcn/docker-compose.yml; its build context has not yet been updated for that move. The commands below use the already-built image with --no-build, rather than the outdated Compose build definition:

docker compose -f docker/minibcn/docker-compose.yml up --no-build

With Docker Compose, you do not need singlebox/.env.local by default. Create it only when you need to override ports, change the local mock display name, choose a host OpenClaw config directory, or set model API values explicitly:

test -f singlebox/.env.local || cp singlebox/.env.example singlebox/.env.local
# Uncomment or edit optional values in singlebox/.env.local as needed.
docker compose -f docker/minibcn/docker-compose.yml --env-file singlebox/.env.local up --no-build

Docker mounts ${HOME}/.openclaw read-only into the container and tries to reuse its openclaw.json when complete OPENCLAW_OPENAI_* values are not set. This is Docker’s legacy model-source behavior, not the native Singlebox mock / manual / home menu. Native manual mode requires complete OPENCLAW_OPENAI_* values and does not fall back to the host JSON. If the host config directory does not exist, Docker Compose may create an empty directory; startup still continues, but no host model config is reused.

To use another host OpenClaw config directory, set this in singlebox/.env.local:

OPENCLAW_HOST_CONFIG_DIR=/path/to/.openclaw

If you do not have a host OpenClaw config, you can also set these values together in singlebox/.env.local:

OPENCLAW_OPENAI_BASE_URL=https://api.openai.com/v1
OPENCLAW_OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx
OPENCLAW_OPENAI_MODEL_ID=<model-id>

If you prefer plain docker run, pass the same values as environment variables and port mappings:

docker run --rm -it \
  --name ocb-local \
  -p 21000:21000 \
  -p 8000:8000 \
  -e OPENCLAW_OPENAI_BASE_URL=https://api.openai.com/v1 \
  -e OPENCLAW_OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx \
  -e OPENCLAW_OPENAI_MODEL_ID=<model-id> \
  ocb:local

After startup, the container will:

Step 3: Verify BCS

curl http://127.0.0.1:21000/health

200 OK means BCS has started.

Step 4: Open the frontend

http://127.0.0.1:8000/

Keep the 21000 port mapping too. The frontend uses /bcnproxy for HTTP APIs, but BCS WebSocket links still use the host BCS port.

Step 5: Connect to BCS

The web UI is the default path. You can also use these lower-level connection options:

The docker exec, docker cp, log, and stop examples below use the ocb-local name from the docker run --name example. With Compose, use the teamclaw service instead, for example:

docker compose -f docker/minibcn/docker-compose.yml exec teamclaw \
  /opt/ocb/apps/bcs/target/debug/bcs-cli --url http://127.0.0.1:21000 list

Option A: Use bcs-cli inside the container

docker exec -it ocb-local /opt/ocb/apps/bcs/target/debug/bcs-cli \
  --url http://127.0.0.1:21000 onboard \
  --name "My Bot" --summary "Hello bot"

Option B: Copy bcs-cli to the host

docker cp ocb-local:/opt/ocb/apps/bcs/target/debug/bcs-cli ./bcs-cli
./bcs-cli --url http://127.0.0.1:21000 onboard --name "My Bot"

Option C: Run OpenClaw on the host and connect through the BCN plugin

The container already runs 5 OpenClaw instances. This section adds one more host OpenClaw instance connected to the same BCS.

First install public OpenClaw on the host:

npm install -g "openclaw@>=2026.3.28"

There are two ways to make the BCN plugin available to host OpenClaw.

If you already cloned this repository on the host, symlink the source directory to the OpenClaw extensions directory. Source changes take effect in host OpenClaw immediately after the plugin has been built into dist/.

# Run from the repository root.
(
  cd apps/bcs/crates/plugins/openclaw-channel-bcn
  npm install
  npm run build
)

# Symlink to the OpenClaw extensions directory.
mkdir -p ~/.openclaw/extensions
ln -sfn "$(pwd)/apps/bcs/crates/plugins/openclaw-channel-bcn" \
  ~/.openclaw/extensions/openclaw-channel-bcn

# Verify the symlink points to the source checkout.
ls -l ~/.openclaw/extensions/openclaw-channel-bcn

This is the same thing docker/minibcn/Dockerfile.ocb does inside the container, with /opt/ocb replaced by the host repository path.

C-2. Copy from the container with docker cp

Use this if you do not want to install pnpm or build locally, but want to reuse the already built dist/ from the container:

mkdir -p ~/.openclaw/extensions
docker cp ocb-local:/opt/ocb/apps/bcs/crates/plugins/openclaw-channel-bcn \
  ~/.openclaw/extensions/openclaw-channel-bcn

This is a one-time snapshot. Host source changes will not affect the copied plugin. Copy again when you need an update.

Start host OpenClaw

After either C-1 or C-2, start it the same way:

BCS_URL=ws://127.0.0.1:21000/ws/bot \
  openclaw gateway run --port 18789

Register the host OpenClaw instance with BCS:

./apps/bcs/target/debug/bcs-cli --url http://127.0.0.1:21000 onboard \
  --name "Host OpenClaw" \
  --summary "OpenClaw on host machine" \
  --domains "local,openclaw" \
  --skills "openclaw" \
  --scopes "local"

BCS now has 5 OpenClaw instances inside the container plus 1 OpenClaw instance on the host, for a total of 6 bots.

Step 6: Stop the stack

If the container is running in the foreground, press:

Ctrl + C

If the container is running in the background:

docker stop ocb-local

FAQ

1. Model environment variables are not configured

The container can start without model environment variables. This is enough to validate BCS, the BCN plugin, and local bot onboard.

To validate real model calls with Docker Compose, Docker tries to reuse ${HOME}/.openclaw/openclaw.json by default. If you do not have a host OpenClaw config, set these values together in singlebox/.env.local:

OPENCLAW_OPENAI_BASE_URL=<model-api-base-url>
OPENCLAW_OPENAI_API_KEY=<model-api-key>
OPENCLAW_OPENAI_MODEL_ID=<model-id>

For plain docker run, rerun with:

-e OPENCLAW_OPENAI_BASE_URL=<model-api-base-url>
-e OPENCLAW_OPENAI_API_KEY=<model-api-key>
-e OPENCLAW_OPENAI_MODEL_ID=<model-id>

2. Port is already in use

If another program on your machine already uses 21000 or 8000, choose a different port. Docker Compose uses the same value inside the container and on the host.

With Docker Compose, edit these values in singlebox/.env.local:

BCS_PORT=<available-bcs-port>
FRONTEND_PORT=<available-frontend-port>

Then start with:

docker compose -f docker/minibcn/docker-compose.yml --env-file singlebox/.env.local up --no-build

Check BCS with:

set -a
. ./singlebox/.env.local
set +a
curl "http://127.0.0.1:${BCS_PORT:-21000}/health"

Open the frontend with the FRONTEND_PORT value from singlebox/.env.local; if it is not set, the default is http://127.0.0.1:8000/.

3. Dependency download failed

This may be a network issue, or the npm registry may be unreachable.

Developers in mainland China should first try --build-arg USE_CN_MIRROR=1.

4. View logs

The foreground container prints BCS, frontend, and 5 test bot logs.

If you started the container in the background:

docker logs -f ocb-local

5. ARM platform builds are slow

If your Mac is M1/M2/M3, Docker may pull the amd64 image and run through Rosetta by default, which can make builds take 20+ minutes. Use --platform linux/arm64 to build an arm64 image directly. node:22-bookworm-slim is a multi-arch image and supports this.

This is not a production image

docker/minibcn/Dockerfile.ocb is for local trials and integration work.

It starts BCS and 5 test bots in development mode. It is useful for first-time BCS validation, but it is not intended as a production deployment image.

This repository does not currently publish prebuilt Docker images as release artifacts. The Dockerfile is a developer convenience for building and validating the project from source on a local machine.

If official Docker images are published in the future, the release process must generate image-level SBOM and third-party license notices for the final image.