Agent Circus: Open-Protocol Runtime and Configuration for AI Coding Agents
AI agents often need access to tools, credentials, and local or remote network resources, which creates risks for the systems they interact with. Agent Circus provides a small runtime and uniform configuration layer for running existing agent harnesses in containers.
Table of Contents
AI Agent Runtimes Need Structure
Agent Circus is aimed at developers and teams that want to use multiple coding agents across projects. It supports popular agent harnesses such as OpenAI Codex, Anthropic Claude Code, Mistral Vibe CLI, and OpenCode. Each harness brings its own configuration file formats, tools, credential handling, and project access mechanisms: when working on projects, agents access Git configuration, SSH keys and known hosts, environment variables, certificates, etc.
Configuring each agent harness individually does not scale well to a multi-agent workflow. If every harness gets configured independently, the same project knowledge is repeated in several formats. Shared resources such as MCP servers can be duplicated even though the project should provide them only once. The result is a setup that works, but is hard to inspect and harder to reproduce.
In addition to the configuration challenges, AI agents may access parts of your system that you actually want to hide from them. At the same time, some projects require access to selected private information or mechanisms. To tackle these security concerns, agent harnesses need to run in sandboxed environments such as VMs or containers.
The Goal: One Runtime And One Configuration Model
A project should have a simple configuration file that describes project-specific settings once. Agent Circus can then combine base harness configuration stored on the host with those project settings and derive the native configuration files expected by each harness.
The second goal is a unified runtime. Agent Circus provides a common runtime and configuration model for existing agent harnesses. It builds on Docker Compose to run each agent in its own container, giving it access only to the project and host resources it really needs to perform its work.
The Agent Circus Execution Model
The architecture of Agent Circus is centered on open protocols or quasi-standards to avoid potential vendor lock-in, as shown in Figure 1.
Through the Agent Client Protocol (ACP), editors such as Emacs via agent-shell or other clients can connect to a selected harness. The Model Context Protocol (MCP) can connect that harness to explicitly configured tools and data sources. Higher-level workflows can be implemented using Agent Skills in a single location. The point is not to hard-code one vendor’s runtime configuration, but to compose agents, tools, and editor integration through a simple and unified configuration interface.
Figure 1: Open protocol relationships used by Agent Circus
Agent Circus uses generated Docker Compose environments as the substrate. The agent-circus command is a higher-level interface to those compose environments and their generated overlays. Those overlays are derived from the project’s Agent Circus configuration and from the selected harness configuration.
The provided subcommands are similar to Docker Compose subcommands, and the basic workflow remains intentionally small:
agent-circus build
agent-circus exec claude-code -- claude
agent-circus exec codex -- codex
The build step derives the compose environment from the project configuration. The exec commands run a command inside the selected agent harness service. If the required container images have not been built yet, exec builds them implicitly.
To expose agents through their ACP surface, the corresponding ACP adapters have to be invoked:
agent-circus build
agent-circus exec claude-code -- claude-agent-acp
agent-circus exec codex -- codex-acp
The project configuration is the shared model from which Agent Circus can generate the configuration formats expected by each harness. For each project, Agent Circus reads this file from .agent-circus/config.toml; if the file is missing, it still starts with safe defaults.
env_passthrough = ["re:^LG_"]
[git]
config_path = "~/.gitconfig"
signing_key_path = "~/.ssh/id_ed25519.pub"
worktree_mirror = true
[ssh]
config_path = "/home/user/.ssh/config"
known_hosts_path = "/home/user/.ssh/known_hosts"
[hosts]
patterns = [
"*.acme.local",
"acme-vm",
]
[[additional_dirs]]
path = "/home/user/git/zeitfenster"
readonly = true
This example shows the intended level of abstraction. The project says which environment variables may pass through, which Git and SSH configuration should be visible, which host patterns should resolve inside the agents’ containers, and which additional directory should be visible read-only. The same configuration can also define hooks, for example to install project-specific tools into the agent containers. The generated harness configuration can then use this shared information without explicit configuration.
Shared services follow the same idea. MCP sidecars and similar resources belong to the project compose environment once, and the harnesses that need them can use that shared service instead of defining their own duplicate copy.
From Workstation State To Project State
The immediate benefit is that project-specific configuration has one place to live. The developer can switch between supported harnesses without manually translating the same access rules into several unrelated configuration formats.
The runtime boundary also becomes easier to reason about. Files, Git configuration, SSH configuration, reachable hosts, additional directories, environment variables, certificates, tools, and MCP servers are part of the project setup instead of unexamined workstation state. This does not make containers a perfect security boundary. It is a runtime and configuration model that makes access more explicit and reproducible; stronger isolation may still require additional controls such as dedicated VMs or fine-grained security contexts.
As coding agents become normal development tools, the important question is not only which agent to use, but also how that agent is connected to the project, the editor, and the tools around it.
Agent Circus has been my daily driver for months, but I still consider it an early-stage project. The core idea is already implemented and the project is available under the permissive MIT license on Codeberg and GitHub.
Related Work
There is already substantial related work around sandboxes and isolated runtime environments for coding agents, so this is intentionally not a complete survey. A field guide to sandboxes for AI provides a comprehensive overview by comparing approaches by boundary, policy, and lifecycle, and discusses containers, gVisor, microVMs, and runtime sandboxes. Coding Agent VMs on NixOS with microvm.nix shows how to run agents in disposable NixOS microVMs so that only explicitly shared state survives. Projects such as microsandbox and Clawk package similar ideas into local-first or disposable agent machines with microVM isolation, controlled network access, and host-side secret handling. agentcage focuses on defense in depth around egress control by placing the agent on an internal network and routing outbound traffic through an inspecting proxy.
