alineo spawn

bunx alineo-cli spawn <parent> <child-spec> [--prompt <msg>] [--depth <n>] [--max <n>] [--json]

Arguments

Argument	Description
`parent`	The caller's own running session — used only to resolve its sandbox ID, not the child's name. Required.
`child-spec`	Path to the child's agent spec JSON file. Required.

Flags

Flag	Description
`--prompt <msg>`	Send one prompt to the child immediately after it's ready, and print the reply before exiting.
`--depth <n>`	Override the caller's own `spawnDepth` budget instead of reading `ALINEO_SPAWN_DEPTH` from the environment.
`--max <n>`	Override the caller's own `maxAgents` budget instead of reading `ALINEO_MAX_AGENTS` from the environment.
`--json`	Print `{ name, sandboxId, reply }` as JSON instead of the default text output.

What it does

alineo spawn is meant to be run by a session's own Pi bash tool, not from a fresh host shell — parent labels the caller's own running session, resolved to a sandbox ID two ways:

If ALINEO_SANDBOX_ID is set in this process's own environment (true when running as a descendant of a Pi bridge process inside a alineo-managed sandbox — which is exactly the case when a Pi session's bash tool runs alineo spawn), that's used directly.
Otherwise, parent is looked up against the ledger's running sessions.

The caller's sandbox is then resolved via Alineo.attach() — not Alineo.resume(), which would kill the very bridge process making this call — and agent.spawn(childSpec, { spawnDepth, maxAgents }) forks its live sandbox into the child.

Unlike alineo start (always starts from a spec's own snapshot), the child sees exactly what the calling sandbox sees right now — filesystem, installed packages, uncommitted work — with no install/setup steps.

Example

# Run from inside a Pi session's own bash tool, with ALINEO_SANDBOX_ID already set:
bunx alineo-cli spawn my-session ./agents/worker.json --prompt "Handle the auth module"

[alineo] spawned: fork-my-session-a1b2c3  sandbox: 6a69afcb-7a00-437a-9819-e032022cc736

Recursive spawning budgets

A spec's spawnDepth is a nesting-depth budget, force-decremented (current - 1) into the child's env on every spawn. 0 means no budget left — alineo spawn refuses immediately with an error. undefined means spawning was never enabled for that spec at all.

maxAgents is a separate, optional ceiling on total descendants for one lineage, independent of nesting depth. Unset means uncapped. It is not coordinated across sibling branches spawned in parallel — it's a per-lineage counter, checked and decremented independently down each branch, not a global budget shared across an entire tree.

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

Notes

The child's environment is resolved fresh from its own spec — nothing is inherited from the caller except the force-computed spawn-depth counter. Every env var the caller's own spec declares is explicitly unset in the shell command that starts the child's bridge, since the child container's OS-level env otherwise still carries whatever was baked in at snapshot time.
No install or setup steps run for the child — it inherits whatever is already installed on the caller's sandbox. If the child needs packages the caller doesn't have, add them to a setup step on the spec the caller was loaded from, not the child's.
See the Pi extension section on the commands index for how a Pi session gets alineo spawn syntax injected into its own guidance automatically.