docker-sbx-kit

Source repo for the Traces Docker Sandboxes kit.

• Docker Hub: https://hub.docker.com/r/tracesdotcom/traces-sbx-kit
• Published refs:
  • docker.io/tracesdotcom/traces-sbx-kit:0.1.0
  • docker.io/tracesdotcom/traces-sbx-kit:latest

Agent-readable reference repo for building and publishing Docker Sandboxes kits. The included kits/traces directory is a prototype mixin kit that adds Traces sharing support to existing Docker Sandbox agents.

Docker Sandboxes kits are experimental. Re-check the Docker docs before making breaking changes: https://docs.docker.com/ai/sandboxes/customize/kits/

What this repo contains

kits/
└── traces/
    └── spec.yaml   # Docker Sandboxes mixin kit for Traces

Quick start for the Traces kit

Prerequisites:

brew install docker/tap/sbx
sbx daemon start --detach
sbx login

Configure a host-side Traces API key. The real key stays on the host; the sandbox only sees Docker's proxy-managed sentinel value.

echo "$TRACES_API_KEY" | sbx secret set -g traces

Create a sandbox with the kit:

sbx run claude --kit docker.io/tracesdotcom/traces-sbx-kit:0.1.0 .

# Or from this repo checkout:
sbx run claude --kit ./kits/traces .

For a running sandbox while iterating on the kit:

sbx kit add <sandbox-name> ./kits/traces

Inside the sandbox, share the current session:

traces share --cwd "$PWD" --agent auto --json

Agents should parse the JSON and return data.sharedUrl to the user.

What the Traces mixin does

• Installs the Traces CLI release binary into /usr/local/bin.
• Runs traces setup skills --global for Traces-supported agents.
• Allows Traces domains plus GitHub release download domains in the sandbox network policy.
• Declares a custom traces credential service and maps it to the outbound Authorization header for actions.traces.com and api.traces.com.
• Sets TRACES_API_KEY=proxy-managed inside the VM; Docker's host-side proxy replaces the outbound auth header with the real host-side secret.
• Disables CLI auto-update and Sentry by default to keep behavior deterministic and avoid extra network policy entries.

Agent instructions: creating a Docker Sandbox mixin kit

When an agent is asked to create or update one of these kits, follow this checklist.

1. Choose mixin unless you are defining a whole agent

Use a mixin kit for add-ons: CLIs, team config, credentials, network access, skills, helper scripts, linters, etc.

Use an agent kit only when defining the complete agent runtime: image, entrypoint, persistence, and launch command.

For Traces, use kind: mixin because Traces extends existing agents.

2. Use the standard kit layout

my-kit/
├── spec.yaml       # required
└── files/          # optional static files
    ├── home/       # copied to /home/agent/
    └── workspace/  # copied to the primary workspace

Required top-level fields:

schemaVersion: "1"
kind: mixin
name: lowercase-hyphen-name
displayName: Human Name
description: Short description

3. Keep install commands non-interactive and idempotent

Install commands run once during sandbox creation. Startup commands run every start. Use initFiles for files that need runtime substitution such as ${WORKDIR}.

commands:
  install:
    - description: Install a tool
      user: "0"
      command: "apt-get update && apt-get install -y jq"
  startup:
    - description: Start a background daemon
      user: "1000"
      background: true
      command: ["sh", "-c", "my-daemon &"]
  initFiles:
    - path: /home/agent/.my-tool/config.json
      content: '{"workspace":"${WORKDIR}"}'
      onlyIfMissing: true

Use UID 0 for root installs and UID 1000 for the agent user.

4. Never put secrets directly in environment.variables

Use Docker Sandboxes credential proxy wiring instead:

network:
  allowedDomains:
    - api.example.com
  serviceDomains:
    api.example.com: my-service
  serviceAuth:
    my-service:
      headerName: Authorization
      valueFormat: "Bearer %s"

credentials:
  sources:
    my-service:
      env:
        - MY_SERVICE_API_KEY

environment:
  proxyManaged:
    - MY_SERVICE_API_KEY

The sandbox sees MY_SERVICE_API_KEY=proxy-managed. Requests to api.example.com get the real host-side secret injected by Docker's proxy.

Host setup:

echo "$MY_SERVICE_API_KEY" | sbx secret set -g my-service

5. Be explicit about network access

Every domain needed by install commands and runtime commands must be in network.allowedDomains. For authenticated domains, also add serviceDomains and serviceAuth.

Keep rules narrow. Prefer exact hosts over broad wildcards.

6. Add memory only when useful to the agent

Top-level memory: | is appended to the agent's memory file when the base agent kit defines agent.aiFilename. Keep it short and action-oriented.

7. Validate locally

sbx kit validate ./kits/traces
sbx kit inspect ./kits/traces

Package for sharing:

sbx kit pack ./kits/traces -o dist/traces-kit.zip

Distribution: Git vs Docker Hub vs other registries

Kits can be loaded from:

• a local directory or ZIP
• a Git URL
• an OCI registry reference

Recommended model:

1. GitHub repo = source of truth. Keep spec.yaml, docs, examples, and review history here.
2. OCI artifact = release channel. Publish immutable versioned tags after validation.
3. Docker Hub if private distribution matters. Docker's docs currently say private kits are supported only on Docker Hub. Other registries are pulled anonymously, so private GHCR/ECR/etc. kits may fail.

For public kits, Git URLs or GHCR are fine. Docker Hub still makes sense if you want the most Docker-native install path and private-kit compatibility later. Use the full docker.io prefix for Docker Hub references.

Example publish flow:

sbx kit validate ./kits/traces
sbx kit push ./kits/traces docker.io/tracesdotcom/traces-sbx-kit:0.1.0
sbx kit push ./kits/traces docker.io/tracesdotcom/traces-sbx-kit:latest

Example use from Docker Hub:

sbx run claude --kit docker.io/tracesdotcom/traces-sbx-kit:0.1.0 .

Avoid mutable-only distribution. If you publish latest, also publish a versioned tag like 0.1.0.

Current caveats

• Docker Sandboxes kits are experimental.
• The Traces kit only works for agents with existing Traces adapters.
• Exact current-session detection depends on each agent runtime. Some agents may fall back to the newest trace for the current working directory.
• Docker Agent, Kiro, and Shell would need new Traces adapters or another capture mechanism.
• Kits cannot be removed from a running sandbox; recreate the sandbox for a clean test.