Architecture

Architecture

New to the code? Read Architecture overview first (ten minutes), then The Vyre map: a 30-minute tour of the kernel, modules, the Gate, the Vault, Records and Flows, the apps and where data lives. This page is the short version.

Vyre is one small daemon, vyred, on each machine you own, plus a Claude Code plugin. Everything else is a module the daemon loads. This page is the map. The specification is the source of truth for every detail, and the decision records say why each hard choice went the way it did.

One process per machine#

vyred runs every service on its machine (Section 2 of the spec, principle 3). It is the same code on the box and on the Mac, with different modules enabled, chosen by role in ~/.vyre/config.json (box or local). Most Core modules run on both; a few run only on the box (names, onboarding, agents' computers, Glass streaming), and the Local modules run only on the Mac. The exact split is in The box and the Mac. The vyre CLI is a thin client: every command is a call to vyred, over its unix socket (~/.vyre/vyred.sock) on the same machine or its HTTP API from elsewhere.

Everything is a module, including the core services, and every module uses the same contract: a module.json manifest and an entry file that registers tools and emits events. See Modules and The module contract. The loaded set on this branch is listed in the module reference.

The three layers#

Optional first-party modules live in modules/: hands-desktop and hands-chrome (module name chrome) for agents' computers. modules/vault-extension is not a vyred module: it is the browser extension for vault autofill.

The box and the Mac are paired into one system by core/link: the Mac can call the box's tools, the box's events reach the Mac, and the box reads the Mac's sessions through a request the Mac holds open, so the Mac opens no port (ADR 0021). See The box and the Mac.

The floor's rules run twice: in Claude Code's PreToolUse hook, and in vyred for every tool call that does not come from you at your own surface. See the security floor.

Surfaces#

Every surface talks to vyred's API. None reads the store directly (Section 9 of the spec).

A thread is one thing wherever it is viewed, and one screen types into it at a time (floor rules 3 and 4). Every session is a real Claude Code session, in a terminal or headless under the Switchboard; Vyre never imitates Claude Code.

Repository layout#

The full tree is Section 3 of the spec. In short:

bin/vyre          the CLI entry (thin: checks the Node version, calls core/cli)
core/             services that run inside vyred, one folder each
harness/          the Claude Code plugin: hooks, MCP server, skills, commands
local/            Mac-only modules: capsule, hands-mac
apps/app/         the Vyre app (Expo); vyred serves its web build at /app/
modules/          first-party optional modules
box/              the Docker stack for a server: Dockerfile, compose.yml, the host wrapper
site/             vyre.run: the landing page (build-site.sh adds the installer)
scripts/          install, release, perf-check, and the docs tooling
docs/             these pages, the spec, the ADRs
test/             cross-module tests; unit tests sit beside their code

Runtime data never lives in the repository. It lives in ~/.vyre/ (override with VYRE_HOME): config.json, the store vyre.db, the sealed vault/, installed modules/, watchers/, certs/, models/ and embedder/ (the search model, fetched on first use), logs/ and the socket. On a Docker box that folder is inside the vyre_vyre-home volume. See Looking after the box.

Principles that shape the code#

The nine principles are in Section 2 of the spec. The ones you meet first when reading the code:

• Public Claude Code surfaces only. Plugins, hooks, MCP and documented CLI flags. Reading transcript files is the one exception, kept in a single adapter, core/transcripts.
• Local first. Nothing leaves your machines except through the Gate.
• Boring, readable code. Node 22.5 or newer, ES modules, plain JavaScript with JSDoc types and // @ts-check, no build step for the core, node:sqlite, node:test. A dependency needs a reason in the changelog.
• Light by default. Idle budgets for vyred, Lumen and the Vyre app. scripts/perf-check holds vyred to its budget in CI; Lumen and the app are measured by hand. See Performance.
• The security floor cannot be configured away. See the floor and Security.

Decision records#

Architecture decision records live in docs/adr/. Each states the problem, the decision and its consequences.

Where to go next#

• Specification, the whole design.
• Performance, the budgets and how they are measured.
• Security, the model in one page.
• Contributing, if you want to change any of this.