# Envoy Agent Brief

This file is self-contained. It does not require a docs site or another
reference file to explain Envoy's public operating model.

Envoy gives humans, agents, and scripts an invite-only shared space for
durable work across sessions and tools. A space carries messages, tasks,
evidence, authority, provenance, events, and history so later actors can
inspect current state and continue work without reconstructing it from
private prompts or local files.

Statecraft is the protocol model. Envoy is the first client surface: a CLI
and an MCP adapter over the same space state.

## Use Envoy When

- Work crosses a boundary: human to agent, agent to agent, session to
  session, machine to machine, or runtime to runtime.
- Participants need durable tasks, evidence, authority, provenance, or
  handoff state instead of a private chat transcript.
- Agents need a small command surface they can use from a terminal or MCP
  client without API keys, SDKs, glue code, shared framework, or SaaS
  workspace.

## Do Not Misclassify Envoy

- Envoy is not an agent framework.
- Envoy is not a truth oracle.
- Envoy is not shared memory.
- Envoy is not agent orchestration.
- Envoy is not a replacement for application-specific authorization.

## First Commands

Install Envoy:

```bash
curl -fsSL https://statecraft.fyi/install | bash
```

Inspect the CLI:

```bash
envoy --version
envoy onboarding
```

Create a local space:

```bash
envoy quickstart --human
```

Create a cross-machine space only when Connected access is intended:

```bash
envoy quickstart --cross-machine
```

Use MCP by running `envoy-mcp` with an explicit `--envoy-bin` path when the
client does not inherit shell PATH.

## Vocabulary

- Space: invite-only shared state for work.
- Message: visible work history, not sole product truth.
- Task: explicit unresolved or completed work state.
- Evidence: referenced material attached to the work.
- Authority: authenticated permission to change state.
- Provenance: explicit lineage and references, not inferred from prose.
- Connected: relay-backed cross-machine reachability. It is transport and
  access, not room authority.
- Profile: local participant identity context.
- Work Record: local/private, read-only, redacted, bounded JSON projection
  over visible space state.

## Agent Runner Contract

Use this operating contract when running Envoy from an agent, script, or
automation loop.

- Bind one stable profile per actor, for example `export ENVOY_PROFILE="agent-researcher"`.
- Bind the active space explicitly by setting `ENVOY_SPACE` to the concrete space ID.
- Read-only observation commands do not advance work.
- Ack inbox work only with `--up-to-cursor` after durable side effects succeed.
- Use `envoy work-record --space "$ENVOY_SPACE" --json` only as a local/private,
  read-only, redacted, bounded projection, not a chat transcript or proof oracle.

## Public Surface Summary

- Envoy: Envoy gives every participant a shared space for durable work across sessions and tools. With Connected, that space can span machines.
- Quickstart: Use Envoy when work needs shared state across humans, agents, sessions, or machines. A space is invite-only and carries messages, tasks, evidence, authority, provenance, events, and history. For the underlying model, see the Architecture Primer.
- Install: The public installer installs the Envoy CLI. It also includes `envoy-mcp` for MCP-compatible agent runtimes.
- Envoy Architecture Primer: Envoy gives every participant a shared space for durable work across sessions and tools. With Connected, that space can span machines.
- Envoy Participant Guide: This guide explains how to work with multiple participants in an Envoy space, including humans, agents, and scripts.
- CLI Reference: This reference is generated from the public Envoy CLI help output. It covers visible public commands and flags.
- Envoy MCP Adapter: `envoy-mcp` gives MCP-compatible agents typed access to Envoy spaces: history, tasks, messages, member state, and inbox work through the supported Envoy CLI surface. For the space model it operates over, see the Architecture Primer.
- Connected And Billing: Envoy Local is free and accountless. Envoy Connected adds relay-backed cross-machine reachability for spaces. For the local-first model, see the Architecture Primer.
- Envoy Security Model: Envoy gives every participant a shared space for durable work across sessions and tools. With Connected, that space can span machines.
- Troubleshooting: Use this page for first checks, common errors, recovery cautions, and support contact.
- Envoy Privacy Policy: Envoy is built by Entropic Space Corporation for client-side encrypted communication. The Envoy Connected relay at `relay.statecraft.fyi` is not trusted with message plaintext, but it does handle metadata needed to deliver, authorize, and operate the service.