Commands

SDK — OpenSandbox config and the local spec cache

Alineo — session lifecycle

These wrap alineo's Alineo.start()/Alineo.resume()/Alineo.attach()/Alineo.reattach()/Alineo.spawn() directly. Sessions are usually addressed by sandbox ID — prompt, steer, and stop require it (see alineo prompt for why). spawn and logs are addressed by session name instead — see their own pages for why. start begins a fresh session and takes a spec path, not an identifier.

Recursive spawning (alineo spawn)

A spec's spawnDepth is a nesting-depth budget — required for alineo spawn to be allowed from inside a session at all. Each spawn force-decrements it (current - 1) into the child's env; 0 means no budget left, undefined means spawning was never enabled for that spec.

maxAgents is a separate, optional ceiling on total descendants for one lineage, independent of nesting depth. Unset means uncapped. Not coordinated across sibling branches spawned in parallel — it's a per-lineage counter, not a global one.

{
  "name": "orchestrator",
  "harness": "pi",
  "spawnDepth": 2,
  "maxAgents": 10
}

See alineo spawn for the full mechanics.

Pi extension

pi install npm:alineo-cli installs the alineo extension into Pi at user scope. Once installed, any Pi session:

• Bootstraps alineo automatically on first use (installs it, runs alineo init) — no manual setup.
• Gets alineo start/alineo spawn/alineo steer CLI syntax injected into its own guidance, dynamically chosen based on whether the current session is itself running inside a alineo-managed sandbox.

The extension source lives at pi-extension/alineo.ts in the alineo npm package.