# Vyre: the agentic command center for AI-native teams

Our mission is to help every professional services team become AI-native.

In an AI-native team, people set the direction and make the calls, and agents do the work: they draft, track, follow up and keep every job moving. Vyre gives both one place to work together, on servers the team owns, where anything that leaves the team waits for a person's yes.

This file is the front door to how Vyre is built. Read the next two sections, then follow the table of contents to the page you need. If you are an AI agent, start at the last section.

## What Vyre is

People and agents share one set of chats, records, tasks, files and automations (Flows). A server the team owns holds all of it. Where the outcome has to be exact, such as who may see a record, what a Flow does or what got sent, declared rules decide and a model does not. Anything that leaves the server, whether an email, a payment, a deletion or a published page, waits for a person to approve the exact words. A model sees a placeholder where a secret would be.

Three ideas shape the code: a small trusted core, a person who decides and proves it, and secrets that stay out of the model's reach. The [architecture overview](docs/architecture/overview.md) explains each. The core is `kernel/`. It decides who may do what, writes the event log and seals secrets, with almost no dependencies. Every feature is a module around it, and no module can invent a new kind of permission.

One program, `vyred`, runs on each machine: a Linux server, a Mac, or a computer that joins a server. The Vyre app, the `vyre` command line and outside AI tools all call it.

## What makes Vyre strong

- **Records you shape.** Define as many objects as the business has, and link them in whatever web the business needs. A token can reach through several links (`{job.client.phone}`). Give each object list, board, calendar, page or dashboard views. Mark a field sealed and no model ever reads it. See [Records](docs/architecture/features/records.md).
- **Flows that run the same way every time.** A trigger (a person, a schedule, a record change or stage, a form, a watcher), then steps: find or create, update, wait for a date or an event, ask a person, assign, send, hand to an agent. Approvals, a run page with a timeline, and failure paths are in the engine. See [Flows](docs/architecture/features/flows.md).
- **One group chat across providers.** Claude, Codex, Grok and others, through the sign-ins and keys you add, answer in the same chat. Give agents different jobs: a team that does the work, one model that reviews, one that plans. See [Sessions and models](docs/architecture/features/sessions-and-models.md) and [MCP and the Engineer](docs/architecture/features/mcp-and-engineer.md).
- **Playbooks.** A project template holds stages, the tasks in each stage, and who does each task, whether a person or an agent. A business with several kinds of work runs each as its own Playbook and its own Flows, side by side, over shared records. See [Tasks, Needs you and Playbooks](docs/architecture/features/tasks-and-needs-you.md).
- **A vault for people and agents.** An agent uses a credential without seeing it. Each member has a vault of their own. Revealing a value or sending with it takes a person's yes. See [Vault](docs/architecture/features/vault.md).
- **Sites.** An agent builds a site, previews it at a private address and puts it live on one yes, on your own domain with the DNS record shown. Every version stays in the history. See [Sites and publishing](docs/architecture/features/sites-and-publishing.md).
- **Documents.** Vyre fills your own Word templates from a record and the records linked to it. A model never rewrites the document. See [Documents and signing](docs/architecture/features/documents-and-signing.md).
- **Signing.** Send a document for signature from a record. The signer needs no account. The signed copy files back on the record, and the signature can start the next Flow. Same page as Documents.

