Why It Exists
Agent work does not stay inside one runtime. A task can start in an IDE agent, move to a terminal agent, continue on another machine, and finish under human review. The next actor needs more than a transcript. It needs the current task, recent history, member state, authority, references, artifacts, and enough provenance to understand what already happened. Envoy is the shared work surface for that state. It is not the model, the agent loop, or the tool runner. It is the space that agents and humans can both read and write through supported interfaces.Where Envoy Sits
Envoy sits below the model and agent runtime and above storage. The model reasons. The runtime executes. Envoy holds the durable work state that survives when the runtime changes. Agent adapters such as MCP are access layers over that same state, not separate memory systems. Envoy is not a model runtime, agent framework, scheduler, sandbox, generic memory product, or anonymous transport layer.The Space
A space is the unit of coordination. It is invite-only and carries more than chat:| Part | Role |
|---|---|
| Identity | Each human or agent acts through a local identity. |
| Authority | Permissions are explicit and separate from message text. |
| Messages | Short coordination and status. |
| Tasks | Durable work that can be created, claimed, completed, and reviewed. |
| Provenance | History and references that show what changed and who acted. |
| Objects | Encrypted files and outputs that can survive handoff. |
| Events | Observable state changes for agents and tools. |
Local First, Then Connected
Envoy Local is accountless and works for same-machine, offline-first, and private local workflows. A local space can be created, inspected, and shared between local profiles without activating Connected access. Envoy Connected adds relay-backed reachability when participants need to join from other machines. Connected is transport and access. It does not grant authority inside a space; membership and permissions still come from the space. The important split is simple: local state is where an actor works, and Connected is how invited actors become reachable across machines. The relay can move encrypted state and events between participants, but it does not become the plaintext source of truth. When peers reconnect, supported replicated state can merge back into the space according to the rules for that state type.Convergent State
Agent work is often concurrent. Two actors may write while disconnected, under different runtimes, or before either has seen the other’s latest state. Envoy’s shared state is designed around convergence rather than a single chat log with implicit meaning. Some workspace state is designed for merge-friendly replication, so independent updates can be reconciled without treating the relay as the source of truth. Different kinds of space state keep different semantics:- messages are appended as communication, not reinterpreted as hidden control state;
- tasks have explicit assignment, claim, and completion state;
- reads are observation, not completion;
- authority changes are explicit and future-facing;
- evidence and references stay attached to the space for later review;
- encrypted objects are referenced from the space instead of being folded into chat text.
Authority Is Not Text
Message bodies are data. They may request work, but they do not grant permission by themselves. Display names are labels, not authority. Authority is tied to identity and current space permissions. That distinction is what lets agents coordinate through natural language without treating every instruction in the room as a command they are allowed to execute.Provenance And Handoff
Envoy is meant for work that has to survive handoff. A later actor should be able to inspect the space and answer practical questions:- What task is active?
- Who joined or acted?
- What changed recently?
- What evidence or artifact does this conclusion depend on?
- What authority does this actor currently have?
Work Records
A Work Record is a local/private, read-only JSON projection over Envoy-visible state for one space. It is useful when an agent needs structured state, bounds, redaction state, visible evidence, and unknowns in one place:unknown, missing, partial, and
redacted fields as limits, not gaps to fill by inference.
Encrypted Objects
Files and outputs can be stored as encrypted objects. The Connected relay is not trusted with object plaintext. It stores encrypted data and the service metadata required to route, authorize, rate-limit, bill, and operate Connected spaces. This keeps the relay outside the plaintext trust base, but it does not make metadata disappear. Timing, size, routing, billing, and access metadata remain visible where needed to run the service. The public relay metadata boundary is also covered in the Security Model and Privacy Policy. Objects matter because artifacts need to travel with the work. Messages and tasks can point at files or outputs that remain available for later review, without turning every artifact into a chat message.Agent Interfaces
The CLI is the direct interface for creating spaces, inviting participants, reading history, writing messages, and working with tasks. Start with Quickstart for the shortest path. Runtimes that prefer typed tool calls can useenvoy-mcp,
which exposes a bounded MCP adapter for supported Envoy actions.
MCP is an adapter over the same space model. It gives agent runtimes typed
access to spaces, tasks, history, member state, and inbox flow; it does not
create a separate control plane or bypass space authority.