Orchestration

Every gibil workflow, from a one-line gibil run to a fleet of agents building features in parallel, is built from two roles. Once you see the split, every recipe reads the same way.

• The orchestrator decides what work happens and in what order. It holds your credentials, drives the loop, and owns the box's lifecycle: it forges the box and burns it when the work is done.
• The box is where the work actually runs. A real Linux server with your code, your tools, and root. It runs commands, holds the worktree, and self-destructs at its TTL.

The orchestrator lives outside the box and talks to it over a channel: MCP tools, or plain SSH.

┌──────────────────┐   MCP tools / SSH   ┌──────────────────┐
│   ORCHESTRATOR   │ ──────────────────▶ │       BOX        │
│                  │                     │                  │
│ drives the loop  │                     │ runs the work    │
│ holds the keys   │ ◀────────────────── │ holds the code   │
│ forge + burn     │      results        │ root, disposable │
└──────────────────┘                     └──────────────────┘

Why the roles are separate

The orchestrator forges the box and burns it at the end, on success and on failure. That ownership is the reason the two roles can never be the same machine: a process can't reliably forge and burn the box it's running on. If the orchestrator lived inside the box, it would be deleting the machine it's executing on, so it could not run cleanup, report a result, or react when the agent inside breaks something.

So the orchestrator has to outlive the box and sit outside its blast radius. The box can be wiped, rm -rf'd, or wedged, and the orchestrator survives to forge another. This is the same relationship a CI runner has with the container it builds: the runner creates and destroys the container, it never runs inside it.

The orchestrator is a role, not a place

"Orchestrator" does not mean "your laptop." It means whatever is driving the loop, and that can run in several places:

• Your laptop, as an AI agent you're talking to.
• A CI runner executing a script.
• A long-lived server.
• Even another gibil box.

Wherever it runs, the relationship to the box is identical. What changes between the shapes below is where the orchestrator sits and how it triggers work.

Four shapes

1. Interactive agent over MCP

Your AI agent (Claude Code, Cursor, or any MCP client) is the orchestrator. It calls gibil's MCP tools to forge a box, run commands, read results, and burn it, all from your editor. You talk to the agent; the agent drives the box.

   YOUR LAPTOP
 ┌─────────────────────┐
 │  AI agent (MCP)     │  ← orchestrator
 │  create_server      │
 │  vm_bash / vm_read  │
 └──────────┬──────────┘
            │ MCP tools
            ▼
     ┌──────────────┐
     │   gibil box  │  ← runs tests, edits, builds
     └──────────────┘

Best for hands-on work where you're in the loop. See Agent Code-Test Loop and AI Agent via MCP.

2. Agent on the box (untethered)

You launch once, then step away. The orchestrator forges a box with a coding agent installed (gibil branch --agent), hands it a task, and the agent runs inside the box on its own. Your laptop is just the launcher: once the agent is working, you can close the lid.

  YOUR LAPTOP                          gibil box
 ┌──────────────┐   launch + task    ┌────────────────────┐
 │ gibil branch │ ─────────────────▶ │  agent runs HERE   │  ← orchestrator
 │  --agent     │                    │  + the work runs   │     and worker,
 │ (then leave) │                    │  here too          │     same box
 └──────────────┘                    └────────────────────┘

Here the orchestrating and the work collapse onto the box itself, which is the one case where they share a machine, because the box is now driving its own loop. The box still burns at its TTL with no one watching. Best for long autonomous tasks. See Run Agents in Parallel.

3. Framework orchestrator (Sandcastle)

A code-defined loop drives the box. Sandcastle, one of the frameworks gibil ships an integration for, runs an agent against your repo until a pass condition is met, then opens a PR. Sandcastle is the orchestrator; gibil is the box underneath. The loop's brain runs wherever you start Sandcastle, and it drives the box over SSH.

Run it on your laptop and the loop stops if the laptop sleeps. Run it somewhere persistent and it keeps going. The three-tier version makes it fully untethered:

 ① LAUNCHER (laptop)        ② ORCHESTRATOR (gibil box)      ③ BOX (gibil box)
 ┌──────────────┐  ssh +   ┌──────────────────────────┐   ┌──────────────────┐
 │ start the    │ ───────▶ │ Sandcastle loop          │   │ worktree         │
 │ run, then    │  kickoff │ holds ANTHROPIC_API_KEY  │   │ runs tests/build │
 │ disconnect   │          │ forges + burns box ③ ────┼──▶│ no keys here     │
 └──────────────┘          └──────────────────────────┘   └──────────────────┘

The launcher can disconnect; the orchestrator box keeps the loop alive and burns the work box when done.

4. Fan-out: one orchestrator, many boxes

One orchestrator drives several boxes at once, each on its own branch or task. They are isolated: separate kernels, separate IPs, no shared state. The orchestrator dispatches work to each, collects results as they land, and burns each box when its branch is done.

                ┌──────────────┐  ← orchestrator
                │ create x3    │     (your agent, or a script)
                └──┬────┬────┬─┘
          ┌────────┘    │    └────────┐
          ▼             ▼             ▼
    ┌──────────┐  ┌──────────┐  ┌──────────┐
    │  box A   │  │  box B   │  │  box C   │
    │ feat/x   │  │ feat/y   │  │ feat/z   │
    └──────────┘  └──────────┘  └──────────┘

Best when the bottleneck is "one task at a time." See Run Agents in Parallel and Parallel Test Sharding.

How the orchestrator triggers work

Three channels, same two roles:

What survives if the orchestrator stops

Whatever drives the loop has to stay powered. If it stops (laptop sleeps, CI job ends, the orchestrator box's TTL fires), the loop stops with it. The box, though, is never orphaned: its TTL burns it regardless.

Picking a shape

All four are the same skeleton: an orchestrator outside the box, driving work over a channel, owning the box's life. Pick where the orchestrator sits based on how long the work runs and whether you need to be there for it.

Next steps

• Run Agents in Parallel: fan-out in practice
• AI Agent via MCP: the MCP channel and its tools
• Build a Feature with Sandcastle: a framework orchestrator on gibil boxes
• How It Works: the forge, use, burn lifecycle of a single box