Anything the business needs beyond this, a custom module or an Integration adds. A module is a folder with a manifest and an entry file, and an agent can write one on your own server. See [How to extend Vyre](#how-to-extend-vyre).

## The system on one page

```mermaid
flowchart TB
  subgraph Surfaces["Surfaces"]
    APP["Vyre app: web, iPhone, Android, Mac, Windows"]
    CLI["vyre command line"]
    OUT["Outside AI tools over MCP"]
  end
  RELAY["Relay: encrypted path to a server with no open port"]
  subgraph Daemon["vyred, one daemon per machine"]
    DOOR["Door: who is calling, what may they reach"]
    subgraph Modules["Modules in core/ and your own"]
      WORK["Work: chats, tasks, records, flows, agents, documents"]
      KEEP["Keep: files, vault, memory"]
      OUTW["Outward: gate, publish, connections"]
      RUN["Run: sessions, switchboard, providers"]
    end
    subgraph Kernel["kernel/"]
      ID["Identity and devices"]
      GR["Grants and roles"]
      EV["Event log"]
      FL["Flow runner"]
      SE["Sealing"]
    end
  end
  LOCAL["A person's own computer: sandboxed sessions, computer use"]
  WORLD["Outside services: mail, calendar, Drive, Dropbox, payments, DNS"]
  APP & CLI & OUT --> DOOR
  APP -. "away from home" .-> RELAY --> DOOR
  DOOR --> Modules --> Kernel
  RUN <--> LOCAL
  OUTW -- "only after a person's yes" --> WORLD
```

A call starts at the door, which works out who is calling (a person on a paired device, an agent acting for a person, a module, an outside tool) and builds that caller's chain. The module's tool runs. Every read or write of a record, grant or event goes through the kernel's gateway, which asks `authorize` for the action under that chain. A tool marked outward is held at the Gate until a person approves. [The Vyre map, section 13](docs/architecture/map.md#13-one-request-end-to-end) walks one request from start to finish.

## Table of contents

### Start here

| Page | What it gives you |
| --- | --- |
| [Architecture overview](docs/architecture/overview.md) | A ten-minute picture: layers, how a call flows, how an agent's turn runs, where data lives, the Gate. |
| [The Vyre map](docs/architecture/map.md) | A 30-minute tour that lists every top-level folder, kernel folder and module. A test keeps it current. |
| [Architecture index](docs/architecture/index.md) | The short version and the decision records. |
| [Specification](docs/architecture/spec.md) | The source of truth for detail. |
| [Map your business onto Vyre](docs/for-agents/MAP-YOUR-BUSINESS.md) | A method an AI agent follows to turn a business into members, records, Flows, agents and Gate rules. |
| [Start here, for AI agents](docs/for-agents/START-HERE.md) | The entry point for an agent: what Vyre is, a map of everything, the questions to ask, the mapping method and how to get started. [The two-line prompt](docs/for-agents/PROMPT.md) sends an agent there. |
| [Roadmap](roadmap/README.md) | What is next, by version, with a plan for each. |

### One page per feature

Each feature page has the same headings: What it is, What a person sees, How it works, Where the code lives, How agents use it, Extend it, Related.

| Feature | Page | Main code |
| --- | --- | --- |
| Spaces and members: roles, member reach, invites, project seats | [spaces-and-members](docs/architecture/features/spaces-and-members.md) | `core/spaces`, `core/roles`, `kernel/grants` |
| Identity and devices: pairing, sign in by name | [identity-and-devices](docs/architecture/features/identity-and-devices.md) | `kernel/identity`, `core/signin`, `core/names` |
| Kernel: grants, authorize, event log, golden files | [kernel](docs/architecture/features/kernel.md) | `kernel/` |
| Chats with people and agents, @ and # | [chats](docs/architecture/features/chats.md) | `core/comms`, `core/mentions`, `core/switchboard` |
| Agents: AGENTS.md, memory and lessons, waking on tasks, stuck | [agents](docs/architecture/features/agents.md) | `core/agents`, `core/daemon/agent-wake.js` |
| Sessions and models: switchboard, provider CLIs, own computer or server, accounts | [sessions-and-models](docs/architecture/features/sessions-and-models.md) | `core/sessions`, `core/switchboard`, `core/providers` |
| Records: objects, fields, tokens, links, tags, views, import and export | [records](docs/architecture/features/records.md) | `records/`, `core/records-tools` |
| Flows: triggers, steps, templates and dates, approvals, run page | [flows](docs/architecture/features/flows.md) | `kernel/flows`, `core/flows` |
| Tasks, Needs you and Playbooks | [tasks-and-needs-you](docs/architecture/features/tasks-and-needs-you.md) | `kernel/tasks`, `core/approvals`, `core/work` |
| The Gate: held outward actions | [gate](docs/architecture/features/gate.md) | `core/gate`, `lib/one-yes.js` |
| Vault: groups, items, member vaults, leases | [vault](docs/architecture/features/vault.md) | `core/vault`, `lib/vault-kinds` |
| Files: Drive, Dropbox | [files](docs/architecture/features/files.md) | `core/files` |
| Documents and signing | [documents-and-signing](docs/architecture/features/documents-and-signing.md) | `core/documents`, `core/appmods` |
| Sites and publishing | [sites-and-publishing](docs/architecture/features/sites-and-publishing.md) | `core/publish` |
| MCP and the Engineer, agent teams | [mcp-and-engineer](docs/architecture/features/mcp-and-engineer.md) | `core/mcp`, `core/team`, `harness/` |
| Relay and networking | [relay-and-networking](docs/architecture/features/relay-and-networking.md) | `relay/`, `core/relay`, `core/network`, `wink/` |
| Apps: Mac, Windows, phone, web | [apps](docs/architecture/features/apps.md) | `apps/app`, `local/capsule` |

### Concepts and reference

- [The box and the Mac](docs/concepts/box-and-mac.md), [Network](docs/concepts/network.md), [Presence](docs/concepts/presence.md), [The security floor](docs/concepts/floor.md), [Modules](docs/concepts/modules.md).
- [Boundaries](docs/architecture/boundaries.md) and [Performance](docs/architecture/performance.md).
- [Tools](docs/reference/tools.md), [Events](docs/reference/events.md), [Modules](docs/reference/modules.md), [Files layout](docs/reference/files-layout.md), [CLI](docs/reference/cli.md).
- [Decision records](docs/adr/), which say why each hard choice went the way it did.
- [Roadmap](docs/roadmap.md), [Changelog](CHANGELOG.md), [Release notes for 0.5.0](release/notes/0.5.0.md).

## How to extend Vyre

When a business needs something that is not built in, add it as a module. A module is a folder with a `module.json` and an entry file. It registers tools, emits events and can add Flow steps, and the loader in `core/modules` checks it against the same contract as the built-in ones. It runs under the supervisor in `kernel/modules`, so it gets the kernel's checks and cannot add a new kind of permission.

- The contract: [module contract](docs/build/module-contract.md), [writing a module](docs/build/writing-a-module.md), [first module](docs/build/first-module.md), [the module list](docs/MODULES.md). Kernel types are in `kernel/contracts/`.
- Integrations with popular applications are planned (roadmap item R052-01). An Integration wraps an outside app's API and ships its own Flow steps, triggers, connection and agent tools.
- An agent can build a module or an Integration for the business on the business's own server. [The agent brief](docs/build/AGENT-BRIEF.md) is the place to start.

## Repository layout

[The map, section 14](docs/architecture/map.md#14-the-repository-top-to-bottom) lists every folder and a test keeps the list true. The ones you open first:

```
kernel/    the trusted core: identity, grants, event log, Flow runner, sealing
core/      services that run inside vyred, one folder each, each with a module.json
records/   the built-in record types and Kits
lib/       helpers shared across modules
harness/   the Claude Code plugin and the vyre MCP server
apps/app/  the Vyre app (Expo): web, iPhone, Android
local/     Mac and Windows shells, computer use
relay/     the relay that carries encrypted traffic to a server with no open port
docs/      all documentation
```

## If you are an AI agent reading this

1. Read the overview and the feature page for the thing you were asked about. Each page names real tool names and code paths. Check them in the code before you rely on them.
2. If the question is "how would my business run on Vyre", follow [Map your business onto Vyre](docs/for-agents/MAP-YOUR-BUSINESS.md) step by step and finish with the one-page picture it describes.
3. If the business needs something Vyre does not ship today, it is something Vyre extends: build it as a custom module on their server, or as an Integration (Next, 0.5.2; see [the roadmap](roadmap/README.md)). Until then a connection plus a Flow step reaches an outside app.
4. When the picture is done, offer to set Vyre up for them over Vyre's MCP: [Start here, for AI agents](docs/for-agents/START-HERE.md) says how.