Claude's Corner: Terminal Use — Vercel for Background AI Agents

---
description: Build Terminal Use — filesystem-first AI agent hosting infrastructure with forking, streaming, and persistent state. Deploy coding agents the same way you deploy web apps.
---

# Build Terminal Use Clone: Agent Hosting Infrastructure with Filesystem Forking

## What You're Building

A production-capable platform for hosting filesystem-based AI coding agents. Users push an agent definition, the platform runs it in an isolated sandbox, persists the filesystem state, and lets them fork that state for parallel agent runs. Includes real-time message streaming back to a dashboard UI.

**Core primitives:**
- Agent sandbox (Firecracker microVM via Fly.io Machines)
- Filesystem snapshots and fork operations
- Real-time message streaming (Redis pub/sub + SSE)
- Run management API and CLI
- Observability dashboard (Next.js)

## Tech Stack

- **Sandbox runtime**: Fly.io Machines (Firecracker microVMs)
- **Agent SDK**: `@anthropic-ai/claude-agent-sdk` or custom
- **API server**: Node.js + Express or Fastify
- **Database**: PostgreSQL (Supabase) for run metadata
- **Streaming**: Redis pub/sub + Server-Sent Events
- **Dashboard**: Next.js + shadcn/ui
- **CLI**: Node.js + commander
- **Auth**: API keys (simple) or Supabase Auth

## Steps

### Step 1: Project Setup and Fly.io Configuration

```bash
npm init -y
npm install @anthropic-ai/claude-agent-sdk express ioredis pg uuid commander dotenv
npm install -D typescript @types/node tsx

# Install Fly CLI
curl -L https://fly.io/install.sh | sh
fly auth login
fly apps create your-agent-platform
```

Create `fly.toml` for your control plane API:
```toml
app = "your-agent-platform"
primary_region = "ord"

[build]
  dockerfile = "Dockerfile"

[http_service]
  internal_port = 3000
  force_https = true

[env]
  NODE_ENV = "production"
```

### Step 2: Database Schema

```sql
-- Agent definitions
CREATE TABLE agents (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name TEXT NOT NULL,
  owner_id UUID NOT NULL,
  manifest JSONB NOT NULL, -- entry point, env vars, dependencies
  docker_image TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Individual runs
CREATE TABLE agent_runs (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  agent_id UUID REFERENCES agents(id),
  parent_run_id UUID REFERENCES agent_runs(id), -- for forks
  status TEXT DEFAULT 'queued', -- queued, running, completed, failed
  fly_machine_id TEXT,
  snapshot_id TEXT, -- Fly volume snapshot ID after run
  forked_from_snapshot TEXT, -- snapshot this run started from
  input_payload JSONB,
  started_at TIMESTAMPTZ,
  completed_at TIMESTAMPTZ,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Message log per run
CREATE TABLE run_messages (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  run_id UUID REFERENCES agent_runs(id),
  role TEXT NOT NULL, -- 'agent', 'tool', 'system'
  content TEXT NOT NULL,
  metadata JSONB,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE INDEX idx_run_messages_run_id ON run_messages(run_id);
CREATE INDEX idx_agent_runs_agent_id ON agent_runs(agent_id);
```

### Step 3: Fly Machines Integration — The Core Engine

This is the hardest part. Fly.io Machines API lets you programmatically create, start, snapshot, and destroy microVMs.

```typescript
// src/fly/machines.ts
import { randomUUID } from 'crypto';

const FLY_API_TOKEN = process.env.FLY_API_TOKEN!;
const FLY_APP_NAME = process.env.FLY_APP_NAME!;
const BASE = `https://api.machines.dev/v1/apps/${FLY_APP_NAME}`;

const headers = {
  'Authorization': `Bearer ${FLY_API_TOKEN}`,
  'Content-Type': 'application/json'
};

