Docker Sandbox (sbx) Kit

The Docker Sandbox (sbx) kit runs a locked Python workspace inside a Docker Sandbox microVM. Its included example is a deterministic, non-agent echo bot: it repeats each Band message without a model or reasoning loop. Replace the example entrypoint with any runnable Python agent.

If you already have runnable Python agent code, complete the sandbox setup first, then follow Replace the Echo Bot with an Agent to connect it.

The published Docker image is named bandhq/band-python-kit-image. The kit installs no dependencies into your host environment, synchronizes the workspace’s committed uv.lock, and starts the configured entrypoint whenever the sandbox starts.

Which Sandbox Setup to Use

Pin published versions, review each network policy, and validate the setup before you use production credentials.

How It Works

The sandbox contains two Python environments:

• The kit environment runs the launcher and reports configuration or startup failures.
• The workspace environment contains only the dependencies selected by your uv.lock.

The launcher reads band.yaml, creates the workspace environment outside the mounted workspace, and replaces itself with the configured entrypoint. Signals from sbx stop therefore reach your process directly.

Prerequisites

• macOS. This guide’s credential storage and recovery steps use the macOS Keychain (security) and Terminal.app; they do not apply on Linux, where Docker Sandboxes uses a different secret-storage backend.
• Docker Desktop and Docker Sandboxes (sbx), tested with v0.43.0
• uv on the host
• Exactly one Band credential path:
  • New Band identity: A user API key that can register an agent. On Band Cloud, user API keys require the Enterprise plan; on other plans, registration returns 403 with plan_required. Without Enterprise, create the agent in the web app and use the existing identity path.
  • Existing Band identity: The existing agent ID and agent API key

Set Up Docker Sandboxes

Both credential paths need these steps.

brew install docker/tap/sbx
sbx login

sbx policy ls

sbx policy init balanced

export BAND_KIT_VERSION=3.1.1
export BAND_KIT_SOURCE_COMMIT=8a26713f70678b4a5ef1cbed27f8190c8474ea79
export BAND_KIT_IMAGE_DIGEST=sha256:f6ed66a631e2ce239686f06959aafe4ff26a0c502aee3542f8f26948a88a22e5
export BAND_KIT_DIR="$HOME/.config/band/band-python-kit-${BAND_KIT_VERSION}-sbx-v1"
mkdir -p "$BAND_KIT_DIR"
curl -fsSL \
  "https://raw.githubusercontent.com/band-ai/band-sdk-python/${BAND_KIT_SOURCE_COMMIT}/docker/band_python_kit/spec.yaml" \
  -o "$BAND_KIT_DIR/spec.yaml"
/usr/bin/sed -i '' \
  -e '1,5d' \
  -e 's/schemaVersion: "2"/schemaVersion: "1"/' \
  -e "s|image: band-python-kit:local|image: docker.io/bandhq/band-python-kit-image:${BAND_KIT_VERSION}@${BAND_KIT_IMAGE_DIGEST}|" \
  "$BAND_KIT_DIR/spec.yaml"
sbx kit validate "$BAND_KIT_DIR"
sbx kit inspect "$BAND_KIT_DIR"

mkdir -p "$HOME/my-band-agent"
curl -fsSL "https://codeload.github.com/band-ai/band-sdk-python/tar.gz/refs/tags/band-sdk-v${BAND_KIT_VERSION}" \
  | tar -xz --strip-components=4 -C "$HOME/my-band-agent" \
      "band-sdk-python-band-sdk-v${BAND_KIT_VERSION}/docker/band_python_kit/echo-agent"

New Band Identity: Self-Registration

security unlock-keychain "$HOME/Library/Keychains/login.keychain-db"
sbx secret set-custom \
  --sandbox band-keychain-preflight \
  --host keychain-preflight.invalid \
  --env BAND_KEYCHAIN_PREFLIGHT \
  --placeholder band-keychain-preflight \
  --value not-a-secret
sbx secret rm \
  --sandbox band-keychain-preflight \
  --placeholder band-keychain-preflight \
  --force

export BAND_API_KEY_USER="<your-user-api-key>"
uvx --from "band-sdk==${BAND_KIT_VERSION}" band-kit provision \
  --name my-band-agent \
  --agent-name "My Sandbox Echo" \
  --description "A deterministic echo bot running in a Docker Sandbox." \
  --workspace "$HOME/my-band-agent" \
  --no-create

sbx run "$BAND_KIT_DIR" \
  --name my-band-agent \
  "$HOME/my-band-agent"

Existing Band Identity: Create Only the Sandbox

