agentserver

Personally command and deploy AI agents across every location and device — from one place.

📖 Read the full vision: Overview of agentserver (slide deck, Apr 2026)

agentserver is a self-hosted platform for operating a fleet of coding agents from one console — cloud sandboxes, your laptop, your desktop, even your phone, all reachable through the same Web UI or an IM channel (WeChat / Weixin, Telegram, …).

It is the answer to a question Addy Osmani frames as the path from L1 (no AI) to L8 (build your own orchestrator)*: once you are juggling 10+ agents across machines, you stop being a conductor and become an orchestrator. agentserver is the orchestration layer.

_{* Addy Osmani, Director, Google · Gemini & Cloud AI — talks.addy.ie/oreilly-codecon-march-2026}

How it differs from what already exists

Why agentserver?

• One console, every device — Operate cloud sandboxes, local laptops/desktops, and IM-bound agents from the same workspace.
• Local tunneling, zero public IP — A local opencode/Claude Code/Codex instance dials home over WebSocket and appears as a sandbox in the UI.
• Sandboxes — Per-task containers with pause/resume and idle auto-pause; Docker (single node) or Kubernetes with Agent Sandbox + gVisor.
• Multi-tenancy by workspace — Cloud and local agents register into the same workspace registry; role-based access (owner / maintainer / developer / guest).
• Credential & LLM proxy — Sandboxes never see real provider keys; per-workspace RPD quotas and usage tracking enforced server-side.
• IM bridge (WIP) — Drive agents from WeChat / Weixin or Telegram via imbridge; no terminal required.
• SSO ready — GitHub OAuth and generic OIDC (Keycloak, Authentik, …).
• Deploy anywhere — Pre-built binaries, Homebrew, Docker Compose, or Helm for Kubernetes.

Roadmap: Three Stages

agentserver is being built in three stages. The diagrams and full reasoning live in Overview of agentserver.pdf.

Core insights driving Stage 3

• Stateless harness — Decouple the brain (Claude + harness) from the hands (sandboxes and tools). Sessions are append-only event logs that live outside the context window. Workers are cattle, not pets — a worker that dies mid-turn loses nothing.
• Hybrid cloud-local mesh — Cloud and local agents share one workspace registry. Discovery happens through agent cards; the LLM picks a tool and a tool router decides where the call goes. Agent discovery, not network mesh.
• Async collaboration via mailboxes — Agents hand off work through inboxes in durable storage. The receiver does not need to be alive when the message is sent. The mailbox is the source of truth.

Architecture

Today's deployment (Stage 1, with Stage 2 services landing):

                  World (Anthropic, GitHub, …)
                          ▲
                          │ egress
              ┌───────────┴────────────┐
              │  credentialproxy /     │
              │  llmproxy (:8081)      │
              │  • key injection       │
              │  • RPD quota / usage   │
              └───────────┬────────────┘
                          │
WeChat / Telegram ──▶ imbridge ──▶ ┐
Browser ───────────▶ agentserver  ─┤    ┌──────────────────┐
                     (:8080)       │    │ sandbox pod /    │
                     • REST API    ├───▶│ container        │
                     • admin UI    │    │ └─ opencode /    │
                     • registry    │    │    nanoclaw      │
                     • tunnels     │    └──────────────────┘
                          │        │
                          │        └──▶ local laptop / desktop / phone
                          │              └─ agentserver-agent (WS tunnel)
                          ▼
                     PostgreSQL
                  (users, workspaces,
                   sandboxes, quotas,
                   sessions, mailboxes)

Browser ──▶ sandboxproxy (:8082) ─▶ subdomain routing to sandbox services
Browser ──▶ cc-broker          ───▶ stateless cc worker pool (Stage 3)
Sandbox ──▶ executor-registry  ───▶ tool-call dispatch / executor lookup

Code of Conduct

agentserver follows four house rules that shape every change:

