Commands
alineo start
Start a brand-new, independent agent sandbox from a spec's own snapshot.
bunx alineo-cli start <spec> [--prompt <msg>] [--rebuild] [--depth <n>] [--max <n>] [--json]Arguments
| Argument | Description |
|---|---|
spec | Path to an agent spec JSON file. Required. |
Flags
| Flag | Description |
|---|---|
--prompt <msg> | Send one prompt immediately after the sandbox is ready, and print the reply before exiting. |
--rebuild | Force a full reinstall instead of restoring from the cached snapshot. See Snapshotting. |
--depth <n> | Override the spec's own spawnDepth field. |
--max <n> | Override the spec's own maxAgents field. |
--json | Print { name, sandboxId, reply } as JSON instead of the default text output. |
What it does
- Reads
alineo.config.jsonand callsAlineo.start(spec, { adapter, rebuild, spawnDepth, maxAgents })— see that page for the full snapshot/install behavior. This always starts from the spec's own snapshot (or builds one on first use); it never inspects the calling process's own sandbox state. - If
--promptis given, sends that message and waits for the full reply before printing anything and exiting. - Without
--prompt, prints the sandbox name and ID and exits immediately — the sandbox keeps running.
Example
bunx alineo-cli start ./agents/my-agent.json[alineo] session: my-agent sandbox: 4af65c3b-24a2-4fd1-999d-918faa9b97fdbunx alineo-cli start ./agents/my-agent.json --prompt "Explain this repo" --json{ "name": "my-agent", "sandboxId": "4af65c3b-...", "reply": "..." }start vs. spawn
alineo start is the entry point for a fresh session — e.g. a host-level Pi session starting the master of a recursive-agent run. alineo spawn instead branches an already-running session's own live sandbox state into a child. Use start when nothing exists yet; use spawn when you're running inside a session and want to delegate part of the current work to a child.
Notes
- The sandbox ID printed here is what
alineo prompt,alineo stop, andalineo logsneed — it is not saved anywhere else automatically. --depth/--maxonly matter if the spec itself (viaagent.spawn()) or a lateralineo spawncall from inside that sandbox will go on to create children.