Multiplayer Agent Platform

An open, self-hosted runtime for operating collaborative AI agents. Teams can observe, steer, approve, pause, resume, and hand off long-running Agent sessions while retaining a replayable audit trail.

Status: v0.2 development preview. The end-to-end Docker runtime, multiplayer session workspace, event store, approvals, Artifact storage, Agent Manifest, encrypted Secret Store, OpenAI-compatible Model Gateway, extension registries, and Python SDK are working.

What works

• Immutable, versioned Agent Manifests
• One isolated Docker container and workspace per Agent session
• PostgreSQL-backed organizations, workspaces, users, sessions, events, audit metadata, approvals, artifacts, and checkpoints
• NATS live fan-out with PostgreSQL event replay
• Human pause, resume, cancellation, instruction, approval, and handoff APIs
• React multiplayer workspace
• Agent version catalog, organization Team, and administrator Audit pages
• 72-hour invitation links with a browser-based account acceptance flow
• Python Agent Protocol SDK
• Persistent MinIO/S3-compatible Artifact and Checkpoint uploads
• Local account bootstrap and organization invitation links
• Optional OIDC single sign-on with PKCE, JWKS ID token verification, and an email domain allowlist
• AES-256-GCM encrypted organization secrets with ephemeral runtime mounts
• OpenAI-compatible Model Gateway with Manifest-enforced provider and model
• Organization-scoped Model Provider, MCP Server, and versioned Skill registries
• Guided or raw-JSON Agent registration with Provider-backed model discovery
• Live per-Session Provider and model switching with immutable defaults
• Runtime leases with same-Runner Worker restart recovery
• Horizontally scalable Control Plane with a shared PostgreSQL tool-call queue
• Pluggable runtime backend: Docker containers or Kubernetes Pods, with Agent egress enforcement verified against Calico
• Helm chart deploying the platform onto Kubernetes with no Docker socket
• Agent WebSocket reconnection with idempotent resend of unacknowledged events
• Database-backed Session commands with Agent ACK and reconnect replay
• Controller handoff UI plus persisted Checkpoint listing and downloads
• Streamable HTTP, SSE, and stdio MCP tools/call execution with Manifest tool allowlists, human approval gates, and optional encrypted server credentials

The UI exposes Agent-authored status, plans, messages, and tool activity. It does not request or store hidden model chain-of-thought.

Quick start

Requirements: Linux Docker Engine with Compose. Docker Desktop is useful for development but is not the recommended production runtime.

cp .env.example .env
# Replace every placeholder in .env.
docker compose --profile sample build
docker compose up -d

Open http://localhost:8080, create the installation owner, then:

1. Create an organization and workspace.
2. Add a Model Provider under Extensions, including its base URL and API key.
3. Choose Register agent, bind primary to a discovered Provider model, and publish the pre-filled research Agent.
4. Start a session with a research topic.
5. Read the model response, send follow-up instructions at any time, then approve or reject report publication from the live timeline.

The sample Agent image is multiplayer-agent-platform/research-report-agent:local. It calls the selected model exclusively through the Model Gateway, so the Provider credential never enters the Agent container.

Architecture

Browser ──HTTP/SSE──> Web proxy ──> Go control plane ──> PostgreSQL
                                       │      │
                                       │      └────────> NATS
                                       └───────────────> MinIO / S3

Runtime worker ──Docker API──> isolated Agent container
       │                              │
       └──── internal network ────────┘ WebSocket Agent Protocol

The control plane never receives the Docker socket. Only the trusted runtime worker mounts it. Agent containers run with a read-only root filesystem, dropped capabilities, resource limits, and no access to the host network. Outbound HTTP and HTTPS requests are routed through an authenticated control plane proxy and allowed only when the destination matches the immutable Manifest's network.egressAllow entries.

Set a stable RUNNER_ID for every Docker host. Session leases are renewed by the active Worker; after expiry, a replacement Worker with the same Runner ID reclaims and monitors the existing Agent container. If the container is missing, the Session is safely returned to the queue with a new Agent token.