• ❌ No human-authored code. All production code is generated by AI agents.
• ✅ Open source from day 1. The repository is public from inception; no closed-source phase.
• ✅ Fully automated DevOps. Build, test, release, and deployment are end-to-end automated.
• ✅ Dogfooding & bootstrapping. agentserver is built (partially) with agentserver — every feature is used by our own agents before it ships.

Quick Start

Docker Compose (recommended for local use)

git clone https://github.com/agentserver/agentserver.git && cd agentserver
docker build -f Dockerfile.opencode -t agentserver-agent:latest .
export ANTHROPIC_API_KEY="sk-ant-..."
docker compose up -d

Open http://localhost:8080 in your browser.

Helm (Kubernetes)

helm install agentserver oci://ghcr.io/agentserver/charts/agentserver \
  --namespace agentserver --create-namespace \
  --set database.url="postgres://user:pass@postgres:5432/agentserver?sslmode=disable" \
  --set anthropicApiKey="sk-ant-..." \
  --set ingress.enabled=true \
  --set ingress.host="cli.example.com" \
  --set baseDomain="cli.example.com"

Pre-built Binaries

Download from GitHub Releases, or install via Homebrew:

brew install agentserver/tap/agentserver

Local Agent Tunneling

Connect a locally-running opencode instance to agentserver — no public IP or third-party tunnel needed.

1. In the Web UI, click the laptop icon next to "Sandboxes" to generate a registration code.

2. On your local machine:

# First time — register with the server
agentserver connect \
  --server https://cli.example.com \
  --code <registration-code> \
  --name "My MacBook"

# Subsequent runs — auto-reconnect using saved credentials
agentserver connect

1. A local sandbox appears in the Web UI — click "Open" to access your local opencode through the browser.

Multi-agent support

Register multiple agents on the same machine, each targeting a different directory and workspace:

# List all registered agents
agentserver list

# Remove a registration
agentserver remove --workspace <workspace-id>

Agent credentials are stored in ~/.agentserver/registry.json.

Tunnel features: zero-config networking, auto-reconnect with backoff, binary WebSocket protocol (no base64 overhead), real-time SSE streaming, offline detection with auto-recovery.

Configuration

See the API reference for full endpoint documentation.

helm upgrade agentserver oci://ghcr.io/agentserver/charts/agentserver \
  --reuse-values \
  --set oidc.redirectBaseUrl="https://cli.example.com" \
  --set oidc.github.enabled=true \
  --set oidc.github.clientId="your-client-id" \
  --set oidc.github.clientSecret="your-client-secret"

helm upgrade agentserver oci://ghcr.io/agentserver/charts/agentserver \
  --reuse-values \
  --set oidc.redirectBaseUrl="https://cli.example.com" \
  --set oidc.generic.enabled=true \
  --set oidc.generic.issuerUrl="https://idp.example.com/realms/main" \
  --set oidc.generic.clientId="agentserver" \
  --set oidc.generic.clientSecret="your-secret"

helm upgrade agentserver oci://ghcr.io/agentserver/charts/agentserver \
  --reuse-values \
  --set backend=k8s \
  --set opencode.runtimeClassName=gvisor \
  --set sandbox.namespace=agentserver

Building from Source

# Prerequisites: Go 1.26, Node.js, pnpm, bun

# Build everything (frontend + backend)
make build

# Build individual components
make backend          # Go binary → bin/agentserver
make frontend         # React frontend → web/dist/
make agent            # Local agent binary → bin/agentserver-agent
make agent-all        # Agent for all platforms (linux/darwin/windows, amd64/arm64)
make llmproxy         # LLM proxy binary → bin/llmproxy

# Docker images
make docker           # Main server image
make docker-agent     # Agent container image
make docker-llmproxy  # LLM proxy image
make docker-all       # All images

Contributing

# Terminal 1: Start backend
go run . serve --db-url "postgres://..." --backend docker

# Terminal 2: Start frontend dev server
cd web && pnpm install && pnpm dev

Per the Code of Conduct, production code is AI-generated. Pull requests authored by an agent (with a human reviewer) are welcome; the repo is dogfooded against itself.

License

MIT