README
¶
Agents don't need better prompts. They need shared situational awareness.
Sympozium is a coordination layer for multi-agent AI systems on Kubernetes —
selective permeability, structured handoffs, and shared memory.
Every agent is a Pod. Every policy is a CRD. Every execution is a Job.
From the creator of k8sgpt and llmfit
This project is under active development. API's will change, things will break. Be brave.
Full documentation: deploy.sympozium.ai/docs
The problem this solves: The Sticky-Note Problem — why message-passing between agents breaks down, and what to build instead.
The Problem
Most multi-agent systems communicate through messages — strings of tokens that one agent serialises and another deserialises. A detection agent spots a threat while a containment agent takes the server offline for maintenance. Neither knows what the other is doing. The breach is missed.
This is the sticky-note problem: agents passing notes instead of sharing a situational board. Kubernetes solved this for containers with a shared control plane. Agents need the same thing — not better message-passing, but shared coordination infrastructure.
Sympozium provides that infrastructure: a synthetic membrane that wraps agent teams with selective permeability, shared memory, structured handoffs, and circuit breakers — all expressed as Kubernetes-native CRDs.
Quick Install (macOS / Linux)
Homebrew:
brew tap sympozium-ai/sympozium
brew install sympozium
Shell installer:
curl -fsSL https://deploy.sympozium.ai/install.sh | sh
Then deploy to your cluster and activate your first agents:
sympozium install # deploys CRDs, controllers, and built-in Ensembles
sympozium # launch the TUI — go to Personas tab, press Enter to onboard
sympozium serve # open the web dashboard (port-forwards to the in-cluster UI)
Advanced: Helm Chart
Prerequisites: cert-manager (for webhook TLS):
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.17.1/cert-manager.yaml
Sympozium can be installed as two charts: sympozium-crds (the CRDs, so they can be upgraded) and sympozium (the control plane). Install the CRDs first, then the control plane:
helm repo add sympozium https://deploy.sympozium.ai/charts
helm repo update
helm upgrade --install sympozium-crds sympozium/sympozium-crds \
--namespace sympozium-system --create-namespace
helm upgrade --install sympozium sympozium/sympozium \
--namespace sympozium-system \
--skip-crds --set createNamespace=false
--skip-crdson the second command assumes you installedsympozium-crdsfirst. If you skip the CRDs chart, drop--skip-crdsso the bundled CRDs in thesympoziumchart are applied instead.
See charts/sympozium/values.yaml for configuration options, or the Helm Chart docs for the full guide.
Why Sympozium?
Containers needed orchestration. Agents need coordination.
Sympozium is a Kubernetes-native coordination layer for multi-agent AI systems. It solves the same problem Kubernetes solved for containers — but for agents that need to share context, hand off tasks, and maintain shared situational awareness.
And that is the whole product. Sympozium decides what agents do. Where compute happens is the job of a capability layer — llmfit-dra, a Kubernetes DRA driver that places models by physics through the stock scheduler. How tokens move is the serving engine's job (vLLM, SGLang, llama.cpp). When an agent needs a model, Sympozium claims one the way an application claims a PersistentVolume — it never decides where it runs. See Positioning for the boundary and what's deliberately out of scope.
Agent Coordination
| Synthetic Membrane | Selective permeability for agent teams — control what agents share via trust groups, visibility tags, and field-level gating. Read the paper |
| Agent Workflows | Delegation, sequential pipelines, supervision, and stimulus triggers between personas — visualised on an interactive canvas |
| Shared Workflow Memory | Pack-level SQLite memory pool for cross-persona knowledge sharing with per-persona access control and time decay |
| Ensembles | Helm-like bundles for AI agent teams — activate a pack and the controller stamps out instances, schedules, and memory |
Platform Infrastructure
| Model Endpoints for Agents | Declare GGUF models as CRDs — weights are downloaded, llama-server deployed, and OpenAI-compatible endpoints exposed for your personas. No API keys required. Placement is claimed, not decided here: with llmfit-dra installed, the stock scheduler places models by physics |
| Skill Sidecars | Every skill runs in its own sidecar with ephemeral least-privilege RBAC, garbage-collected on completion |
| Multi-Channel | Telegram, Slack, Discord, WhatsApp — each channel is a dedicated Deployment backed by NATS JetStream |
| Persistent Memory | SQLite + FTS5 on a PersistentVolume — memories survive across ephemeral pod runs |
| Scheduled Tasks | Cron-based recurring agent runs for periodic workflows, data syncs, and automated checks |
| Agent Sandbox | Kernel-level isolation via kubernetes-sigs/agent-sandbox — gVisor or Kata with warm pools for instant starts |
| MCP Servers | External tool providers via Model Context Protocol with auto-discovery and allow/deny filtering |
| TUI & Web UI | Terminal and browser dashboards with live workflow canvas, or skip the UI entirely with Helm and kubectl |
| Any AI Provider | OpenAI, Anthropic, Azure, Ollama, or any compatible endpoint — no vendor lock-in |
Documentation
Development
make test # run tests
make test-system # run envtest system tests (no cluster needed)
make lint # run linter
make manifests # generate CRD manifests
make run # run controller locally (needs kubeconfig)
License
MIT License
Directories
¶
| Path | Synopsis |
|---|---|
|
api
|
|
|
v1alpha1
Package v1alpha1 contains API Schema definitions for the sympozium.ai v1alpha1 API group.
|
Package v1alpha1 contains API Schema definitions for the sympozium.ai v1alpha1 API group. |
|
channels
|
|
|
discord
command
Package main is the entry point for the Discord channel pod.
|
Package main is the entry point for the Discord channel pod. |
|
slack
command
Package main is the entry point for the Slack channel pod.
|
Package main is the entry point for the Slack channel pod. |
|
telegram
command
Package main is the entry point for the Telegram channel pod.
|
Package main is the entry point for the Telegram channel pod. |
|
whatsapp
command
Package main is the entry point for the WhatsApp channel pod.
|
Package main is the entry point for the WhatsApp channel pod. |
|
cmd
|
|
|
agent-runner
command
|
|
|
apiserver
command
Package main is the entry point for the Sympozium API server.
|
Package main is the entry point for the Sympozium API server. |
|
controller
command
Package main is the entry point for the Sympozium controller manager.
|
Package main is the entry point for the Sympozium controller manager. |
|
ipc-bridge
command
Package main is the entry point for the Sympozium IPC bridge sidecar.
|
Package main is the entry point for the Sympozium IPC bridge sidecar. |
|
mcp-bridge
command
Package main is the entry point for the Sympozium MCP bridge sidecar.
|
Package main is the entry point for the Sympozium MCP bridge sidecar. |
|
memory-server
command
memory-server runs as a standalone Deployment per Agent.
|
memory-server runs as a standalone Deployment per Agent. |
|
node-probe
command
Package main is the entry point for the Sympozium node-probe DaemonSet.
|
Package main is the entry point for the Sympozium node-probe DaemonSet. |
|
sympozium
command
Package main provides the sympozium CLI tool for managing Sympozium resources.
|
Package main provides the sympozium CLI tool for managing Sympozium resources. |
|
web-proxy
command
Package main is the entry point for the web-proxy that exposes Sympozium agents as OpenAI-compatible and MCP HTTP endpoints.
|
Package main is the entry point for the web-proxy that exposes Sympozium agents as OpenAI-compatible and MCP HTTP endpoints. |
|
webhook
command
Package main is the entry point for the Sympozium admission webhook server.
|
Package main is the entry point for the Sympozium admission webhook server. |
|
internal
|
|
|
apiserver
Package apiserver provides the HTTP + WebSocket API server for Sympozium.
|
Package apiserver provides the HTTP + WebSocket API server for Sympozium. |
|
channel
Package channel provides base types and interfaces for Sympozium channel implementations.
|
Package channel provides base types and interfaces for Sympozium channel implementations. |
|
controller
Package controller contains the reconciliation logic for Sympozium CRDs.
|
Package controller contains the reconciliation logic for Sympozium CRDs. |
|
dra
Package dra detects, at runtime, whether the cluster can do claim-based model placement: Kubernetes DRA (resource.k8s.io/v1, GA in 1.34) plus the llmfit.ai ModelClaim CRD served by llmfit-dra.
|
Package dra detects, at runtime, whether the cluster can do claim-based model placement: Kubernetes DRA (resource.k8s.io/v1, GA in 1.34) plus the llmfit.ai ModelClaim CRD served by llmfit-dra. |
|
eventbus
Package eventbus provides OTel trace context propagation over NATS headers.
|
Package eventbus provides OTel trace context propagation over NATS headers. |
|
helmchart
Package helmchart provides helpers for loading the embedded Sympozium Helm chart.
|
Package helmchart provides helpers for loading the embedded Sympozium Helm chart. |
|
ipc
Package ipc implements the IPC bridge sidecar that mediates communication between ephemeral agent pods and the durable Sympozium control plane.
|
Package ipc implements the IPC bridge sidecar that mediates communication between ephemeral agent pods and the durable Sympozium control plane. |
|
llmprovider
Package llmprovider is the canonical taxonomy of LLM provider identifiers.
|
Package llmprovider is the canonical taxonomy of LLM provider identifiers. |
|
mcpbridge
Package mcpbridge implements the MCP bridge sidecar that translates between file-based IPC and remote MCP servers via JSON-RPC 2.0 Streamable HTTP.
|
Package mcpbridge implements the MCP bridge sidecar that translates between file-based IPC and remote MCP servers via JSON-RPC 2.0 Streamable HTTP. |
|
orchestrator
Package orchestrator handles the construction of Kubernetes Jobs/Pods for AgentRun executions and manages sub-agent spawning.
|
Package orchestrator handles the construction of Kubernetes Jobs/Pods for AgentRun executions and manages sub-agent spawning. |
|
pricing
Package pricing computes dollar cost estimates for AgentRuns from token usage and a per-model price table.
|
Package pricing computes dollar cost estimates for AgentRuns from token usage and a per-model price table. |
|
session
Package session provides session persistence and transcript storage backed by PostgreSQL with pgvector for memory embeddings.
|
Package session provides session persistence and transcript storage backed by PostgreSQL with pgvector for memory embeddings. |
|
toolpolicy
Package toolpolicy resolves ToolPolicy from Ensemble AgentConfig specs.
|
Package toolpolicy resolves ToolPolicy from Ensemble AgentConfig specs. |
|
webhook
Package webhook provides validating and mutating admission webhooks for Sympozium.
|
Package webhook provides validating and mutating admission webhooks for Sympozium. |
|
webproxy
Package webproxy provides the HTTP proxy that exposes Sympozium agents as OpenAI-compatible and MCP endpoints.
|
Package webproxy provides the HTTP proxy that exposes Sympozium agents as OpenAI-compatible and MCP endpoints. |
|
pkg
|
|
|
sidecartools
Package sidecartools holds helpers shared between the controller (which writes the native sidecar-tools manifest and the IPC routing target) and the agent-runner (which consumes the manifest and dispatches exec requests).
|
Package sidecartools holds helpers shared between the controller (which writes the native sidecar-tools manifest and the IPC routing target) and the agent-runner (which consumes the manifest and dispatches exec requests). |
|
telemetry
Package telemetry provides shared OpenTelemetry initialization for all Sympozium components.
|
Package telemetry provides shared OpenTelemetry initialization for all Sympozium components. |