AgentPane

Background AI agents that work while you don't. A GitHub issue opens, a cron schedule fires, a webhook lands — AgentPane spins up agents in isolated sandboxed environments, plans the work, writes the code, and waits for your review. Every tool call, every file change, every decision streams back to you in real time through durable event streams that survive disconnects and replay on reconnect. You stay in control without staying in the loop.

Running AI agents in the background creates hard problems: agents need filesystem isolation so they don't corrupt each other's work, long-running sessions need event streams that survive network drops without losing data, and external triggers need to flow through a verified pipeline before an agent touches your code. AgentPane solves these with git worktree isolation per agent, a dual-write event pipeline (SQLite for durability, Caddy SSE for real-time delivery) with offset-based replay on reconnect, and a pluggable webhook system with HMAC verification, subscription filters, and template interpolation that converts external signals into agent-ready tasks — all running inside isolated sandboxed environments across Docker, Kubernetes, Nomad, or AWS Bedrock AgentCore.

Architecture

System-level view of the AgentPane platform showing the browser client, Go CLI + SDK, published packages, 15 frontend view modules, Caddy durable streams, Hono API (40 route modules, 60+ endpoints), 17+ services, Drizzle ORM (44 tables, SQLite + PostgreSQL), prompt registry, credential/skill injectors, memory layer (MemoryStore, DreamService, InsightDeriver), 5 sandbox providers (Docker, K8s CRD, Nomad, AWS Bedrock AgentCore, Devcontainer), agent execution pipeline, 7-phase bootstrap, and 4 background schedulers.

Tenancy Model

Authentication, ownership hierarchy, and role-based access control. Shows the GitHub OAuth flow, workspace/folder/codespace/task ownership chain, folder-level RBAC with role cascade, 35 permission actions, event system scoping (team → codespace), 10 codespace-scoped resources, template/marketplace scoping, and global resources.

OpenShift Deployment

Private network deployment on OpenShift with Cloudflare Tunnel for inbound webhook delivery via agentpane.teams. Caddy front door on :3000, dual webhook endpoints, 5 sandbox providers, 5 background schedulers, 4 K8s CRD types with gVisor, and multi-stage Docker build. No inbound firewall rules needed — the cloudflared pod initiates an outbound-only tunnel to Cloudflare Edge.

Durable Streams

End-to-end event streaming pipeline: 48 event types across 8 channels, structured envelope protocol (OC-005d), ChunkBatcher, dual-write DurableStreamsService (SQLite + Caddy with LRU producer pool), SSE delivery, Zod validation, 10 TanStack DB collections, and reactive UI with ref-counted SSE sharing.

Events System

Webhook ingestion pipeline: 5 source types (2 implemented: GitHub + Cron), dual endpoints (/hooks/events/:slug + /hooks/github-app), HMAC verification with 5 signature headers, DI-based PluginRegistry, subscription matching with field filters, template interpolation, team-scoped routing to codespace tasks with auto-start, 4-table schema with 90-day retention cleanup.

Features

Agent Orchestration

• Multi-Agent Concurrency — Multiple AI agents working simultaneously on different tasks
• Plan → Execute Workflow — Agents plan first, then execute after user approval
• Teams Mode (planned) — During planning, an agent can request parallel execution by spawning multiple sub-agents to work on different parts of the plan concurrently
• Git Worktree Isolation — Each agent works in an isolated git worktree
• Session Replay — Full session history with timeline, event filtering, and play/pause/seek controls
• Agent Topology — Real-time React Flow graph showing live agent activity with ELK auto-layout
• AI-Assisted Planning — Interactive planning sessions where Claude asks clarifying questions before execution
• Persistent Memory — Internal DB-backed agent memory with automatic context injection from previous sessions. The memory service derives insights from agent interactions via Claude analysis, stores them in SQLite/PostgreSQL, and injects relevant context into new agent prompts. Includes DreamService (24h skill improvement cycle), InsightDeriver, and SkillTracking. Memory is scoped per-codespace and persists across agent sessions.

