Skip to content
apomesh

Architecture overview

apomesh runs hierarchical, LLM-backed agents. You submit a root agent with a goal; apomesh decomposes the goal into sub-tasks, runs specialized worker agents (some in parallel), verifies their outputs, and synthesizes a result. Every step is recorded on a durable event log you can watch live, every tool call runs inside an OS-level sandbox, and a worker that disconnects mid-run resumes from a checkpoint instead of starting over.

Structurally, apomesh is a control plane plus a distributed execution plane — one coordinating brain and a fleet of stateless executors. This is the same family as Temporal, a Kubernetes scheduler with its kubelets, or Erlang/OTP across nodes: not microservices (there are no per-service databases), not a plain monolith (execution genuinely distributes).

The three doors

Section titled “The three doors”

A newcomer needs three planes before anything else makes sense:

Everything below layers on those three.

apomesh: control plane, distributed execution plane, and the shared state plane

The control plane

Section titled “The control plane”

One orchestrator daemon runs per deployment. It owns everything durable: the event log, provider and worker routing, supervision and failure handling, HITL adjudication, cost aggregation, and all persistence. It is the sole writer to the state plane (Postgres for durability, Redis for hot paths). Drivers reach it over gRPC, REST/SSE, or the desktop console’s IPC bridge — every transport delegates to the same substrate workflow, so the platform behaves identically regardless of how you called it. See The orchestrator.

The distributed execution plane

Section titled “The distributed execution plane”

Workers hold no session state. Each dials the orchestrator on startup, advertises its capabilities, and then receives dispatches over that connection. A worker runs the tool-use loop, calls LLM providers, and executes every tool inside a sandbox — one throwaway subprocess per tool call. Scale workers horizontally; the orchestrator stays a singleton. A single-binary mode runs a worker in-process for local development. See Workers.

The operator-facing planes

Section titled “The operator-facing planes”

On top of the control/execution split, apomesh exposes several planes an operator configures and inspects independently:

  • Agent-configuration plane — an agent is configured, not hard-coded. A manifest binds prompt fragments, tool selections, skills, a supervisor strategy, and defaults; operators edit it or start from a published, version-pinned shape.
  • Context plane — governs what each model call sees: a pure prompt transformer compiles the call, and token-runway compaction bounds working memory so long sessions don’t overrun the context window.
  • Memory plane — the tiers an agent remembers through: working, episodic, semantic (vector + keyword), and procedural project memory.
  • Credential plane — one sealed, per-tenant store for every secret. Secrets are never readable by an agent; the substrate resolves them server-side and injects them at the sandbox boundary.
  • Orchestration-strategy plane — a session runs under a coordinator, and the coordination shape is an addressable, versioned configuration you select at launch or lock onto a published agent.
  • Identity & authorization — who is calling, which tenant they resolve to, and what they are allowed to do.
  • Programmable agents & the function plane — when an agent’s logic is genuinely code rather than configuration, it ships as a container image and runs as a confined workload holding no substrate handles; every capability arrives over one typed, family-gated, metered channel.

Sessions and events are the spine

Section titled “Sessions and events are the spine”

Underneath all of it, the event log is the single source of truth. A session is reconstructed from its events, tailed live over the same log, and rehydrated from that log after a restart. That story — event-sourcing, reconstruction, resume, and deterministic recomposition on resume — is on Sessions, events & durability.

Where to next

Section titled “Where to next”