Box0 (b0) Multi-Agent Platform

Run AI agents in parallel. Create agents with roles, trigger them on demand or on a schedule, and collect results.

Setup

Step 1: Check if Box0 is installed

b0 --version

If this succeeds, skip to Step 3.

Step 2: Install

npm install -g @box0/cli@latest

If npm is not available, build from source:

git clone https://github.com/risingwavelabs/box0.git
cd box0 && cargo build --release
export PATH="$PWD/target/release:$PATH"

Step 3: Check if server is running

b0 server status

If this shows "Server is running", skip to Step 5.

Step 4: Start the server

b0 server

On first start, Box0 creates an admin account and auto-configures ~/.b0/config.toml.

Step 5: Install the skill

npx skills add risingwavelabs/skills --skill b0

Step 6: Verify

b0 ls

This should run without errors. Setup is complete.

Tell the user: "Box0 is installed and ready. You can now delegate tasks to agents."

---

When to use

When the user's request could benefit from specialized agents or parallel execution, delegate.

Choosing an agent

Always use b0 run with an existing agent or create one with b0 add. Use b0 ls to see what is available.

Use b0 add when:

• No existing agent matches the task
• The user wants a named agent for future reuse

Use b0 run <name> when:

• b0 ls shows an existing agent that matches the task
• The user mentions an agent by name ("ask the reviewer")

Commands

b0 ls                                                  # list available agents
b0 add <name> --instructions "..."                     # create a named agent
b0 add <name> --instructions "..." --every 1h --task "..." # create scheduled agent
b0 add <name> --instructions "..." --webhook           # create agent with trigger URL
b0 add <name> --instructions "..." --webhook-secret s  # create agent with HMAC secret
b0 rm <name>                                           # delete an agent
b0 run <agent> "<detailed task prompt>"                # trigger agent and wait for result
b0 run <agent> "<task>" --timeout 600                  # trigger with custom timeout
b0 info <name>                                         # show agent info including trigger URL
b0 logs <name>                                         # show recent agent logs
b0 update <name> --instructions "..."                  # update agent instructions

How to write task prompts

This is critical. Do NOT forward the user's words. Compose a complete, actionable prompt.

Bad:

b0 run reviewer "review this PR"

Good:

b0 run reviewer "Review the changes on branch feature-timeout in this repo.
The PR adds timeout handling to src/handler.rs.
Focus on correctness, edge cases, and error handling.
Cite line numbers for any issues found."

Steps:

1. Gather context first - read relevant files, run git diff, check the branch
2. Include specifics - file paths, line numbers, branch names, what changed and why
3. State the deliverable - what the agent should produce (a list of issues, a summary, a fix)

For large content (diffs, file contents), pipe via stdin:

git diff main..HEAD | b0 run reviewer "Review the following diff. Focus on correctness."

Concurrent tasks

Run multiple agents in parallel:

b0 run reviewer "Review the changes on branch feature-timeout..." &
b0 run security "Check src/handler.rs for OWASP top 10 vulnerabilities..." &
b0 run doc-writer "Update README to reflect the new timeout config option..." &
wait

Each b0 run call blocks until its agent completes. Run them in the background with & to parallelize.

Scheduled agents

Create an agent that runs automatically on a schedule:

b0 add monitor --instructions "Check logs for errors." --every 1h --task "scan logs"

Intervals: 30s, 5m, 1h, 6h, 1d.

Webhook triggers

Every agent with --webhook has a trigger URL. Any HTTP POST to that URL runs the agent.

b0 add notifier --instructions "Process incoming alerts." --webhook

This prints the trigger URL: <server>/trigger/<workspace>/<agent-name>.

To see the trigger URL for an existing agent:

b0 info notifier

To add HMAC signature verification:

b0 add notifier --instructions "Process alerts." --webhook --webhook-secret mysecret

Then sign requests with X-Hub-Signature-256: sha256=<hmac-sha256-of-body>.

Error handling

If an agent fails, b0 run reports the error. Decide whether to:

• Retry with a clearer prompt
• Try a different agent
• Handle the task yourself
• Report the failure to the user

Troubleshooting

| Symptom | Fix | |---------|-----| | b0: command not found | Run npm install -g @box0/cli@latest | | b0 server status shows not running | Run b0 server | | b0 run times out | Increase timeout with --timeout 600 | | Agent returns empty result | Check agent instructions with b0 info <name> |