README.md
July 23, 2026 · View on GitHub
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 Ensembles 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 Agents, Schedules, and memory |
Platform Infrastructure
| Model Endpoints for Agents | Declare models as CRDs — GGUF or HuggingFace weights are downloaded, an inference server (llama.cpp, vLLM, TGI, or custom) is deployed, and OpenAI-compatible endpoints are 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 |
| Policy & Governance | Cluster-wide SympoziumPolicy CRD — tool gating (allow/deny/ask), sandbox requirements, network egress rules, and image-registry allowlists, enforced by an admission webhook |
| Serving Mode | Run an agent as a long-lived, OpenAI-compatible + MCP HTTP endpoint instead of a one-shot Job — agents as services |
| Observability & Cost | OpenTelemetry traces and metrics, Prometheus endpoints, per-run trace IDs, and token usage with estimated cost on every AgentRun |
| Any AI Provider | OpenAI, Anthropic, AWS Bedrock, Azure, Ollama, or any OpenAI-compatible endpoint (Groq, Mistral, DeepSeek, OpenRouter, vLLM, LM Studio, …) — 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