Task Management

• Kanban Board — Drag-and-drop workflow: Backlog → Queued → In Progress → Waiting Approval → Verified
• Auto-Start — Moving a task to "In Progress" automatically assigns and starts an agent
• AI Task Creation — Claude asks multi-round clarifying questions to refine task requirements before submission
• Code Review — Approve or reject agent changes with diff visualization before merge
• Live Task View — Alternative to the Kanban board: a 3-column layout with resizable task list sidebar (status filters, search, keyboard navigation), real-time agent topology graph (React Flow + ELK auto-layout showing live agent activity), and audit trail panel with session events + live SSE streaming

Sandboxed Execution

• Docker Containers — Run agents in isolated Docker containers with codespace bind-mounts
• Kubernetes CRD — Agent Sandbox SDK for Kubernetes pod provisioning via agents.x-k8s.io/v1alpha1
• Nomad Jobs — HashiCorp Nomad sandbox provider for job-based agent isolation
• AWS Bedrock AgentCore — Managed AWS runtimes with STS auth, ECR image validation, and orphan cleanup
• Per-Codespace or Shared — Choose between a shared container or per-codespace isolation
• Skill Injection — Tasks can reference a skillId that maps to a .claude/skills/{skillId}/SKILL.md file. Org and template skills are automatically materialized into the sandbox filesystem before agent execution. The agent prompt includes a lightweight use skill {name} directive — the agent reads the full skill content from disk.

Terraform No-Code Composer

• Natural Language → HCL — Generate Terraform configurations from plain English via Claude
• Private Module Browser — Browse and search modules from your connected private Terraform registry
• Dependency Diagrams — Visual resource dependency graphs (React Flow + ELK)
• Composition History — Track and revisit previous compositions
• Variable Forms — Interactive variable input with smart widget inference and .tfvars generation
• Registry Sync — Background scheduler auto-syncs registry data on configurable intervals

Plugin Marketplace

• GitHub-Synced Plugins — Browse Claude plugins synced from GitHub repos
• Multiple Sources — Add internal and external marketplace sources
• Category Browse — Filter and explore plugins by category

Templates

• GitHub-Synced Templates — Add GitHub repos as template sources for skills, commands, and agents
• Org & Codespace Scoping — Templates can be scoped to an organization or individual codespace
• Auto-Sync — Background scheduler syncs template changes from GitHub on configurable intervals

Integrations

• GitHub App — Repository sync via PAT or GitHub App installation tokens, webhook-triggered template sync
• Workflow Designer — Visual AI-powered workflow editor with drag-and-drop (React Flow + ELK)
• Workflow Catalog — Browse saved workflows with SVG previews, search, filter, and pagination
• Git View — 5-column dashboard: PRs, worktrees, commits, local branches, remote branches
• CLI Monitor — Real-time monitoring of Claude CLI sessions (@agentpane/cli-monitor)
• Durable Streams — Real-time event streaming via Caddy front door (LMDB-backed SSE + long-poll)
• Encrypted API Keys — UI-managed per-service API key storage with masked display
• Factory Hook Architecture — useEffect is banned via Biome lint rules. All side effects use purpose-built factory hooks: useMountEffect() for mount/unmount, useWatchEffect() for value changes, useInterval(), useTimeout(), useEventListener(), and useAutoScroll(). This eliminates exhaustive dependency lint suppressions and makes intent explicit.
• Memory Service — Internal DB-backed persistent agent memory. Stores memory messages, insights, skill executions, and skill metrics in SQLite/PostgreSQL. Agents automatically receive relevant context from prior sessions via the InsightDeriver. Includes DreamService for periodic skill analysis and improvement suggestions. Memory is scoped per-codespace.

Organization

• Folder Hierarchy — 3-tier organizational model: Workspace → Project Folders → Codespaces. Folders group related codespaces with folder-level RBAC membership. Teams are linked to folders via team_project_folders, and access cascades from folder to codespace level.

