# alineo docs

> Sandboxes as objects. Spawn live containers, run code, checkpoint state — from TypeScript.

alineo is an AI agent platform built on sandboxed execution: live sandbox containers
as first-class objects (spawn, exec, checkpoint, resume) with a durable audit ledger,
a lazy workflow builder, and an agent SDK on top.

How to use this file:

- Each entry links to the page's Markdown (.md) form — fetch that for clean parsing.
- When citing or linking a page, use its canonical URL without the .md suffix
  (e.g. https://docs.alineo.tech/docs/core/getting-started).
- The entire documentation as one file: https://docs.alineo.tech/llms-full.txt

## Core SDK

- Getting Started
  - [Getting Started](https://docs.alineo.tech/llms.mdx/core/getting-started.md): Go from zero to a running workflow in a few minutes.
  - [What is the sandbox client?](https://docs.alineo.tech/llms.mdx/core/getting-started/what-is-alineo.md): @alineo-labs/sandbox gives you live sandbox containers as first-class objects — spawn, exec, checkpoint, resume.
  - [Installation](https://docs.alineo.tech/llms.mdx/core/getting-started/installation.md): Install @alineo-labs/sandbox and a storage adapter, then wire up the client.
  - [Quick start](https://docs.alineo.tech/llms.mdx/core/getting-started/quickstart.md): Run your first sandbox command in under five minutes.
  - [How it works](https://docs.alineo.tech/llms.mdx/core/getting-started/how-it-works.md): SandboxHandle as a first-class object, ExecHandle, the durable ledger, and the @alineo-labs/workflow lazy layer.
- Concepts
  - [Concepts](https://docs.alineo.tech/llms.mdx/core/concepts.md): The core ideas behind the sandbox client — what things are and how they relate.
  - [Workflows](https://docs.alineo.tech/llms.mdx/core/concepts/workflows.md): The two usage modes — direct sandbox API and the @alineo-labs/workflow lazy builder.
  - [Sandboxes](https://docs.alineo.tech/llms.mdx/core/concepts/sandboxes.md): Isolated Docker containers managed by OpenSandbox — how they're created, configured, and closed.
  - [Environments](https://docs.alineo.tech/llms.mdx/core/concepts/environments.md): Define a named setup recipe once, snapshot it, and spawn cheap isolated sandboxes from it on demand.
  - [Steps](https://docs.alineo.tech/llms.mdx/core/concepts/steps.md): What you can do with a SandboxHandle — exec, execCode, file operations, checkpoint, and control flow.
  - [Refs & state](https://docs.alineo.tech/llms.mdx/core/concepts/refs-and-state.md): Capture exec output and thread values between steps using ExecResult and the workflow builder's vars.
  - [Event stream](https://docs.alineo.tech/llms.mdx/core/concepts/event-stream.md): How ExecHandle streams stdout from the sandbox in real time — pipe, async generator, and await.
  - [Storage adapters](https://docs.alineo.tech/llms.mdx/core/concepts/storage-adapters.md): How the IStorageAdapter interface persists every exec event for durability and replay.
  - [Network policy](https://docs.alineo.tech/llms.mdx/core/concepts/network-policy.md): Control which hosts a sandbox may reach — set an allow/deny policy at creation, or change it at runtime with sb.egress.*.
  - [Credentials](https://docs.alineo.tech/llms.mdx/core/concepts/credentials.md): Register credentials that get injected into outbound requests without the sandbox process ever holding them.
- Building Workflows
  - [Building Workflows](https://docs.alineo.tech/llms.mdx/core/building.md): Practical guides for each step type and capability in the builder API.
  - [exec & execCode](https://docs.alineo.tech/llms.mdx/core/building/exec.md): Run shell commands with exec() and interpreted code with execCode().
  - [File operations](https://docs.alineo.tech/llms.mdx/core/building/file-ops.md): Write, read, move, delete, search, list, patch, and transfer files inside the sandbox container.
  - [Control flow](https://docs.alineo.tech/llms.mdx/core/building/control-flow.md): retry, when, forEach, parallel, and sequence — composable workflow primitives from @alineo-labs/workflow.
  - [Snapshots & replay](https://docs.alineo.tech/llms.mdx/core/building/snapshots.md): Checkpoint the container filesystem with checkpoint() and restore from it with client.resume().
- Patterns
  - [Patterns](https://docs.alineo.tech/llms.mdx/core/patterns.md): Cross-cutting concerns — how to handle failure, time, and observability.
  - [Timeouts & cancellation](https://docs.alineo.tech/llms.mdx/core/patterns/timeouts-and-cancellation.md): Sandbox lifetime limits, bash-level command timeouts, and cleanup with try/finally.
  - [Error handling](https://docs.alineo.tech/llms.mdx/core/patterns/error-handling.md): Strict vs non-strict exec, CommandError, SandboxError, and ExecConnectionError.
  - [Run management](https://docs.alineo.tech/llms.mdx/core/patterns/run-management.md): List, inspect, resume, and delete past sandbox sessions from the ledger.
  - [Named checkpoints](https://docs.alineo.tech/llms.mdx/core/patterns/named-checkpoints.md): Tag checkpoints with human-readable names, list them, and resume from any specific point.
  - [Forking sandboxes](https://docs.alineo.tech/llms.mdx/core/patterns/fork.md): Create independent sandbox copies from a live checkpoint with sb.fork().
  - [Observability](https://docs.alineo.tech/llms.mdx/core/patterns/observability.md): SandboxHooks lifecycle callbacks and OpenTelemetry tracing with @alineo-labs/otel.
  - [Flue integration](https://docs.alineo.tech/llms.mdx/core/patterns/flue.md): Use a @alineo-labs/sandbox SandboxHandle as a Flue session environment with @alineo-labs/flue.
- Storage Adapters
  - [Storage Adapters](https://docs.alineo.tech/llms.mdx/core/adapters.md): Choose where @alineo-labs/sandbox persists your run ledger.
  - [SQLite adapter](https://docs.alineo.tech/llms.mdx/core/adapters/sqlite.md): Zero-config storage with WAL mode. The right default for local dev and single-process deploys.
  - [Postgres adapter](https://docs.alineo.tech/llms.mdx/core/adapters/postgres.md): Shared ledger for production multi-process deployments.
  - [Custom adapter](https://docs.alineo.tech/llms.mdx/core/adapters/custom.md): Implement IStorageAdapter to use any storage backend with @alineo-labs/sandbox.
- API Reference
  - [API Reference](https://docs.alineo.tech/llms.mdx/core/api-reference.md): Complete reference for every public symbol exported from @alineo-labs/sandbox.
  - [Sandbox](https://docs.alineo.tech/llms.mdx/core/api-reference/alineo-client.md): The main client — sandbox(), resume(), restoreSnapshot(), connect(), and sandboxes management.
  - [ExecHandle](https://docs.alineo.tech/llms.mdx/core/api-reference/workflow-run.md): The object returned by sb.exec() and sb.execCode() — PromiseLike<ExecResult> with pipe(), stdout(), and result().
  - [Errors](https://docs.alineo.tech/llms.mdx/core/api-reference/errors.md): CommandError, SandboxError, ExecConnectionError, WorkflowError, and SandboxClientError — the full alineo error hierarchy.
- [AI Resources](https://docs.alineo.tech/llms.mdx/core/ai-resources.md): Use the alineo docs with LLMs and coding agents — llms.txt, per-page Markdown, and agent skills.

## Workflow Builder

- Getting Started
  - [Getting Started](https://docs.alineo.tech/llms.mdx/workflow/getting-started.md): What the Workflow Builder is, and how to run your first workflow.
  - [What is the Workflow Builder?](https://docs.alineo.tech/llms.mdx/workflow/getting-started/what-is-workflow.md): @alineo-labs/workflow adds a lazy declarative layer over the Core SDK — one await at the end, lifecycle managed automatically.
  - [Quickstart](https://docs.alineo.tech/llms.mdx/workflow/getting-started/quickstart.md): Run your first workflow — install, configure, and run a multi-step pipeline in one await.
- Building
  - [Building](https://docs.alineo.tech/llms.mdx/workflow/building.md): SandboxBuilder operations, control flow, parallel/sequence patterns, and capturing values.
  - [SandboxBuilder](https://docs.alineo.tech/llms.mdx/workflow/building/sandbox-builder.md): The object passed to every workflow callback — queues operations synchronously, flushes them when the workflow is awaited.
  - [Control Flow](https://docs.alineo.tech/llms.mdx/workflow/building/control-flow.md): retry, when, and forEach — conditional branching and iteration inside a SandboxBuilder.
  - [Parallel & Sequence](https://docs.alineo.tech/llms.mdx/workflow/building/parallel-sequence.md): Run the same workflow across multiple containers simultaneously, or chain sandboxes where each step sees the previous result.
  - [Capturing Values](https://docs.alineo.tech/llms.mdx/workflow/building/capturing-values.md): Use readFile(path, as) to pull file contents out of the sandbox and into WorkflowResult.vars.
- API Reference
  - [API Reference](https://docs.alineo.tech/llms.mdx/workflow/api-reference.md): Complete reference for the @alineo-labs/workflow lazy orchestration layer.
  - [Builder API](https://docs.alineo.tech/llms.mdx/workflow/api-reference/builder.md): workflow(), WorkflowBuilder, and SandboxBuilder — the @alineo-labs/workflow lazy orchestration layer.

## Alineo SDK

- [Alineo SDK](https://docs.alineo.tech/llms.mdx/agent.md): Run AI coding agents (Pi) in isolated sandbox containers with a simple TypeScript API.
- Getting Started
  - [Getting Started](https://docs.alineo.tech/llms.mdx/agent/getting-started.md): Load an agent spec, send a prompt, and understand snapshotting, workspace setup, and streaming.
  - [Quick start](https://docs.alineo.tech/llms.mdx/agent/getting-started/quickstart.md): Load an agent spec, send a prompt, and stream the response in minutes.
  - [Snapshotting](https://docs.alineo.tech/llms.mdx/agent/getting-started/snapshotting.md): How Alineo.load() caches the Pi install so subsequent loads take seconds instead of minutes.
  - [Workspace setup](https://docs.alineo.tech/llms.mdx/agent/getting-started/workspace-setup.md): Declarative bash steps that run after Pi install and are baked into the snapshot.
  - [Streaming & tool events](https://docs.alineo.tech/llms.mdx/agent/getting-started/streaming.md): Observe Pi's text output and tool calls in real time using AgentStream and AgentEvent.
  - [Reliability & error recovery](https://docs.alineo.tech/llms.mdx/agent/getting-started/reliability.md): Handle transient API errors with auto-retry, observe retry events, and abort mid-flight bash commands.
  - [Session inspection & control](https://docs.alineo.tech/llms.mdx/agent/getting-started/session-inspection.md): Inspect token usage, retrieve session history, list available commands, and control how Pi processes queued messages.
  - [Permission gate (human-in-the-loop)](https://docs.alineo.tech/llms.mdx/agent/getting-started/permissions.md): Pause an agent's tool calls for human approval — a mode shorthand or a full per-tool policy, plus a gate that holds outbound network egress until someone approves.
- API Reference
  - [API Reference](https://docs.alineo.tech/llms.mdx/agent/api-reference.md): Complete reference for the Alineo SDK.
  - [Alineo](https://docs.alineo.tech/llms.mdx/agent/api-reference/agent.md): Complete reference for the Alineo class, AgentSpec, AgentStream, and all Pi RPC commands.

## alineo CLI

- Getting Started
  - [What is alineo?](https://docs.alineo.tech/llms.mdx/alineo/getting-started.md): alineo starts a local OpenSandbox server, manages alineo spec files, and drives agent sessions directly from the command line — spawn, prompt, fork, and orchestrate without writing TypeScript.
  - [Quickstart](https://docs.alineo.tech/llms.mdx/alineo/getting-started/quickstart.md): Start a local OpenSandbox server and fetch your first agent spec in under five minutes.
- Commands
  - [Commands](https://docs.alineo.tech/llms.mdx/alineo/commands.md): All alineo commands and their options.
  - [alineo init](https://docs.alineo.tech/llms.mdx/alineo/commands/init.md): Start a local OpenSandbox server in Docker and configure the current project.
  - [alineo add](https://docs.alineo.tech/llms.mdx/alineo/commands/add.md): Fetch an agent spec from a URL or local file and save it to your project's agents directory.
  - [alineo list](https://docs.alineo.tech/llms.mdx/alineo/commands/list.md): List the agent specs saved in the current project's agents directory.
  - [alineo remove](https://docs.alineo.tech/llms.mdx/alineo/commands/remove.md): Delete a saved agent spec file from the current project.
  - [alineo spawn](https://docs.alineo.tech/llms.mdx/alineo/commands/spawn.md): Start a brand-new, independent agent sandbox from a spec's own snapshot.
  - [alineo prompt](https://docs.alineo.tech/llms.mdx/alineo/commands/prompt.md): Send one prompt to a running agent sandbox and print the reply.
  - [alineo fork](https://docs.alineo.tech/llms.mdx/alineo/commands/fork.md): Fork a running session's own live sandbox into a brand-new independent child agent.
  - [alineo agents](https://docs.alineo.tech/llms.mdx/alineo/commands/agents.md): List running agent sessions, cross-checked against the live OpenSandbox control plane.
  - [alineo kill](https://docs.alineo.tech/llms.mdx/alineo/commands/kill.md): Stop a sandbox by ID.
  - [alineo logs](https://docs.alineo.tech/llms.mdx/alineo/commands/logs.md): Print ledger events for a session.
- Registry
  - [Registry](https://docs.alineo.tech/llms.mdx/alineo/registry.md): Publish an AgentSpec JSON file so others can fetch it with a single command.
  - [AgentSpec schema](https://docs.alineo.tech/llms.mdx/alineo/registry/schema.md): Complete field reference for the AgentSpec JSON fetched by alineo add and run by alineo's Alineo.load().
- [Running an agent spec](https://docs.alineo.tech/llms.mdx/alineo/using-sandboxes.md): Load an agent spec saved by alineo add with Alineo.load() — alineo add itself never creates a sandbox.

## Examples

- [Hello World](https://docs.alineo.tech/llms.mdx/examples/hello-world.md): Spin up an Ubuntu sandbox, run a command, and stream the output.
- [Code Interpreter](https://docs.alineo.tech/llms.mdx/examples/exec-code.md): Run code through the sandbox's built-in interpreter — stateless and stateful modes.
- [File Operations](https://docs.alineo.tech/llms.mdx/examples/file-ops.md): The full sandbox file operations API — read, write, move, search, and transfer.
- [Reading Files](https://docs.alineo.tech/llms.mdx/examples/read-file.md): Read a file written inside the sandbox back to the host process.
- [Capturing Output](https://docs.alineo.tech/llms.mdx/examples/capture.md): Capture exec stdout and use it as input for subsequent steps.
- [Running Bash Scripts](https://docs.alineo.tech/llms.mdx/examples/run-bash-script.md): Run a multi-line bash script inside an isolated sandbox and stream its output.
- [Interactive Exec](https://docs.alineo.tech/llms.mdx/examples/interactive-exec.md): A live, bidirectional PTY session that can be checkpointed and resumed mid-session.
- [Exposing Ports](https://docs.alineo.tech/llms.mdx/examples/ports.md): Start an HTTP server inside a sandbox and reach it from the host via sb.proxy().
- [Control Flow](https://docs.alineo.tech/llms.mdx/examples/control-flow.md): retry, when, and forEach — alineo's built-in workflow control-flow primitives.
- [Cancellation & Cleanup](https://docs.alineo.tech/llms.mdx/examples/cancellation.md): Resource cleanup and error handling when commands fail or time out.
- [Error Handling](https://docs.alineo.tech/llms.mdx/examples/error-handling.md): Strict vs. non-strict exec, and the CommandError/SandboxError/ExecConnectionError types.
- [Reusable Environments](https://docs.alineo.tech/llms.mdx/examples/environments.md): Build a sandbox image once, then restore from snapshot on every run.
- [Checkpoint & Resume](https://docs.alineo.tech/llms.mdx/examples/snapshot-replay.md): Capture a snapshot after install, then resume from it to skip setup on the next run.
- [Forking Sandboxes](https://docs.alineo.tech/llms.mdx/examples/sandbox-fork.md): Install dependencies once, then fork into independent sandboxes that run in parallel.

## Cookbooks

- [Untrusted Code Execution](https://docs.alineo.tech/llms.mdx/cookbooks/untrusted-code-execution.md): Safely run LLM-generated or user-submitted code — per-snippet isolation, resource caps, and timeouts.
- [CI Test Runner](https://docs.alineo.tech/llms.mdx/cookbooks/ci-test-runner.md): Run a repo's test suite in a disposable sandbox and turn the output into a structured pass/fail report.
- [Parallel Test Shards](https://docs.alineo.tech/llms.mdx/cookbooks/parallel-test-shards.md): Install dependencies once, then fork into parallel sandboxes to shard work across them.
- [Resumable ETL Pipeline](https://docs.alineo.tech/llms.mdx/cookbooks/resumable-etl-pipeline.md): A multi-stage pipeline that checkpoints after every stage and resumes without redoing completed work.
- [AI Agent Bugfix](https://docs.alineo.tech/llms.mdx/cookbooks/ai-agent-bugfix.md): An agent that debugs and fixes a failing test on its own, then gets independently verified.
- [Persistent Agent Memory](https://docs.alineo.tech/llms.mdx/cookbooks/persistent-agent-memory.md): An agent that remembers things about a customer across separate sandbox sessions, via @alineo-labs/memory.
- [Credential-Scoped Agent](https://docs.alineo.tech/llms.mdx/cookbooks/credential-scoped-agent.md): An agent that calls an authenticated API with a token it can never read — injected at the egress layer.