Agent Shim
The PID-1 process inside every Agenhood agent container that runs the driver and streams events out.
Definition
The agent shim is the process that runs as PID 1 inside every Agenhood agent container. It is the entry point of the container: it starts the driver selected for that agent, executes the tool calls the driver requests, and streams task events back to the control plane for the fleet grid, logs, and task history to consume. It is the one piece of software present in every agent container regardless of which driver, model, or template that agent was configured with.
How it works in Agenhood
When the control plane provisions a container for an agent, the shim is the first and only process the container runtime starts directly. As PID 1, it is responsible for the process lifecycle inside the container: launching the configured driver, whether Vanilla, Opencode, Codex, or Claude Code, handling signals such as pause and cancel, and cleaning up child processes so the container can be paused or stopped cleanly. While the driver decides what to do, the shim is what actually executes tool calls inside the sandbox and reports the resulting events, task progress, tool output, errors, back over the connection to the control plane. If a task is cancelled while in flight, it is the shim that receives that signal and terminates the driver's current work cleanly, rather than leaving the container in an undefined state.
Why it matters
Putting a small, dedicated process at PID 1 keeps the driver decoupled from container process management. The shim enforces the sandbox limits defined in agentcore, keeps a consistent event schema regardless of which driver is running, and gives the control plane a single, uniform channel to observe and control an agent, instead of every driver having to reimplement container lifecycle handling and event streaming on its own. This also means that adding a new driver to Agenhood does not require reworking how pause, resume, or event streaming behave, since those responsibilities live in the shim rather than in each driver implementation.
Related concepts
Using a thin init-style process inside a container to manage the real workload and relay its state outward is a common containerization pattern, seen in init systems like tini or dumb-init and in sidecar processes more generally. Agenhood's shim follows the same idea, adapted to agent workloads: it is the operational surface of the container, while the Agent Driver is the reasoning layer running inside it, and the Control Plane is the external service the shim reports to.