export async function createMachine(opts: {
  image: string;
  env: Record<string, string>;
  volumeSnapshotId?: string;
}) {
  const body: Record<string, unknown> = {
    config: {
      image: opts.image,
      env: opts.env,
      guest: { cpu_kind: 'shared', cpus: 2, memory_mb: 2048 },
      auto_destroy: true, // clean up after agent finishes
    }
  };

  // If forking from a snapshot, mount a volume cloned from that snapshot
  if (opts.volumeSnapshotId) {
    const vol = await createVolumeFromSnapshot(opts.volumeSnapshotId);
    body.config = {
      ...body.config as object,
      mounts: [{ volume: vol.id, path: '/agent-workspace' }]
    };
  }

  const res = await fetch(`${BASE}/machines`, {
    method: 'POST', headers, body: JSON.stringify(body)
  });
  return res.json() as Promise<{ id: string; state: string }>;
}

export async function snapshotMachineVolume(machineId: string, volumeId: string) {
  const res = await fetch(`${BASE}/volumes/${volumeId}/snapshots`, {
    method: 'POST', headers
  });
  return res.json() as Promise<{ id: string }>;
}

export async function createVolumeFromSnapshot(snapshotId: string) {
  const res = await fetch(`${BASE}/volumes`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
      name: `fork-${randomUUID().slice(0, 8)}`,
      size_gb: 10,
      snapshot_id: snapshotId,
      region: 'ord'
    })
  });
  return res.json() as Promise<{ id: string }>;
}

export async function waitForMachine(machineId: string, targetState = 'stopped') {
  for (let i = 0; i < 120; i++) {
    const res = await fetch(`${BASE}/machines/${machineId}`, { headers });
    const machine = await res.json() as { state: string };
    if (machine.state === targetState) return machine;
    await new Promise(r => setTimeout(r, 5000));
  }
  throw new Error(`Machine ${machineId} did not reach ${targetState}`);
}
```

### Step 4: Message Streaming with Redis Pub/Sub

```typescript
// src/streaming/publisher.ts
import Redis from 'ioredis';

const redis = new Redis(process.env.REDIS_URL!);

export async function publishMessage(runId: string, message: {
  role: string;
  content: string;
  metadata?: Record<string, unknown>;
}) {
  const payload = JSON.stringify({ ...message, timestamp: Date.now() });
  await redis.publish(`run:${runId}`, payload);
  // Also persist to DB asynchronously
  await redis.lpush(`run:${runId}:history`, payload);
}
```

```typescript
// src/api/routes/stream.ts — SSE endpoint
import { Router } from 'express';
import Redis from 'ioredis';

const router = Router();

router.get('/:runId/stream', async (req, res) => {
  const { runId } = req.params;
  
  res.setHeader('Content-Type', 'text/event-stream');
  res.setHeader('Cache-Control', 'no-cache');
  res.setHeader('Connection', 'keep-alive');
  res.flushHeaders();

  // First, replay history
  const sub = new Redis(process.env.REDIS_URL!);
  const history = await sub.lrange(`run:${runId}:history`, 0, -1);
  history.reverse().forEach(msg => {
    res.write(`data: ${msg}\n\n`);
  });

  // Then subscribe to live events
  sub.subscribe(`run:${runId}`);
  sub.on('message', (_, message) => {
    res.write(`data: ${message}\n\n`);
  });

  req.on('close', () => sub.disconnect());
});

export default router;
```

### Step 5: Agent Runner — Orchestrating a Run

```typescript
// src/runner/run.ts
import { createMachine, waitForMachine, snapshotMachineVolume } from '../fly/machines';
import { publishMessage } from '../streaming/publisher';
import { db } from '../db';

export async function executeRun(runId: string) {
  const run = await db.agentRuns.findById(runId);
  const agent = await db.agents.findById(run.agentId);

  await db.agentRuns.update(runId, { status: 'running', startedAt: new Date() });
  await publishMessage(runId, { role: 'system', content: 'Agent starting...' });

  const machine = await createMachine({
    image: agent.manifest.dockerImage,
    env: {
      ...agent.manifest.env,
      RUN_ID: runId,
      PLATFORM_API_URL: process.env.PLATFORM_API_URL!,
      INPUT_PAYLOAD: JSON.stringify(run.inputPayload),
    },
    volumeSnapshotId: run.forkedFromSnapshot ?? undefined
  });

  await db.agentRuns.update(runId, { flyMachineId: machine.id });

  // Wait for agent to complete
  await waitForMachine(machine.id, 'stopped');

  // Snapshot the filesystem after completion
  const volumeId = await getVolumeForMachine(machine.id);
  if (volumeId) {
    const snapshot = await snapshotMachineVolume(machine.id, volumeId);
    await db.agentRuns.update(runId, { snapshotId: snapshot.id });
  }

  await db.agentRuns.update(runId, { status: 'completed', completedAt: new Date() });
  await publishMessage(runId, { role: 'system', content: 'Agent completed.' });
}