See Agent Protocol, Gateways and extensions, Authentication, High availability, Kubernetes, Helm chart, Metrics and tracing, Threat Model, the OpenAPI contract, and the Manifest JSON Schema.

Development

go test ./...
go run ./cmd/control-plane

cd web
npm ci          # package-lock.json pins the toolchain; use npm ci, not install
npm run lint    # tsc project typecheck
npm test        # vitest + jsdom component and API tests
npm run build

python -m pip install -e './sdk/python[test]'
pytest sdk/python

web/src/main.tsx only mounts the application; the components live in web/src/app.tsx so they can be rendered under test.

Without DATABASE_URL, NATS_URL, or OBJECT_STORE_ENDPOINT, the control plane uses in-memory data, an in-process broker, and local object files.

End-to-end tests

The end-to-end flows drive a live Docker stack: model gateway, MCP approval gate, organization management, egress policy, checkpoint resume, durable command replay, and worker recovery.

make e2e                      # build, start, seed, run every flow
make e2e FLOWS="mcp_flow"     # run a subset
make e2e-down                 # stop and remove the stack

make e2e adds an e2e Compose profile carrying an OpenAI-compatible mock Provider that also serves an MCP endpoint and a plain egress target. It stays on the control network, so Agent containers can reach it only through the policy proxy. test/e2e/seed.py creates the fixture organization, workspace, secret, and Provider, and is safe to re-run.

Two flows are disruptive by design and run last: durable_command_flow detaches a container from the runtime network, and recovery_flow restarts the control plane and the runtime worker.

Runtime sandbox

Agents may run system commands and child processes inside their container, and may write /workspace and /tmp. They cannot modify the host or access other session workspaces. System packages should be built into the Agent image; runtime dependencies may be placed inside /workspace when policy permits.

Gateway-mode model credentials never enter the Agent container. Explicit Manifest secret bindings are materialized in a per-session Docker volume, mounted read-only below /run/secrets/agent-platform, and removed during runtime cleanup.

Manifest network entries accept an exact host (api.example.com), an exact host and port (api.example.com:8443), or a subdomain wildcard (*.example.com). An empty list denies outbound HTTP and HTTPS. Model gateway and MCP traffic remains platform-mediated and is governed by its corresponding Manifest bindings.

Agents can upload checkpoints with the SDK. Starting a Session from a checkpoint creates a child Session and mounts the verified checkpoint read-only at /workspace/.agent-platform/checkpoint; the SDK exposes it through restored_checkpoint(). The console's Session checkpoint list provides a Resume as new Session action.

Docker isolation is not a VM-grade boundary against malicious kernel exploits. Use a dedicated runner VM for third-party images. See the threat model for the full boundary.

Open source and hosted service

The self-hosted core is licensed under Apache-2.0. The planned hosted service uses dedicated deployments per customer and charges for managed operations, runner compute, storage, backups, upgrades, and support—not feature locks in the open-source runtime.

Current boundary

The MCP registry, Manifest allow/approval policy, and streamable HTTP tools/call executor are implemented for all three transports, including optional Secret Store credentials. stdio servers run in a per-call container launched by the runtime worker, never by the Control Plane. OIDC single sign-on is implemented; SAML, SCIM, and per-organization identity providers are not. Runtime HTTP/HTTPS egress enforcement and checkpoint-based child Session resume are implemented. Several Control Plane instances can run over one PostgreSQL, NATS, and object store; see High availability. Agent Sessions run as Docker containers or Kubernetes Pods, with the same controls on both; see Kubernetes for how pause and checkpoint restore differ underneath. A Helm chart deploys the platform itself onto a cluster. Both binaries expose Prometheus metrics on a listener separate from the API, and export W3C-context traces over OTLP; the trace of a Session survives the PostgreSQL job queue, NATS, and the Agent container. See Metrics and tracing. Hosted tenant provisioning remains a future milestone.