Run the CLI with Docker¶

The server image also contains the complete bbk CLI, and the bbk wrapper script in scripts/ runs it as if it were installed. With the wrapper on your PATH, every bbk command in these docs works as written, including pipes, bbk mcp, and bbk web, with no Rust toolchain and nothing to compile.

Install the wrapper¶

From a checkout, as in the Quick start:

mkdir -p ~/.local/bin && install -m 755 scripts/bbk ~/.local/bin/   # Linux, macOS, WSL, Git Bash

Copy-Item scripts\bbk.ps1, scripts\bbk.cmd "$HOME\bin"   # Windows: any folder on your PATH

Without a checkout, for example on a laptop that only talks to a remote server, download it instead:

curl -fsSL https://raw.githubusercontent.com/brian-summers/blackbook/main/scripts/bbk -o ~/.local/bin/bbk && chmod +x ~/.local/bin/bbk

foreach ($f in 'bbk.ps1', 'bbk.cmd') { Invoke-WebRequest "https://raw.githubusercontent.com/brian-summers/blackbook/main/scripts/$f" -OutFile "$HOME\bin\$f" }

With no local server, the first run pulls briansummers/blackbook:latest from Docker Hub. The image is built for linux/amd64; Docker Desktop on Apple silicon runs it under emulation.

What it does for you¶


Your logins	Profiles live in the `bbk-home` Docker volume (`~/.bbk` inside the container), encrypted under your passphrase as always. `bbk unlock` carries over from one command to the next.
Your files	The current directory is mounted at `/work`, so relative paths work. Files outside it aren't visible to the container.
A server on this machine	While the `blackbook-app` container runs, the CLI uses the same image (so CLI and server versions match), joins its network, and reaches it at the address bundles name by default, `https://127.0.0.1:8443`.
Remote servers	Reached directly, the same as from a native install.
A terminal	Attached only when you're at one, so pipes and MCP's stdin and stdout stay byte-exact.
Passphrases	`BLACKBOOK_PASSPHRASE` and the other `BLACKBOOK_*` variables are forwarded when set, so passphrases never appear on a command line.
`bbk web`	The console is published on `http://127.0.0.1:8088`, reachable from your machine only.
Hardening	Read-only root filesystem, every Linux capability dropped, and `no-new-privileges`.

Optional settings:

Variable	Default	Purpose
`BBK_IMAGE`	the local server's image, else `briansummers/blackbook:latest`	Image to run. Pin a release with, e.g., `briansummers/blackbook:v0.1.0`.
`BBK_VOLUME`	`bbk-home`	Volume that holds your profiles.
`BBK_NETWORK`	the local server's network	Docker network to join. `none` cuts the container off entirely.
`BBK_SERVER`	`blackbook-app`	Container name of the local server.
`BBK_PUBLISH`	none	Extra ports to publish, space-separated, e.g. `127.0.0.1:5432:5432` for a tunnel.

AI agents (MCP)¶

An MCP client only needs the wrapper on PATH:

bbk -P agent unlock --ttl-minutes 60
claude mcp add blackbook -- bbk -P agent mcp                        # native Windows: -- cmd /c bbk -P agent mcp
claude mcp add blackbook -e BBK_NETWORK=none -- bbk mcp --offline   # crypto tools only, no network at all

Good to know¶

Tunnels listen inside the container, so listen on all interfaces there and publish the port: BBK_PUBLISH=127.0.0.1:5432:5432 bbk tunnel forward bob --listen 0.0.0.0:5432 --to 10.0.0.5:5432. On the accepting side, the container dials the --to address.
On Linux, the container runs as uid 1000, so commands that write files (-o, file get) need the current directory to be writable by that uid.
In PowerShell, piping a string to a program appends a CRLF line ending, so use --text or a file when the exact bytes matter. If PowerShell refuses to run bbk.ps1, allow local scripts once with Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.
To keep a bundle off the disk, pipe it in. There's no terminal for a prompt then, so set BLACKBOOK_PASSPHRASE first: docker exec blackbook-app cat /opt/blackbook/data/admin-bundle.json | bbk login -

Without the wrapper¶

For CI, or anywhere you'd rather spell it out, it's one docker run:

docker run --rm -i -v bbk-home:/home/blackbook/.bbk -v "$PWD:/work" -w /work \
  -e BLACKBOOK_PASSPHRASE briansummers/blackbook:latest get api-key

Add -t for passphrase prompts. To reach a server on the same machine, also join its network (docker network ls shows the name) and point loopback addresses at it: --network blackbook_blackbook_network -e BLACKBOOK_LOOPBACK_SERVER=blackbook-app:8443.