sb0 run

Run and test your agent locally without Docker

Command

sb0 run --prompt "your prompt here"

Description

Runs your agent handler locally for quick testing. Executes directly in your Python environment without Docker, enabling fast iteration during development.

Usage

Test with a single prompt (from agent/ directory):

sb0 run --prompt "Say hello"

Expected Output

Streaming agent response...

Hello! How can I assist you today?

Options

--prompt <text>

The prompt to send to your agent.

sb0 run --prompt "What is 2+2?"

--session-id <id>

Session identifier for conversation continuity. Use the same session ID to maintain context across multiple queries.

sb0 run --prompt "What is 2+2?" --session-id "abc123"
sb0 run --prompt "What was my previous question?" --session-id "abc123"

--extras <json>

Additional parameters passed to your handler as kwargs. Must be valid JSON.

sb0 run --prompt "test" --extras '{"debug": true, "custom_field": "value"}'

How It Works

sb0 run executes your agent handler directly using:

uv run --no-project --python .venv/bin/python sb0-runner

This means:

• No Docker required - Runs in your local Python environment
• Fast iteration - No build step needed
• Instant feedback - See changes immediately after editing code

Development Workflow

Rapid iteration cycle:

# 1. Edit your handler
nano handle_query.py

# 2. Test immediately
sb0 run --prompt "test input"

# 3. Make more changes
nano handle_query.py

# 4. Test again
sb0 run --prompt "another test"

No rebuild needed between edits!

Requirements

• Agent must be initialized - Run sb0 init first
• ANTHROPIC_API_KEY must be set - Export in your environment
• Must run from agent directory - The directory containing agent.config.yaml

Common Issues

API Key Not Set

Error: ANTHROPIC_API_KEY not found

Solution:

export ANTHROPIC_API_KEY="sk-ant-..."

Not in Agent Directory

Error: agent.config.yaml not found

Solution:

cd agent  # Navigate to agent directory
sb0 run --prompt "test"

Debug Mode

Enable debug logs to see internal operations:

sb0 run --prompt "test" --extras '{"debug": true}'

This shows:

• Logger output from your handler
• Internal sb0-runner messages
• Print statements (captured as DEBUG logs)

Next Steps

• Build for production
• Deploy to platform
• Learn about the handler

Related

• Testing locally
• Agent handler