async function getVolumeForMachine(machineId: string): Promise<string | null> {
  // Fetch machine details and extract volume ID from mounts
  const res = await fetch(`https://api.machines.dev/v1/apps/${process.env.FLY_APP_NAME}/machines/${machineId}`, {
    headers: { Authorization: `Bearer ${process.env.FLY_API_TOKEN}` }
  });
  const machine = await res.json() as { config?: { mounts?: Array<{ volume: string }> } };
  return machine.config?.mounts?.[0]?.volume ?? null;
}
```

### Step 6: Fork API

```typescript
// POST /runs/:runId/fork
router.post('/:runId/fork', async (req, res) => {
  const parentRun = await db.agentRuns.findById(req.params.runId);
  
  if (!parentRun.snapshotId) {
    return res.status(400).json({ error: 'Parent run has no snapshot. Run must be completed to fork.' });
  }

  const newRun = await db.agentRuns.create({
    agentId: parentRun.agentId,
    parentRunId: parentRun.id,
    forkedFromSnapshot: parentRun.snapshotId,
    inputPayload: req.body.inputPayload ?? parentRun.inputPayload,
    status: 'queued'
  });

  // Kick off async execution
  executeRun(newRun.id).catch(console.error);

  res.json({ runId: newRun.id, message: 'Fork created and queued' });
});
```

### Step 7: Agent Dockerfile Pattern

Agents need to be packaged in a standard way. Here is the pattern Terminal Use likely uses:

```dockerfile
# Template agent Dockerfile
FROM node:22-slim

# Install Claude Agent SDK
RUN npm install -g @anthropic-ai/claude-agent-sdk

# Agent workspace is the persistent volume
WORKDIR /agent-workspace

# Copy agent source
COPY agent/ ./
RUN npm install

# Platform SDK for publishing messages back
COPY platform-sdk/ /platform-sdk/
RUN cd /platform-sdk && npm install && npm run build

# Entry point — agent calls platform SDK to stream messages
ENTRYPOINT ["node", "index.js"]
```

Your agent's `index.js` should import your platform's messaging SDK and call `publishMessage(process.env.RUN_ID, {...})` as it works.

## Key Insights

1. **Fly.io is the right substrate.** It exposes Firecracker microVMs through a clean REST API with volume snapshot support. You get production-grade isolation without managing your own hypervisor.

2. **Copy-on-write is how forking is cheap.** Fly volume snapshots are COW — creating a volume from a snapshot is nearly instant and only copies divergent blocks. A fork costs almost nothing until the forked agent starts writing.

3. **Persistent volumes are not free.** Price this carefully. A volume sitting idle costs money. Build a cleanup policy that deletes volumes for runs older than N days unless the customer explicitly retains them.

4. **The streaming layer is what users see most.** Even if your sandbox infra is excellent, if streaming is flaky or laggy, the product feels broken. Get Redis pub/sub right before you optimise anything else.

5. **Build the CLI first, then the dashboard.** Terminal Use's CLI-first philosophy is right. Power users want to deploy from the terminal. The dashboard is for monitoring, not the happy path.

## Gotchas

- **Machine cold start latency:** Fly Machines take 1-5 seconds to boot. For interactive agent use cases this is fine; for sub-second needs you need pre-warmed pools.
- **Volume costs accumulate fast:** Every run that snapshots a filesystem costs money even when idle. Implement TTL-based cleanup from day one.
- **Streaming backpressure:** If your agent emits thousands of messages, naive SSE will overwhelm the client. Implement rate limiting and message batching in the publisher.
- **Docker image size matters:** Large agent images slow down every cold start. Keep your base image under 500MB and cache dependencies aggressively.
- **Redis memory for run history:** `LPUSH` based history will grow unbounded. Set a max length (`LTRIM`) or move to Postgres-backed history after initial MVP.