Skip to main content

​
Command

sb0 build

​
Description

Builds your agent into a production-ready Docker image. This packages your agent code, dependencies, and runtime into a container for deployment.

​
Usage

Build from your agent/ directory: 
sb0 build

​
Expected Output

Building Docker image my-agent:latest...
[+] Building 45.2s (12/12) FINISHED
 => [internal] load build definition from Dockerfile.agent
 => [internal] load metadata for docker.io/library/python:3.12-slim
 => [stage-0 1/6] FROM docker.io/library/python:3.12-slim
 => [stage-0 2/6] RUN apt-get update && apt-get install -y ...
 => [stage-0 3/6] COPY pyproject.toml uv.lock ./
 => [stage-0 4/6] RUN uv sync --frozen
 => [stage-0 5/6] COPY . .
 => [stage-0 6/6] RUN uv pip install sb0-runner sb0-protocol
 => exporting to image

✔ Image built: my-agent:latest

​
What Gets Built

The build process:
  1. Generates Dockerfile - Creates .sb0/Dockerfile.agent based on your config
  2. Installs system packages - From agent.config.yaml
  3. Installs Python dependencies - From pyproject.toml and uv.lock
  4. Copies agent code - Your handle_query.py and other files
  5. Packages sb0 runtime - Includes sb0-runner and sb0-protocol
  6. Creates Docker image - Tagged according to agent.config.yaml

​
Image Name

The image name is defined in your agent.config.yaml: 
version: "0.1"
image: "my-agent:latest"  # <-- This is the image name

​
.dockerignore Warning

If .dockerignore is missing, you’ll see a warning: 
Warning: .dockerignore not found. The .venv directory may be copied into the Docker image.
         This can cause issues. Consider creating a .dockerignore file that includes '.venv/'.
Solution: Create a .dockerignore file: 
.venv/
__pycache__/
*.pyc
.git/
.DS_Store

​
When to Build

You need to build when:
  • Deploying to production - Before running sb0 push
  • Configuration changes - After modifying agent.config.yaml
  • System package changes - After adding to system_packages
  • Final testing - To verify Docker image works correctly
You do NOT need to build for:
  • Local testing - Use sb0 run --prompt instead
  • Python code changes - Test with sb0 run without rebuilding
  • Adding Python dependencies - Test locally first, build when ready to deploy

​
Build Platforms

Builds for your native platform by default:
  • Apple Silicon (M1/M2/M3) - linux/arm64
  • Intel/AMD - linux/amd64

​
Requirements

  • Docker must be running - Start Docker Desktop or Docker daemon
  • Must run from agent directory - The directory containing agent.config.yaml
  • Valid configuration - agent.config.yaml must be properly formatted

​
Common Issues

​
Docker Not Running

Error: Cannot connect to the Docker daemon
Solution: Start Docker Desktop or the Docker daemon.

​
Invalid Configuration

Agent validation failed:
 - handler must specify module:ClassName format
Solution: Fix errors in agent.config.yaml and try again.

​
Generated Files

Building creates:
  • .sb0/Dockerfile.agent - Generated Dockerfile (don’t edit manually)
  • Docker image - Tagged according to your config
The .sb0/Dockerfile.agent is automatically generated. Don’t edit it manually—your changes will be overwritten on the next build.

​
Next Steps

After building:
  1. Test the image locally (optional): 
    docker run -it --rm \
  -e ANTHROPIC_API_KEY \
  my-agent:latest
  2. Deploy to platform: 
    sb0 push