> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sb0.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# sb0 build

> Build your agent into a Docker image

## Command

```bash theme={null}
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:

```bash theme={null}
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`:

```yaml theme={null}
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

<Note>
  The `.sb0/Dockerfile.agent` is automatically generated. Don't edit it manually—your changes will be overwritten on the next build.
</Note>

## Next Steps

After building:

1. **Test the image locally** (optional):
   ```bash theme={null}
   docker run -it --rm \
     -e ANTHROPIC_API_KEY \
     my-agent:latest
   ```

2. **Deploy to platform**:
   ```bash theme={null}
   sb0 push
   ```

## Related

* [Publishing your agent](/v0-docs/quickstart/publishing)
* [Deploy to platform](/v0-docs/cli/push)
* [Agent configuration](/v0-docs/agents/configuration)