# alineo spawn
URL: /docs/cli/commands/spawn

Spawn a child agent from a running session's own live sandbox.



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

## Arguments [#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 [#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 [#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:

1. 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.
2. Otherwise, `parent` is looked up against the ledger's running sessions.

The caller's sandbox is then resolved via [`Alineo.attach()`](/docs/agent/api-reference/alineo#alineoattach) — **not** `Alineo.resume()`, which would kill the very bridge process making this call — and [`agent.spawn(childSpec, { spawnDepth, maxAgents })`](/docs/agent/api-reference/alineo#agentspawn) 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 [#example]

```bash
# 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 [#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.

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

## Notes [#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](/docs/cli/commands#pi-extension) section on the commands index for how a Pi session gets `alineo spawn` syntax injected into its own guidance automatically.