Orchestrator Quickstart (Beta)

This guide walks through a minimal Orchestrator (Beta) setup: register an agent, create a workflow, and complete tasks.

Prerequisites

Hoard installed and configured
A running server: hoard serve
HOARD_SERVER_SECRET set so the server can start

For local testing you can also set HOARD_TOKEN to the same value as HOARD_SERVER_SECRET to get full access from the CLI.

Quickstart Steps

Initialize Orchestrator settings
Terminal window
```
hoard orchestrate init
```
This creates a registration token in your config and prompts for artifact storage settings.

Export required environment variables

export HOARD_SERVER_SECRET=your_server_secret
export HOARD_TOKEN=$HOARD_SERVER_SECRET
export HOARD_REGISTRATION_TOKEN=your_registration_token

Use the token printed by hoard orchestrate init for HOARD_REGISTRATION_TOKEN.

Start the server
Terminal window
```
hoard serve
```
Register an agent
Terminal window
```
hoard agent register demo-agent --type worker --capabilities summarize
```
The response includes a unique agent token. Use it when acting as that agent.

Create a workflow definition

cat > workflow.json <<'JSON'
{
  "steps": [
    {
      "step_key": "draft",
      "name": "Draft outline",
      "description": "Create a short outline"
    },
    {
      "step_key": "review",
      "name": "Review outline",
      "description": "Review and improve the outline",
      "depends_on_steps": ["draft"]
    }
  ]
}
JSON

Create and start the workflow
Terminal window
```
hoard workflow create "Outline workflow" --definition workflow.json
hoard workflow start wf-1234
```
Replace wf-1234 with the workflow id returned by the create command.

Act as the agent and complete tasks

export HOARD_TOKEN=hoard_agt_sk_...
hoard task poll
hoard task claim tsk-1234
hoard task complete tsk-1234 --summary "Drafted outline"

Repeat for the next task until the workflow completes.

Attach artifacts (optional)

hoard artifact put tsk-1234 outline.md --type text --content "# Outline\n- Item 1"

Check workflow status and events

hoard workflow status wf-1234
hoard event poll

Review cost summary (optional)

hoard cost summary --period today
hoard cost budget --period today

Notes

cost.report is called by agents via MCP when they complete work.
task.start, task.fail, task.cancel, and workflow pause/resume/cancel are available via MCP even if not exposed in the CLI.
Use MCP Tools for full schemas and scope requirements.