pi-cloud-agent

Background agents, without the backend.

Every agentic product (code review, issue triage, research bots) rebuilds the same 80%: a durable queue, an isolated machine, credentials that survive sitting next to untrusted code, a log someone can replay. This is that 80%, in under 8,000 lines, MIT, on your own server.

You write the other 20%.

Principles

• Small enough to read. Under 8,000 lines of TypeScript. You can audit every line that touches your credentials in an evening, which is the only honest reason to trust it with one.
• Composable, not configurable. Three contracts: a vertical, a compute backend, a forge. Plugins are installable skill/MCP bundles beside those contracts — not a second controller.
• Boring on purpose. Postgres and one reconciliation loop. No workflow engine, no message broker, no cache.
• Deleting is design work. Every feature is a liability. The default answer to "should we add this?" is "not yet, and probably not here."

Complexity belongs compressed inside the abstraction, not spread across the surface.

How a run works

1. Something triggers it: the dashboard or an API call.
2. The operator connects a GitHub or Azure DevOps identity in Settings; the controller resolves the repository and boots a sandbox with the run credential.
3. Inside, an agent clones the repo, does the work, and posts its own result with ordinary tools like git and gh.
4. Every step lands in an append-only log you can stream live or replay later.
5. A standalone run's machine is reclaimed. A chat session's filesystem is parked for the next turn, then expires automatically.

Runs are fully headless. The dashboard can also continue a deliberate multi-turn session without pretending each follow-up is a new conversation.

What it is not

A remote dev environment. There is nothing to attach to; the controller cannot even dial into a sandbox, by design. A parked session preserves agent history and a filesystem, not a machine you can SSH into.

The execution unit is a run: an event starts it, it ends, and its log is immutable. A session is the durable parent for ordered chat turns, the Pi checkpoint, and an optional parked workspace. See docs/sessions.md.

Development

Copy .env.example to .env, add the GitHub App settings, run make setup, then make dev. Sign in and add a model connection from Settings. DEVELOPMENT.md has the short quick start and optional provider setup.

Why it is this small

The interesting decisions are subtractions:

• No workflow engine. Run state lives in Postgres and one reconciliation loop repairs it, so a restart is indistinguishable from a slow tick. No Temporal, no trigger.dev, no run lifecycle held in memory to lose. → docs/resumability.md
• No event bus, no Redis. Postgres already stores every event; LISTEN/NOTIFY is a wake-up hint and polling is the correctness baseline.
• No publishing step. The agent posts its own review. No output parser, no findings table, and therefore no way for the controller to disagree with what the agent actually did.
• A lifecycle-shaped sandbox contract. create, resume, suspend, deleteWorkspace, and stop. The sandbox remains outbound-only; persistence is a provider concern, not an agent server. → docs/adding-a-sandbox-provider.md
• User-owned model connections. The controller resolves the selected connection for each run, while the sandbox receives only the model configuration and credential needed for that run. → docs/model-connections.md

Layout

apps/
  controller/     trusted service: HTTP, reconciler, credentials, database
  web/            operator dashboard
packages/
  protocol/       the contracts: types, schemas, provider interfaces
  sandbox/        SandboxProvider implementations
  vcs/            GitHub and Azure DevOps provider implementations
  runtime/        runs inside the sandbox (untrusted)

The split is by substitutability and trust, not by feature. packages/runtime executes untrusted repository code and may depend only on packages/protocol; pnpm boundaries enforces that in CI.

Documentation

• DeepWiki: a deep dive into the project's architecture and design
• VISION.md: what this is for, and what it will refuse to become
• ARCHITECTURE.md: the two trust zones and the run lifecycle
• DEVELOPMENT.md: complete local setup, microSandbox image, optional E2B template, and first run
• AGENTS.md: index for coding agents, plus the enforced rules
• docs/: durable sessions, resumability, secrets, testing, operations, extension guides

Contributing

Skills/plugins, sandbox backends, and forges are the surfaces this project wants to grow, and none of them require touching the controller. Bug fixes, corrected docs, and deletions are equally welcome.

DEVELOPMENT.md covers environment setup and validation. CONTRIBUTING.md covers the rules CI enforces and the short list of changes worth discussing before you write code. By participating you agree to the Code of Conduct.

Credits

We are proud to build on the open-source community. We'd like to highlight a few that do particularly heavy lifting:

• Pi coding agent - the agent harness inside the sandbox (@earendil-works/pi-coding-agent).
• microSandbox - the default local microVM sandbox backend.
• Pierre Diffs - the diff renderer (@pierre/diffs).

License

MIT © zen8labs