Use this path instead of self-registration when the agent already exists in Band. Do not run band-kit provision. If you do not have the agent yet, create it and save its ID and API Key by following the Quickstart.

agent:
  id: "<your-agent-uuid>"
  entrypoint: main.py

export BAND_KIT_VERSION=3.1.1
export BAND_KIT_DIR="$HOME/.config/band/band-python-kit-${BAND_KIT_VERSION}-sbx-v1"
printf "Agent API key: "
read -r -s BAND_API_KEY
printf "\n"
printf '%s' "$BAND_API_KEY" | sbx secret set-custom \
  --sandbox my-band-agent \
  --host '**.band.ai' \
  --env BAND_API_KEY \
  --placeholder proxy-managed
unset BAND_API_KEY
sbx run "$BAND_KIT_DIR" \
  --name my-band-agent \
  "$HOME/my-band-agent"

Verify the Echo Bot

Keep the attached terminal open. In a second host terminal, verify that Docker started the sandbox and its background agent process:

sbx ls
sbx exec my-band-agent cat /var/log/sbx-kit-startup.log

sbx ls must show my-band-agent with status running. The startup log should include Launching customer entrypoint for main.py and no later error. A running sandbox confirms that Docker started the environment. The echo reply confirms that the agent also connected to Band.

In Band, add the agent to a room, then send a new message after the sandbox is running. With self-registration, the agent is My Sandbox Echo:

@My Sandbox Echo hello from Band

The non-agent echo bot sends an echo: reply containing the received message from inside the sandbox.

After this smoke test passes, follow Replace the Echo Bot with an Agent to replace the starter with your own runnable Python agent.

Recover from a Keychain Failure

The preflight exposes Docker secret-storage failures before agent registration. A failed preflight does not create a Band identity. If provisioning had already registered an identity before storage failed, keep its printed key private. On macOS, recovery cannot continue until both sbx login and the Keychain preflight succeed.

Keychain Not Found During Preflight

Choose Cancel in the dialog. Do not choose Reset To Defaults as a troubleshooting shortcut. Apple states that resetting the default Keychain deletes all passwords stored in it and requires logging out and back in.

The next three commands only inspect your user Keychain configuration. They print the default Keychain, the Keychain search list, and whether the expected login Keychain can be opened. They do not change or delete Keychain data.

security default-keychain -d user
security list-keychains -d user
security show-keychain-info "$HOME/Library/Keychains/login.keychain-db"

If those commands identify the login Keychain, restart the Docker Sandboxes daemon as your logged-in user. The commands below stop any user-owned daemon, then start a fresh one with the current desktop user’s Keychain context. Do not run them with sudo.

sbx daemon stop
sbx daemon start

Run the preflight again from Terminal.app in an active macOS desktop session. Avoid SSH, sudo, and background launch contexts. Docker has confirmed that a locked Keychain in an SSH session prevents sbx from reading credentials in docker/sbx-releases#486, and a root-started daemon caused a separate macOS credential-store failure in docker/sbx-releases#77.

If the dialog still appears, do not register an agent. The following command generates Docker diagnostics as a local GitHub issue report. Review it for sensitive paths or values before sharing it on the Docker Sandboxes issue tracker.

sbx diagnose --output github-issue

No File-Backed Keychain Bypass on macOS

Docker documents that macOS stores both literal values and dynamic secret sources in the system Keychain. --command and --ref change how Docker resolves a secret, but their source configuration still uses Docker’s Keychain-backed secret store. sbx login --password-stdin also persists the resulting Docker credential in Keychain.

Docker’s automatic file-backed secret store is available only on Linux when no Secret Service is running. It is not a macOS fallback. If sbx login fails while saving credentials, stop. Repair Docker’s Keychain access or run the sandbox from a supported Linux host before continuing. Do not run band-kit provision, because it can register a Band identity before the local Docker operation fails.

If an earlier version of this guide caused you to save a still-private key at ~/.config/band/my-band-agent-api-key, leave the mode-600 file in place until Keychain access is repaired. Do not print or paste its contents. After sbx login and the Keychain preflight both succeed, the commands below import that key into Docker’s secret store.

export BAND_KIT_VERSION=3.1.1
export BAND_KIT_DIR="$HOME/.config/band/band-python-kit-${BAND_KIT_VERSION}-sbx-v1"
BAND_SECRET_FILE="$HOME/.config/band/my-band-agent-api-key"
/bin/cat "$BAND_SECRET_FILE" | sbx secret set-custom \
  --sandbox my-band-agent \
  --host '**.band.ai' \
  --env BAND_API_KEY \
  --placeholder proxy-managed

