castellan run
Scheduler-led goal loop with a plugin verifier. Writes episode JSON to .castellan/episodes/<goal-id>.json.
Usage
castellan run --goal <GOAL> [--plugin gridworld] [--resume [<GOAL_ID>]]
[--rlm] [--max-steps 8]
[--audit <PATH>] [--json] [--mcp] [--model <URL_OR_NAME>]
[--genome <ID>] [--seed-archive] [--archive .castellan/topology_archive.json]
[--write-back] [--no-write-back] [--mux] [--no-mux]
When resuming, --goal is optional (defaults to checkpoint description). Plugin comes from the checkpoint.
Key flags
| Flag | Default | Notes |
|---|---|---|
--goal | required unless --resume | Natural-language goal text |
--plugin | gridworld | Verifier plugin (castellan plugin list) |
--resume | off | Continue from .castellan/checkpoints/ (optional goal UUID; default latest) |
--rlm | off | In-tree RLM verify/act loop |
--max-steps | 8 | Max RLM steps when --rlm |
--json | off | NDJSON castellan-events on stdout |
--mcp | off | Process mcp_tools from observation payload |
--mux | off (explicit) | Force scheduler-led run via in-process multiplexer panes |
--no-mux | off | Rollback for mux-by-default; also CASTELLAN_MUX_AUTO=0 or CASTELLAN_MUX_DISABLE=1 |
--seed-archive | off | Seed topology from evolve archive before run |
--write-back | auto with --seed-archive | Merge fitness into archive after success |
--mux runs via MuxHarnessHost; episode JSON includes pane_tree. BL-020 (MOAT Phase 3): mux is the default when the multiplexer socket is healthy — no CASTELLAN_MUX_AUTO=1 required. Rollback with --no-mux, CASTELLAN_MUX_AUTO=0, or CASTELLAN_MUX_DISABLE=1.
--json events
| Event | Summary |
|---|---|
episode_start | goal_id, plugin, goal |
scheduler_tick | tick, pending |
task_dispatched | tick, task_id, zone |
verify_result | tick, zone, goal_met |
cost_rollup | per-tick usd, tokens, session total_usd, total_tokens |
deposit | zone signal deposit |
archive_write_back | optional genome merge |
episode_end | goal_id, status, fitness, episode_path |
See statusline for dashboard consumption.
Recipes
Gridworld smoke (verify.sh default):
castellan run --goal "reach target" --plugin gridworld
RLM verify/act:
castellan run --goal "reach target" --plugin gridworld --rlm --max-steps 4
Resume mid-goal:
castellan run --goal "reach target" --plugin gridworld
castellan run --resume
Mux topology in episode:
castellan run --goal "reach target" --plugin gridworld --mux
Evolve round-trip:
castellan evolve --episodes 5 --workspace .castellan/episodes
castellan run --goal "reach target" --plugin gridworld --seed-archive --write-back