> ## 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 run

> Run and test your agent locally without Docker

## Command

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

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

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

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

```bash theme={null}
sb0 run --prompt "test" --extras '{"debug": true, "custom_field": "value"}'
```

## How It Works

`sb0 run` executes your agent handler directly using:

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

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

```bash theme={null}
export ANTHROPIC_API_KEY="sk-ant-..."
```

### Not in Agent Directory

```
Error: agent.config.yaml not found
```

**Solution:**

```bash theme={null}
cd agent  # Navigate to agent directory
sb0 run --prompt "test"
```

## Debug Mode

Enable debug logs to see internal operations:

```bash theme={null}
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](/v0-docs/cli/build)
* [Deploy to platform](/v0-docs/cli/push)
* [Learn about the handler](/v0-docs/agents/handler)

## Related

* [Testing locally](/v0-docs/quickstart/testing-locally)
* [Agent handler](/v0-docs/agents/handler)