Arbor

# Arbor

**Branch-native coding workspace infrastructure for autonomous AI agents.**

Arbor provides microVM-isolated workspaces that coding agents can run real builds in, checkpoint at any moment, fork into parallel branches, and restore safely — all within your own VPC. Think of it as the infrastructure layer that makes multi-agent experimentation safe and reproducible.

Built in Rust on top of [Firecracker](https://github.com/firecracker-microvm/firecracker).

---

## The problem Arbor solves

When you run a coding agent on a real repository, three things keep going wrong:

**1. Agents can't safely experiment in parallel.**
If you want to try three different approaches to fixing a bug, you need three isolated environments. Spinning up three fresh VMs from scratch wastes minutes and gigabytes. Existing snapshot tools let you restore a checkpoint — but they don't handle what happens when you restore the *same* snapshot three times. All three copies share the same SSH keys, session tokens, PRNG seeds, and Docker layer cache state. They'll silently collide.

**2. Secrets end up inside the VM.**
The standard pattern — inject an `OPENAI_API_KEY` environment variable into the sandbox — means the agent can read, log, and exfiltrate credentials. An agent executing arbitrary code in a compromised dependency has full access to every secret in its environment.

**3. You can't run this on your own infrastructure.**
Every existing coding sandbox is SaaS-only. If your codebase is proprietary, your compliance team won't let agent traffic touch a third-party cloud. There is no self-hosted option that gives you microVM isolation, checkpoint/restore, and proper secret handling in one coherent system.

Arbor is the answer to all three.

More details are introduced in [INTRO.md](INTRO.md) and summarized in the differentiators and comparison sections below.

---

## Core differentiators

### 1. Branch-safe restore (unique)

Firecracker's official documentation [explicitly warns](https://github.com/firecracker-microvm/firecracker/blob/main/docs/snapshotting/snapshot-support.md):

> *Resuming a microVM from a snapshot that has been previously used is possible, but the content of the Guest's memory will have the same entropy as the original snapshot.*

Restoring the same checkpoint twice means both VMs start with identical PRNG seeds, identical in-memory token caches, identical SSH agent state. For single-agent use this is an acceptable limitation. For multi-agent branching experiments, it is a correctness bug.

Arbor solves this with a **quarantine + reseal** protocol. Every fork goes through:

```
fork(checkpoint_id)
 └─ new VM boots in QUARANTINED state
     ├─ all egress blocked (no network out)
     ├─ all attach tokens invalidated
     └─ reseal hook chain runs:
         1. bump identity_epoch  →  new VM identity
         2. rotate session tokens
         3. re-sign preview URLs
         4. revoke + re-issue secret grants
         5. re-seed guest entropy via vsock
         ─────────────────────────────────
         only then: state → READY
```

This is enforced at the infrastructure level. No application-level coordination required.

### 2. VPC-first secret brokering

Arbor's egress proxy sits on the host, outside the VM. When an agent calls `api.openai.com`:

```
agent process
  → VM network stack (blocked by default)
  → host netns + TAP device
  → arbor-egress-proxy
      ├─ allowlist check (is this host permitted?)
      ├─ credential injection (Authorization: Bearer <real-key>)
      └─ upstream request to api.openai.com
```

The VM never receives the credential value. The agent sees a placeholder like `OPENAI_API_KEY=arbor-brokered` in its environment. The real key is injected by the host-side proxy. If the agent logs its environment, leaks it to a supply-chain compromise, or exfiltrates it via a prompt injection — the real key is never exposed.

### 3. Checkpoint DAG

Every checkpoint records its parent, forming a directed acyclic graph:

```
ws-main ──ckpt-A "before-migration"
              ├── ws-attempt-1  (fork: postgres migration path)
              ├── ws-attempt-2  (fork: redis approach)
              └── ws-attempt-3  (fork: skip migration entirely)
```

Each forked workspace has its own isolated identity, its own Docker daemon, its own egress policy, and its own secret grants. The parent workspace keeps running. None of the three attempts can observe or interfere with each other.

### 4. Self-host / VPC-first

Arbor is designed from day one to run inside your own infrastructure. The entire control plane, runner pool, and egress proxy run in your VPC. Code, secrets, and agent activity never leave your network. This is the deployment model, not an enterprise add-on.

---

## How it compares

| | Arbor | E2B | Docker Sandboxes | Modal | Daytona |
|---|---|---|---|---|---|
| Isolation | Firecracker microVM | Firecracker microVM | Firecracker microVM | Container | Container/VM |
| Private Docker daemon | Yes | Yes | Yes | No | No |
| VM checkpoint | Full VM | Basic resume | No | Container-level | No |
| Fork from checkpoint | First-class API | No | No | No | No |
| Branch-safe restore | **Yes (unique)** | No | No | No | No |
| Credential brokering | Host-side proxy | No | Yes | No | No |
| Default-deny egress | Yes | Partial | Yes | No | No |
| Self-host / VPC | **First-class** | SaaS only | SaaS only | SaaS only | Yes |
| Open source | Yes (MIT, Rust) | SDK only | No | No | Yes |

**E2B** is the closest technical peer — also Firecracker-based, also targets AI agents — but has no fork API, no branch-safe semantics, and is SaaS-only. Great for single-agent sandboxing; not built for multi-agent branching.

**Docker Sandboxes** introduced the brokered-credentials pattern that Arbor builds on, but has no snapshot capability at all, no self-host option, and is SaaS-only.

**Modal** has excellent container checkpointing and scale-to-zero, but is function-oriented rather than workspace-oriented. You can't `git clone` a repo and run a multi-hour agent session in a persistent environment.

**Daytona** is self-hostable and git-native, but designed for human developers. No snapshot, no credential brokering, no egress policy, no agent-oriented API.

---

## Architecture

```
                   ┌──────────────────────────────┐
                   │        CLI / SDK / UI        │
                   └──────────────┬───────────────┘
                                  │ REST + WebSocket
              ┌───────────────────▼──────────────────┐
              │           arbor-api  (axum)           │
              │  AuthN · quotas · attach tokens       │
              └──────┬────────────────────┬───────────┘
                     │                    │
          ┌──────────▼──────┐   ┌─────────▼──────────┐
          │ arbor-controller│   │ arbor-secret-broker │
          │ workspace FSM   │   │ grant TTL · rotation│
          └──────┬──────────┘   └─────────┬───────────┘
                 │ schedule               │ push grants
          ┌──────▼──────────────────────────────────────┐
          │           arbor-snapshot-service             │
          │     manifest · S3 upload · digest · GC       │
          └──────────────────┬──────────────────────────┘
                             │
          ┌──────────────────▼──────────────────────────┐
          │              Runner Node Pool                │
          │  ┌────────────────────────────────────────┐ │
          │  │        arbor-runner-agent              │ │
          │  │  Firecracker + Jailer + cgroups v2     │ │
          │  │  netns · TAP · vsock mux · snapshots   │ │
          │  └──────────────────┬─────────────────────┘ │
          │                     │ vsock                  │
          │  ┌──────────────────▼─────────────────────┐ │
          │  │         Workspace microVM              │ │
          │  │  dockerd · git · arbor-guest-agent     │ │
          │  │  language runtimes · agent process     │ │
    

[truncated…]