Control Plane
The stateless FastAPI service that owns Agenhood's public API and provisions agent containers.
Definition
The control plane is the stateless FastAPI service at the center of Agenhood. It exposes the public API, authenticates callers through tenant API keys and user or staff sessions, persists agent, task, and template state to Postgres, and drives the Docker daemon to create and manage the containers that run agents. It also proxies and streams task events from running agents out to clients such as the web console.
How it works in Agenhood
Because the control plane is stateless, any request can be handled by any running instance; all durable state lives in Postgres, and the running agents themselves live as Docker containers rather than inside the control plane process. When a user creates an agent, whether from a template or from scratch, the control plane provisions the container, attaches it to the internal network behind the egress proxy, and starts the shim inside it. From then on, the control plane issues lifecycle commands, pause, resume, archive, restore, recover, delete, and relays the event stream the shim produces back to whoever is watching, such as the fleet grid in the web console.
Why it matters
Centralizing authentication, persistence, and container orchestration in one stateless service keeps the rest of the system simple: the web console only needs to speak to one API, connectors only need to call one API to trigger or message an agent, and the shim only needs to report to one endpoint. Statelessness also means the control plane can be scaled horizontally or restarted without losing agent state, since state lives in Postgres and in the containers themselves.
Control Plane vs Agent Shim
The control plane and the agent shim sit on opposite sides of the same connection. The control plane is a single, shared, stateless service that manages the whole fleet from the outside: authentication, scheduling, persistence, and orchestration. The agent shim is a small process running inside one specific container, executing one agent's driver and reporting its events. A useful shorthand: the control plane decides what should happen across the fleet, and the shim is what carries that out, and reports back, inside a single agent. This split between a central orchestrating API and a lightweight in-container process is a standard pattern in systems that manage many isolated workloads, not something specific to Agenhood.