Declarative YAML Specs

Instead of writing Rust code, you can define agents and pipelines as YAML files and run them directly with the CLI.

1. Agent spec

A single agent spec declares the sandbox, LLM provider, prompt, and skills:

api_version: v1
kind: agent
name: hn_researcher

sandbox:
  mode: auto
  memory_mb: 1024
  vcpus: 1
  network: true

llm:
  provider: claude

agent:
  prompt: >
    Analyze current HackerNews top stories and produce
    a tactical briefing for AI engineering teams.
  skills:
    - "file:examples/hackernews/skills/hackernews-api.md"
  timeout_secs: 600

2. Pipeline spec

A pipeline spec chains multiple boxes with explicit stage ordering:

api_version: v1
kind: pipeline
name: quick-pipeline

sandbox:
  mode: auto
  memory_mb: 512
  network: true

pipeline:
  boxes:
    - name: analyst
      prompt: Extract key facts from the input.
      skills: ["agent:claude-code"]
      timeout_secs: 300

    - name: writer
      prompt: Turn facts into a concise executive summary.
      skills: ["agent:claude-code"]
      timeout_secs: 300

  stages:
    - type: box
      name: analyst
    - type: box
      name: writer

3. Running with the CLI

Use void-box run to execute any spec file:

4. Environment overrides

Override the LLM provider at runtime without changing the spec:

Environment variables take precedence over spec-level llm.provider settings.

5. Next

Learn how to compose pipelines in Rust, or set up local LLMs with Ollama.