CLI & SDK

• Go CLI (agentpane) — Full-featured command-line interface for AgentPane. Manage codespaces, tasks, agents, sessions, and worktrees from the terminal. Supports JSON output (-json flag) for scripting and piping to jq. Configuration via environment variables (AP_API_TOKEN, AP_ADDRESS, AP_CODESPACE).
• Go SDK — Typed Go client library at cli/sdk/ for programmatic API access. Includes typed request/response structs for all API resources.

Tech Stack

Layer	Technology	Package	Version
Runtime	Bun	bun.sh	1.3.10
Build	Vite	vite	8.0.1
Front Door	Caddy (durable-streams-server)	durable-streams	0.2.2
Framework	TanStack Start	@tanstack/react-start	1.166.1
API Router	Hono	hono	4.12.8
Database	SQLite + PostgreSQL	better-sqlite3 / postgres	12.8.0 / 3.4.8
ORM	Drizzle	drizzle-orm + drizzle-kit	0.45.1 / 0.31.10
Validation	Zod	zod	4.3.6
Client State	TanStack DB	@tanstack/db + @tanstack/react-db	0.5.33 / 0.1.77
Real-time	Durable Streams	@durable-streams/*	0.2.x
AI / Agents	Claude Agent SDK	@anthropic-ai/claude-agent-sdk	0.2.76
AI / API	Anthropic SDK	@anthropic-ai/sdk	0.78.0
Memory	Internal DB	MemoryService + DreamService	Built-in
UI	React + Radix + Tailwind	react + @radix-ui/* + tailwindcss	19.2.4 / 4.1.18
Flow Editor	React Flow	@xyflow/react	12.10.1
Graph Layout	ELK	elkjs	0.11.0
Drag & Drop	dnd-kit	@dnd-kit/core + @dnd-kit/sortable	6.3.1 / 10.0.0
Icons	Phosphor	@phosphor-icons/react	2.1.10
Syntax	Shiki	shiki	3.22.0
Markdown	react-markdown	react-markdown	10.1.0
Testing	Vitest	vitest	4.0.16
E2E Testing	Playwright	@playwright/test	1.58.1
Linting	Biome	@biomejs/biome	2.4.4
Containers	Dockerode	dockerode	4.0.10
Kubernetes	K8s Client	@kubernetes/client-node	1.4.0
AWS	AWS SDK	@aws-sdk/client-sts	3.1004.0
GitHub	Octokit	octokit	5.0.5

Getting Started

Prerequisites

• Bun 1.3.10+
• Node.js 24.0.0+
• Docker (optional, for sandboxed agent execution)
• AWS Account (optional, for AWS Bedrock AgentCore sandbox execution)

Installation

# Clone the repository
git clone https://github.com/agentdevsl/agentpane.git
cd agentpane

# Install dependencies
bun install

# Set up the database (SQLite by default)
bun run db:push

Configuration

Set the following environment variables (or configure via the Settings UI):

Variable	Required	Description
ANTHROPIC_API_KEY	Yes	API key for Claude Agent SDK
DB_MODE	No	sqlite (default) or postgres
DATABASE_URL	If postgres	PostgreSQL connection string
CADDY_STREAMS_URL	No	Override streams server URL (default: http://localhost:3002)
GITHUB_TOKEN	No	GitHub personal access token
GITHUB_APP_ID	No	GitHub App ID for installation tokens
GITHUB_PRIVATE_KEY	No	GitHub App private key
GITHUB_WEBHOOK_SECRET	No	Secret for verifying GitHub webhooks
CORS_ORIGIN	Production	Allowed CORS origin

AWS Bedrock AgentCore credentials (access key, secret key, region, runtime ARN) are configured via the Settings UI under sandbox.agentcore, not environment variables.

Development

# Start frontend, API, and streams servers
bun run dev

This starts:

• Frontend: Vite dev server on port 3000
• API: Hono backend on port 3001
• Streams: DurableStreamTestServer on port 3002

PostgreSQL (Optional)

For production or multi-user setups, switch to PostgreSQL:

# Start PostgreSQL via Docker
bun run docker:pg

# Push schema to PostgreSQL
bun run db:push:pg

# Open Drizzle Studio (PostgreSQL)
bun run db:studio:pg

Then set DB_MODE=postgres and DATABASE_URL to use PostgreSQL at runtime.

Build

# Production build (frontend + typecheck + agent-runner)
bun run build

Project Structure

├── src/
│   ├── app/
│   │   ├── routes/              # TanStack Start file-based routes (51 routes)
│   │   └── components/
│   │       ├── ui/              # Radix-based primitives (Button, Dialog, etc.)
│   │       └── features/        # Feature modules (20 modules)
│   │           ├── kanban-board/         # Drag-drop task board
│   │           ├── terraform/            # No-code HCL composer
│   │           ├── agent-session-view/   # Real-time agent execution
│   │           ├── agent-topology/       # Live agent graph (React Flow + ELK)
│   │           ├── plan-session-view/    # Interactive planning with Claude
│   │           ├── approval-dialog/      # Code review modal
│   │           ├── container-agent-panel/ # Container execution UI
│   │           ├── workflow-designer/    # Visual workflow editor
│   │           ├── workflow-catalog/     # Workflow browser with SVG previews
│   │           ├── git-view/            # Git dashboard (PRs, branches, worktrees)
│   │           ├── cli-monitor/         # CLI event streaming
│   │           ├── live-task-view/         # 3-column live task dashboard
│   │           ├── session-history/     # Session list with filters
│   │           └── ...
│   ├── db/
│   │   └── schema/              # Drizzle schemas (SQLite + PostgreSQL)
│   │       ├── sqlite/          # SQLite schema (42 tables)
│   │       ├── postgres/        # PostgreSQL schema (42 tables)
│   │       └── shared/          # Shared enums and types
│   ├── lib/
│   │   ├── agents/              # Claude Agent SDK integration
│   │   ├── sandbox/             # Sandbox providers (Docker, K8s CRD, Nomad, AgentCore)
│   │   ├── streams/             # Durable Streams / Caddy producer
│   │   ├── state-machines/      # 4 state machines (agent, task, session, worktree)
│   │   ├── terraform/           # Terraform compose prompts
│   │   ├── prompts/             # Prompt registry and templates
│   │   ├── bootstrap/           # 7-phase app initialization
│   │   └── ...
│   ├── server/
│   │   └── routes/              # Hono API routes (38 route files)
│   └── services/                # Business logic (50+ service files)
│       ├── agent/               # Agent CRUD, execution, queueing
│       ├── session/             # Session CRUD, streaming, presence
│       ├── cli-monitor/         # CLI monitoring infrastructure
│       ├── memory/               # DB-backed persistent agent memory
│       ├── terraform-compose.service.ts
│       ├── container-agent.service.ts
│       ├── marketplace.service.ts
│       ├── template.service.ts
│       ├── sandbox.service.ts
│       └── ...
├── cli/                          # Go CLI + SDK (agentpane command)
│   ├── main.go                   # Entry point
│   ├── sdk/                      # Go SDK (API client, typed resources)
│   └── internal/                 # CLI internals (commands, output)
├── agent-runner/                # Claude Agent SDK runner for containers
├── packages/
│   ├── agent-sandbox-sdk/       # @agentpane/agent-sandbox-sdk (K8s CRD client)
│   ├── cli-monitor/             # @agentpane/cli-monitor (npm package)
│   └── nomad-sandbox-sdk/       # @agentpane/nomad-sandbox-sdk (Nomad HTTP client)
├── Caddyfile                    # Caddy front door config (streams, proxy, static)
├── docker/
│   ├── Dockerfile               # Multi-stage build (deps → build → caddy → runtime)
│   ├── Dockerfile.agent-sandbox # Agent sandbox environment
│   ├── Dockerfile.agentcore    # AWS Bedrock AgentCore runtime (ARM64)
│   ├── start.sh                 # Entrypoint: starts Caddy + Bun
│   ├── docker-compose.yml       # Development (SQLite)
│   ├── docker-compose.postgres.yml # Production (PostgreSQL)
│   └── docker-compose.memory.yml # Memory service (PostgreSQL + Redis, legacy)
├── k8s/                         # Kubernetes manifests
├── specs/
│   └── application/             # Complete application specifications
│       ├── api/                 # REST API (60+ endpoints)
│       ├── components/          # UI component specs (19 specs)
│       ├── database/            # Database schema
│       ├── services/            # Service layer
│       ├── state-machines/      # State machine specs (4 machines)
│       ├── testing/             # Test infrastructure (193 test cases)
│       ├── wireframes/          # Visual designs (42 HTML wireframes)
│       └── ...
├── scripts/                     # Dev, testing, migration, and K8s scripts
└── tests/                       # Unit, integration, and E2E test suites

Agent Execution Flow

Task moved to "In Progress"
  → Auto-assign idle agent (or create new)
  → Create git worktree for isolation
  → Planning phase (Claude SDK, plan mode)
  → User reviews and approves plan
  → Execution phase (teams mode planned)
  → Task moves to "Waiting Approval"
  → User reviews diffs and approves/rejects

Sandbox Providers

Provider	Description	Status
Docker	Container-based isolation with codespace bind-mounts	Active
Agent Sandbox SDK	Kubernetes CRD-based pod provisioning (agents.x-k8s.io/v1alpha1)	Active
Nomad	HashiCorp Nomad job-based isolation via @agentpane/nomad-sandbox-sdk	Active
AWS Bedrock AgentCore	Managed AWS runtimes via Bedrock Agent Runtime API with STS/ECR integration	Active
Kubernetes (direct)	Direct K8s pod management with RBAC	Archived

Events System

AgentPane includes a pluggable event system that converts external signals — GitHub webhooks, scheduled cron jobs, or custom HTTP webhooks — into tasks that agents can automatically pick up and execute.

External Event (GitHub, Linear, Jira, Cron)
  → /hooks/events/:slug (public, HMAC-verified)
  → Plugin normalizes to NormalizedEvent
  → Deduplicate via deliveryId (idempotent)
  → Match subscriptions (event type + field filters)
  → Interpolate prompt template with event data
  → Create task (optionally auto-start agent)

Event Sources — Team-scoped webhook endpoints. Each source gets a unique slug and encrypted HMAC secret. Supported types:

Source	Signature Header	Events
GitHub	X-Hub-Signature-256	issues, pull_request, push, ping
Linear	Linear-Signature	Issue and project events
Jira	X-Hub-Signature	Issue and sprint events
Generic Webhook	X-Webhook-Signature	Any JSON payload
Cron	N/A (internal)	schedule.tick, schedule.manual_trigger

Event Subscriptions — Route events from a source to a codespace. Each subscription defines which event types to match, optional field filters (repo, branch, labels, author, action), a prompt template with {{variable}} interpolation, and which Kanban column to place the created task in. If the target column is "In Progress", the task auto-starts an agent.

GitHub Issue Events — When a GitHub issue is opened (or labeled, assigned, etc.), the webhook delivers the event, the GitHub plugin normalizes it, matching subscriptions render their prompt templates with issue data ({{issue.title}}, {{issue.body}}, {{repo.full_name}}, etc.), and a task is created in the target codespace. This enables fully automated issue-to-agent pipelines.

Webhookd — The webhook delivery infrastructure. Public endpoint at /hooks/events/:slug sits outside the /api/* auth boundary (rate-limited at 60 req/min per IP). Webhook secrets are AES-256 encrypted at rest with rotation via POST /api/events/sources/:id/rotate-secret. Deduplication uses a unique constraint on (eventSourceId, deliveryId) so retried deliveries from external systems are silently accepted without creating duplicate tasks. The full event audit trail is stored in the event_log table with status tracking (received → matched → task_created | ignored).

Scheduler — A lightweight polling-based scheduler for cron event sources. Ticks every 30 seconds (configurable via SCHEDULER_TICK_INTERVAL_MS), evaluates cron expressions and simple intervals, and feeds synthetic events through the same processing pipeline as webhooks. Features include:

• Budget enforcement — Max executions per hour/day/week/month to prevent runaway costs
• Timezone-aware — Cron expressions respect configured IANA timezones
• Auto-pause — Sources auto-pause after 5 consecutive errors
• CAS locking — Compare-and-swap on nextRunAt prevents duplicate execution
• Recovery — On restart, missed executions are skipped (clock is not rewound)
• Manual trigger — POST /api/events/sources/:id/trigger for on-demand execution

Additional schedulers handle template sync and Terraform registry sync on configurable intervals (minimum 5 minutes).

Real-Time Streaming — All event processing outcomes are broadcast to connected SSE clients via the in-process event bus, enabling live updates in the Events UI. Agent execution events flow through a separate path: DurableStreamsService dual-writes to SQLite and Caddy, with offset-based replay on reconnect (see Durable Streams diagram above).

Plugin Architecture — New event sources are added by implementing EventSourcePlugin (signature verification, event parsing, filter matching, template variables) and registering in the PluginRegistry. The registry is dependency-injected for test isolation.

Available Scripts

Script	Description
bun run dev	Start frontend (3000) + API (3001) + streams (3002)
bun run dev:api	Start API server only
bun run dev:vite	Start Vite frontend only
bun run build	Production build (frontend + typecheck + agent-runner)
bun run test	Run unit tests
bun run test:watch	Run tests in watch mode
bun run test:coverage	Run tests with coverage
bun run test:e2e	Run E2E tests (Vitest + Playwright config)
bun run test:ui	Run AI-powered UI tests
bun run test:integration	Run integration tests
bun run test:k8s	Run Kubernetes integration tests
bun run lint	Lint with Biome
bun run lint:fix	Lint and auto-fix
bun run format	Format with Biome
bun run check	Lint + format check
bun run check:fix	Lint + format auto-fix
bun run typecheck	TypeScript type check
bun run db:generate	Generate Drizzle migrations (SQLite)
bun run db:push	Push schema to SQLite
bun run db:migrate	Run SQLite migrations
bun run db:studio	Open Drizzle Studio (SQLite)
bun run db:generate:pg	Generate Drizzle migrations (PostgreSQL)
bun run db:push:pg	Push schema to PostgreSQL
bun run db:migrate:pg	Run PostgreSQL migrations
bun run db:studio:pg	Open Drizzle Studio (PostgreSQL)
bun run db:migrate:sqlite-to-pg	Migrate data from SQLite to PostgreSQL
bun run docker:pg	Start PostgreSQL via Docker Compose
bun run docker:pg:down	Stop PostgreSQL Docker Compose

Packages

Package	Description
@agentpane/agent-sandbox-sdk	TypeScript SDK for the kubernetes-sigs Agent Sandbox CRD (agents.x-k8s.io/v1alpha1)
@agentpane/cli-monitor	CLI monitor daemon — watches Claude Code sessions in real-time
@agentpane/nomad-sandbox-sdk	TypeScript SDK for HashiCorp Nomad sandbox management via HTTP API
agentpane CLI	Go CLI and SDK for AgentPane API — manage codespaces, tasks, sessions, and agents from the terminal

Documentation

• Specifications — /specs/application/README.md — Complete application specs (41 user stories, 60+ API endpoints, 19 component specs, 4 state machines, 193 test cases)
• Development Guide — AGENTS.md — Development guidelines, architecture, and coding conventions
• AI Assistant Guide — .claude/CLAUDE.md — AI-assisted development instructions

License

MIT