Running with Docker#

Run Blackbox AI in a container with recorded provenance and a persistent data volume.

Before you start#

• Docker with Compose.
• An operator token. The container binds to 0.0.0.0, so Compose requires BLACKBOX_OPERATOR_TOKEN in the environment.

Provenance values#

The image records the commit it was built from and a fingerprint of the source tree. Supply both.

PowerShell:

$env:BLACKBOX_COMMIT_SHA = (git rev-parse HEAD).Trim()
$env:BLACKBOX_SOURCE_SHA256 = (npm run --silent source:fingerprint).Trim()
docker compose up --build

POSIX shells:

BLACKBOX_COMMIT_SHA="$(git rev-parse HEAD)" \
BLACKBOX_SOURCE_SHA256="$(npm run --silent source:fingerprint)" \
docker compose up --build

Build from a clean checkout. A fingerprint taken over a modified tree records a value that matches no commit, which defeats the purpose of recording it.

Data persistence#

Compose persists the data/ directory — including store.json and the canonical evaluation-report slot — in the blackboxai-data volume.

The volume is the world. Removing it removes the world. See Data and backup for how to copy it safely.

Verify#

1. The service answers readiness:

   Copy

   curl -sS http://127.0.0.1:4287/api/ready

2. A Director request without the operator token is refused.

3. Stopping and restarting the stack resumes the same world rather than creating a new one.

If it does not work#