Describe what you want built. SAM provisions a cloud workspace, runs an AI coding agent, and streams the results back to you.

Self-Hosting Guide • Architecture • Documentation

---

What You Get

Project chat that executes code. Link a GitHub repo, describe a task in natural language, and SAM handles the rest — provisioning a VM, cloning your repo into a devcontainer, starting Claude Code, and streaming output back to the chat.

Chat history that outlives workspaces. Conversations persist at the project level. Stop a workspace, spin up a new one weeks later, and your full history is still there.

Your infrastructure, your costs. Self-hosted on Cloudflare ($5/mo Workers Paid plan) + Hetzner Cloud VMs. A workspace costs ~$0.007–0.03/hr compared to $0.18–0.36/hr on GitHub Codespaces.

How It Works

You: "Add rate limiting to the /api/upload endpoint"
         |
    Project Chat (app.{domain})
         |
    Cloudflare Worker API
         |
    TaskRunner -- alarm-driven orchestrator that:
      1. Claims a warm node or provisions a new Hetzner VM
      2. Creates a Docker workspace with your repo
      3. Starts Claude Code with your task description
      4. Streams agent output back to project chat
         |
    Agent streams results back as it works

Architecture

Layer	What	How
Control plane	API, auth, orchestration	Cloudflare Workers + D1 + KV + R2
Real-time data	Chat messages, activity, sessions	Durable Objects with embedded SQLite (per project)
Compute	Workspaces running coding agents	Hetzner VMs with a Go agent managing Docker containers, WebSocket terminal, and auth
Warm pool	Fast workspace starts	Completed VMs stay warm for 30 min for instant reuse

The control plane is serverless — no servers to manage, no databases to back up. Compute scales to zero when you're not using it.

Repository Structure

apps/
  api/          Cloudflare Worker API (Hono)
  web/          Control plane UI (React + Vite)
  www/          Marketing site, blog & docs (Astro + Starlight)
packages/
  shared/       Shared types and utilities
  providers/    Cloud provider abstraction (Hetzner)
  cloud-init/   Cloud-init template generator
  vm-agent/     Go VM agent (PTY, WebSocket, MCP tool endpoints)
  ui/           Design system tokens and shared UI components
  terminal/     Shared terminal component

For the full architecture with diagrams, see the Architecture Overview.

Quick Deploy

SAM deploys automatically via GitHub Actions. Fork, configure, push. For the complete setup guide with detailed steps and troubleshooting, see the Self-Hosting Guide.

Prerequisites

• A Cloudflare account (Workers Paid plan, $5/mo)
• A domain with nameservers pointing to Cloudflare
• A GitHub App for OAuth + repo access

Steps

1. Fork this repository
2. Create a GitHub Environment named production in your fork's Settings > Environments
3. Add the required secrets (Cloudflare API token, GitHub App credentials, etc. — see the Self-Hosting Guide for the full list)
4. Push to main — GitHub Actions provisions all infrastructure, deploys the API + UI, runs migrations, and verifies health

Your instance is live at app.{your-domain}. Users sign in with GitHub and provide their own Hetzner API token to create workspaces.

Development

pnpm install        # Install dependencies
pnpm build          # Build all packages
pnpm test           # Run tests
pnpm typecheck      # Type check
pnpm lint           # Lint
pnpm format         # Format

Build packages in dependency order: shared > providers > cloud-init > api / web.

For local development details, see the Local Development Guide.

Documentation

Full documentation is available at simple-agent-manager.org/docs:

• Self-Hosting Guide — deploy your own instance
• Architecture Overview — how the system works
• Security Model — BYOC, encryption, credentials
• Local Development — contributing and development setup

License

AGPL-3.0