AgentsMesh

AgentsMesh creates isolated AgentPods — each a containerized execution environment with a PTY terminal, Git worktree sandbox, and browser-accessible terminal view — managed via gRPC commands from the backend. Runners register with the backend using mTLS, receive lifecycle commands (spawn, terminate, execute), and maintain persistent connections for real-time state synchronization. Each Pod is a separate process boundary with its own filesystem sandbox and terminal session, enabling parallel multi-agent execution without cross-contamination.

Agents communicate asynchronously through Channels — named message queues managed by the backend and relayed to connected Runners via gRPC streaming. When an agent publishes a message to a Channel, the backend broadcasts it to all Runners with subscribed Pods, which deliver it to the agent's terminal or MCP interface. The Relay component handles session management and heartbeat-based connection health tracking, ensuring messages reach agents even if network conditions are unstable.

AgentsMesh abstracts agent type as a configurable parameter when spawning a Pod. Supported agents include Claude Code, Codex CLI, Gemini CLI, and Aider, each with different CLI interfaces and capabilities. When a Pod is created, the Runner installs the specified agent binary and configures it with environment variables (API keys, model selection). The agent runs in the Pod's terminal, and AgentsMesh orchestrates its lifecycle without imposing constraints on the agent's internal behavior. Custom agents can be supported by providing a startup script or binary.

The Runner maintains workspace state for each Pod, including current Git branch, commit history, uncommitted changes, and file modifications. Agents can query workspace state via MCP tools or REST API to understand the current code context. The Runner tracks Git state by running git commands (git status, git log, git diff) and caching results. This enables agents to make informed decisions about which files to edit, which branches to work on, and whether changes are ready for commit.

The Runner supports auto-update, where the backend can trigger a Runner to download and restart itself with a new binary version. The update process is designed for zero-downtime: existing Pods are allowed to complete, new Pod creation is paused during update, and the Runner restarts with the new binary. This enables platform updates without manual intervention or downtime for running agents.

The Relay component manages Runner-to-Backend communication with session persistence and heartbeat-based health checking. When a Runner connects, the Relay establishes a session and monitors heartbeat messages. If the connection drops, the Relay maintains session state and allows the Runner to reconnect without losing context. This enables Runners to survive temporary network outages without losing Pod state or pending commands.

Bindings allow one agent to observe and control another agent's terminal by establishing a read/write connection to a peer Pod's PTY. When Agent A creates a Binding to Agent B's Pod, Agent A gains terminal access to Agent B's session, enabling scenarios like one agent monitoring another's progress or taking over execution. Bindings are managed via MCP tools exposed by the Runner's MCP server, which translates tool invocations into gRPC commands to the backend's Runner Connection Manager.

The Runner exposes an MCP (Model Context Protocol) server that agents can invoke to autonomously spawn new Pods, create Bindings, and manage Channels without human intervention. Tools like create_pod, create_binding, and publish_to_channel are registered in the MCP server (runner/internal/mcp/http_server.go) and translated to gRPC commands sent to the backend. This enables agents to dynamically scale their own execution environment — e.g., an agent can spawn a new Pod for a subtask, bind to it for monitoring, and coordinate via Channels.

AgentsMesh integrates a Ticket Service that binds agents to work items (tickets) on a Kanban board. Agents can query tickets, update status, and receive webhook notifications when external systems (GitHub, GitLab) create or update PRs/MRs. The backend's ticket_service maintains ticket state and enforces agent-to-ticket bindings, while the web frontend displays a Kanban view. Webhooks from external systems trigger ticket creation or status updates, enabling agents to react to external events without polling.

Runners are self-hosted Go binaries that register with the backend using mTLS (mutual TLS with certificate-based authentication). During registration, the Runner provides its identity (hostname, capabilities) and establishes a persistent gRPC connection to the backend. The backend's Runner Connection Manager (backend/internal/service/runner/connection_manager.go) maintains a registry of active Runners and routes commands (spawn Pod, execute command) to the appropriate Runner. All communication is encrypted and authenticated via PKI, ensuring only authorized Runners can connect.

AgentsMesh does not proxy AI API calls. Users supply their own provider API keys (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY) directly to the Runner process environment. Agents running in Pods access these keys from the Runner's environment and make direct API calls to the provider (Claude, GPT, Gemini). The platform orchestrates agent lifecycle and communication but never handles AI inference traffic, meaning AI costs appear on the user's own provider account and there are no per-token usage caps imposed by AgentsMesh.

AgentsMesh synchronizes terminal state to the web frontend in real-time using WebSocket connections and an internal event bus. When a Pod's terminal produces output, the Runner emits an event (via gRPC) to the backend's event bus, which broadcasts it to all connected WebSocket clients viewing that Pod. The Relay component manages WebSocket session lifecycle and heartbeat, ensuring clients receive updates even if network conditions are unstable. Terminal state includes stdout, stderr, and PTY metadata (cursor position, window size).

Each Pod gets its own Git worktree sandbox created from a specified repository and branch. The Runner creates a worktree (git worktree add) in an isolated directory, ensuring each Pod has a separate working directory with independent Git state. When a Pod terminates, the worktree is automatically cleaned up (git worktree remove). This isolation prevents agents from interfering with each other's code changes and enables agents to work on different branches or commits simultaneously without conflicts.

AgentsMesh exposes a REST API (backend/internal/api/rest/v1/) for programmatic control of Pods, Tickets, and Channels. Clients can create Pods, query ticket status, publish to Channels, and manage agent lifecycle via HTTP endpoints. The REST API is a thin wrapper over the backend's internal services (runner, ticket, mesh), translating HTTP requests to service method calls. Authentication is handled via API keys or JWT tokens, and responses are JSON-encoded.