AgentPod
The fleet and facilities console for agent runtimes. AgentPod manages the machines and
workspaces your agents live in: files, logs, terminals, configuration, health, lifecycle,
cleanup, and provisioning. Attach to runtimes you already run, or provision new ones.
Documentation · Node-agent downloads · Self-hosting · Operations
Current console rendered locally with synthetic demo nodes, agents, and activity. No live fleet
or credentials are shown; this image illustrates the UI, not a deployment health check.
Highlights
- Attach across hosts and harnesses. Detect Hermes, OpenClaw, Claude Code, Codex,
OpenCode, and Pi using harness-specific descriptors. Capabilities depend on the harness.
- Reach hosts behind NAT. Each node dials out to the hub over WSS; nodes need no inbound ports.
- Operate from one console. Inspect stations, browse files, tail logs, open terminals,
and manage supported lifecycle and cleanup actions. The roster and attention lane surface
offline nodes, unavailable stations, and node version drift.
- Control agent access. Principals, station occupancy, and dispatch grants connect runtime
operations to agent identity. Optional Matrix and SuperPipeline integrations connect the
runtime plane to communication and work orchestration.
- Roll updates deliberately. Update a node with
apn update, or request an individual or
fleet update from the hub. Node agents do not upgrade on a timer.
AgentPod owns runtime management. SuperPipeline
owns boards, cards, runs, and approval gates; SuperMessage
is the Matrix client.
Architecture
Operator → SvelteKit console → Hub (HTTPS + WSS)
↑ outbound WSS connections
node-agent on each host
↓
harness stations
| Component | Technology | Responsibility |
|---|
apps/node-agent | Go daemon | Detect harnesses; execute local station capabilities; enroll with and connect to the hub |
apps/hub | Bun, Hono, Drizzle, Postgres + pgvector | Registry, broker, authentication, audit, provisioning, integrations |
apps/console | SvelteKit, Svelte 5, static SPA | Fleet roster, node and station panels, runtime and access management |
packages/contract | TypeScript, Zod | Shared node/hub/console schemas |
docs-site | Astro, Starlight | User and integration documentation; separate npm project |
The descriptor registry is registry.go.
See the documentation map for current runbooks and historical designs.
Run locally
Requires Bun, Node.js 20+, the repository-pinned pnpm 10.18.2, and a dedicated
Postgres database with pgvector. Building the node-agent from source also requires the
Go version in go.mod. The docs site requires Node.js 22.12+.
git clone https://github.com/SuperJackfruitLabs/agentpod.git
cd agentpod
corepack enable
pnpm install --frozen-lockfile
cp apps/hub/.env.example apps/hub/.env
Set DATABASE_URL in apps/hub/.env to your local pgvector database. The example's credentials
are for local development; use the deployment guide for production secrets,
origins, cookies, and provisioning configuration. Hub migrations run on startup.
Start the hub and console in separate terminals, from the repository root:
pnpm --filter @agentpod/hub dev
PUBLIC_HUB_URL=http://localhost:3001 pnpm --filter @agentpod/console dev
Open http://localhost:5173. The first registered account becomes admin and public signup
closes; admins can manage users. AgentPod currently resolves requests to one bootstrap tenant,
not independently managed organizations. Principals and grants are implemented within that boundary.
Enroll a host
Create an enrollment token in the console, then follow
Enroll your first node. The
release assets include the installer,
checksums, and node-agent binaries for Linux and macOS, amd64 and arm64. These are node-agent
releases; the hub and console run from source or deployed builds.
On an enrolled host, apn status, apn logs, and apn restart manage the service. See
CLI documentation and the operations guide
for enrollment, adoption, service installation, and updates.
Deploy your own instance
Follow Deployment for the full setup. Build the console with its intended
hub URL; it is embedded at build time:
PUBLIC_HUB_URL=https://hub.example.com pnpm --filter @agentpod/console build
The build needs Node 22 or newer (the console is built on the vendored vibekit design system,
see apps/console/vendor/README.md); there are no other build
variables. The output is apps/console/build/. Serve it on a same-site custom domain such as
console.example.com and configure the hub's allowed origins and cookie settings. A raw
*.pages.dev preview is not interchangeable with that authenticated deployment.
Development and validation
Branch from main and submit a scoped PR. See contributing,
project instructions, and TESTING.md for tier-specific requirements.
Run these commands from the repository root:
(cd packages/contract && bun test)
(cd apps/node-agent && go test -race ./...)
pnpm --filter @agentpod/console check
pnpm --filter @agentpod/console test
pnpm --filter @agentpod/console build
The console also has an accessibility and overflow sweep against a stubbed hub (axe-core, no
horizontal scroll, no console errors, 44px touch targets under 1024px). It is not part of
pnpm test; it needs a build and an already installed Playwright Chromium:
cd apps/console
PUBLIC_HUB_URL=https://hub.agentpod.dev pnpm build
pnpm e2e:sweep --vibes=daylight # or paper, studio, quiet; --only=fleet,agents; --detail
Hub tests need the separate pgvector test database described in TESTING.md,
including its migration preparation. Always pass an explicit test URL: Bun otherwise loads
apps/hub/.env, which may point to a development database.
(cd apps/hub && DATABASE_URL=postgres://agentpod:agentpod-dev-password@localhost:5434/agentpod bun test)
CI additionally checks contract fixtures and provider wrappers and runs the separate
cloudflare/worker-v2 suite. The workflow is the complete check list.
Project status
Active development. Releases describe
node-agent builds; CHANGELOG.md records changes. Source on main may be newer
than the latest release. The previous OpenCode-based product is archived under
docs/archive; it is not the current three-tier product.
License
MIT.
