agentserver

Run your coding agent on any machine — access it from the browser.

agentserver is to opencode what code-server is to VS Code — a self-hosted platform that lets your team use a coding agent from the browser.

Why agentserver?

• Zero install — Open a browser, start coding with AI
• Sandboxes — Isolated containers per task; pause, resume, auto-pause on idle
• Local tunneling — Connect a local opencode instance via WebSocket, no public IP needed
• Multi-tenancy — Workspaces with role-based access (owner / maintainer / developer / guest)
• Two backends — Docker (single node) or Kubernetes with Agent Sandbox + gVisor isolation
• SSO ready — GitHub OAuth and generic OIDC (Keycloak, Authentik, etc.) out of the box
• API key proxy — Sandboxes never see the real Anthropic key; injected server-side
• LLM proxy — Dedicated proxy service with per-workspace rate limiting (RPD quotas) and usage tracking
• Admin panel — Manage users, quotas, and system settings from the web UI
• Batteries included — Sandbox image ships with Go, Rust, C/C++, Node.js, Python 3, and common tools
• Deploy anywhere — Pre-built binaries, Homebrew, Docker Compose, or Helm for Kubernetes

Architecture

agentserver consists of three services that can run as a single binary or be deployed independently:

                                                ┌──────────────────┐
                                                │  sandbox pod /   │
                                           ┌───▶│  container       │
                                           │    │  └─ opencode     │
Browser ──▶ sandbox-proxy (:8082) ─────────┤    └──────────────────┘
            (subdomain routing)            │        WebSocket tunnel
                                           └───▶ local agent machine
                                                  └─ opencode serve

Browser ──▶ agentserver (:8080) ──────────────▶ PostgreSQL
            ├─ REST API                         (users, workspaces,
            ├─ admin panel                       sandboxes, quotas)
            ├─ agent registration
            └─ tunnel endpoints

Sandbox ──▶ llmproxy (:8081) ──────────────▶ Anthropic API
            ├─ token validation                (real key injected
            ├─ RPD quota enforcement            server-side)
            └─ usage tracking

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

License

MIT