Continue only when sbx secret set-custom succeeds. The next commands delete the plaintext file, remove its path from the shell, then start and attach to the sandbox.

rm -f "$BAND_SECRET_FILE"
unset BAND_SECRET_FILE
sbx run "$BAND_KIT_DIR" \
  --name my-band-agent \
  "$HOME/my-band-agent"

Provisioning Failed, Key Still Private

Do not rerun band-kit provision. The failed command already registered the Band identity and wrote its ID to band.yaml.

The commands below unlock your login Keychain, read the printed agent key without displaying it or saving it in shell history, pipe it to sbx using the current --sandbox syntax, and remove it from the shell. The final command starts and attaches to the sandbox that provisioning did not reach.

export BAND_KIT_DIR="$HOME/.config/band/band-python-kit-3.1.1-sbx-v1"
security unlock-keychain "$HOME/Library/Keychains/login.keychain-db"
printf "Agent API key: "
read -r -s BAND_API_KEY
printf "\n"
printf '%s' "$BAND_API_KEY" | sbx secret set-custom \
  --sandbox my-band-agent \
  --host '**.band.ai' \
  --env BAND_API_KEY \
  --placeholder proxy-managed
unset BAND_API_KEY
sbx run "$BAND_KIT_DIR" \
  --name my-band-agent \
  "$HOME/my-band-agent"

If Keychain storage fails again, keep the key private and stop. Do not create the sandbox until sbx secret set-custom succeeds.

The Key Is Lost or Exposed

Treat a key copied into chat, an issue, or shared logs as exposed. Do not inject it into the sandbox.

1. Delete the orphaned identity from Band. You can use Band’s agent management interface or the DELETE /api/v1/me/agents/{id} endpoint.
2. Restore agent.id: replace-with-agent-id in the starter’s band.yaml.
3. Complete the Keychain preflight.
4. Run self-registration again. Use a new --agent-name if the orphaned identity could not be deleted.

An orphaned identity still counts against your plan’s agent limit until you delete it.

Credential Custody

The echo bot starter uses credentials.source: proxy-managed.

The real Band key does not enter the VM. The SDK sends the sentinel in the normal authentication field, and the proxy replaces it only for the configured Band host.

After sbx login succeeds, a plaintext workspace env file can bypass proxy-managed agent-secret storage, but it stores the real credential in both the mounted workspace and the VM. It does not bypass Docker authentication. Use it only when proxy injection is unavailable. The annotated band.yaml shows the required acknowledgement and file path.

Replace the Echo Bot with an Agent

The starter’s main.py uses a deterministic echo adapter and no model. Replace it with any runnable Python agent. Keep agent.entrypoint in band.yaml pointed at the file that starts your process.

For a Band framework adapter:

1. Replace the echo adapter in main.py, or replace the file and update agent.entrypoint.
2. Add the matching band-sdk extra and any application dependencies to pyproject.toml.
3. Store each provider credential on the host.
4. Allow only the network hosts the agent needs.
5. Regenerate and commit uv.lock.

For example, the first command below stores an Anthropic key in Docker’s host-side secret store. The second permits this sandbox to reach Anthropic. The third resolves the workspace dependencies and updates uv.lock.

sbx secret set -g anthropic
sbx policy allow network --sandbox my-band-agent api.anthropic.com
uv lock

After changing dependencies, stop and restart the sandbox. This makes the kit launcher synchronize the updated lockfile before it executes your entrypoint:

sbx stop my-band-agent
sbx run --name my-band-agent

Network Access

The kit’s baseline allows Band Cloud plus pypi.org and files.pythonhosted.org, which are required to synchronize locked dependencies in a fresh sandbox. LLM providers, source-control hosts, custom APIs, and non-production Band deployments require explicit per-sandbox rules.

The following commands allow only OpenAI’s API and GitHub for my-band-agent. Add a host only when the code inside that sandbox needs it:

sbx policy allow network --sandbox my-band-agent api.openai.com
sbx policy allow network --sandbox my-band-agent github.com

Kit rules are part of the effective sandbox policy, not a complete statement of everything reachable. A selected base policy or organization governance can add, restrict, or override access.

The next command displays allowed and blocked requests for this sandbox so you can identify the exact host behind a failed network call:

sbx policy log my-band-agent

Troubleshooting

Source Reference

• Docker Sandbox (sbx) kit release source
• Non-agent echo bot workspace
• Docker Sandbox kits
• Docker sbx secret set-custom CLI reference
• Docker Sandbox credential storage

Next Steps