RelayAgent

The deterministic layer where humans and agents work together.

English | 한국어 | 简体中文 | 日本語

RelayAgent is a personal substrate for agent packages that ship their own screens.

Agents are probabilistic. Collaboration is not. Every agent runtime today hands you a chat box, and a chat box has no surface a human can inspect, verify, or take over mid-flight. A package here ships a screen you can operate and verbs you can replay, judged by one manifest, so the same layer works for both the person and the agent.

One package = one agent + its screen. Installing one gives you software, not a chat window. The view is versioned as one body with its agent, judged by the same manifest, built at install, and hosted by the daemon at /pkg/<name>/view/. Chat and channels are just additional doors into that software.

One package is one directory. A single manifest (relay.yaml) declares everything the package is: its agents, verbs, screens, channels, services, triggers, and what it must not touch. The substrate reads nothing outside the manifest, installs fail-loud, keeps credentials in a vault, and records every inter-package connection as an auditable grant.

Core concepts

Quickstart

Requirements: Node.js 22.6 or later (the runner uses --experimental-strip-types), and a logged-in Claude Code CLI for the bundled harness. On macOS, credentials go to the Keychain; elsewhere a 0600 file vault is used.

git clone https://github.com/relayax/relayagent.git
cd relayagent
npm install
alias relay="node --experimental-strip-types runner/relay.ts"

relay validate packages/system        # judge the manifest
relay install packages/system --ring0 --workspace ~   # management shell as ring-0, home folder as its workspace
relay daemon                          # API, services, triggers, console

The daemon listens on http://127.0.0.1:4747 (change with RELAY_PORT). The console lives at /pkg/system/view/, the authoring playground at /pkg/system/view/playground.html. That console is itself the system package's view: the first piece of agent software running on the substrate.

Talk to the substrate:

relay run system                       # interactive session
relay run system "what is installed?"  # one-shot

Asking the system agent to build something new hands off to its agent-builder subagent, which reads the grammar, scaffolds into the edit layer (a draft), judges it with draft-validate, and publishes it with draft-publish. Installed packages are running binaries and are never edited in place: edits accumulate in a git-backed draft, and only a snapshot that passes judgment becomes a release. To edit by hand, open the Studio (/studio) from the console. GUI edits and agent edits share the same draft, the same diff, and the same publish gate.

CLI

relay daemon                          start the substrate (API, services, triggers, console)
relay install <dir> [--ring0] [--workspace dir]  install a package (workspace = the folder grant)
relay ls | rm <name>                  list | remove
relay validate <dir>                  judge a manifest
relay build <pkg>                     rebuild surfaces.view.out
relay run <pkg> [prompt]              session (interactive without a prompt)
relay harness <pkg> [name]            list or switch harness variants
relay harness-check <pkg>             judge harness contract conformance
relay login <pkg> [--token]           harness login (when the adapter has a login verb)
relay model <pkg> [model]             show or set the model
relay effort <pkg> [level|off]        reasoning effort (adapters with the effort capability)
relay connect <pkg> <service>         paste a credential (vault / Keychain)
relay grant <consumer> <provider> --tools a,b | --mission m

Anatomy of a package

my-package/
  relay.yaml                        the BOM: structure and paths
  assets/icon.svg
  agents/<name>/AGENT.md            persona
  agents/<name>/skills/<s>/SKILL.md skills
  agents/<name>/commands/<c>.md     slash commands
  scripts/<verb>.ts                 default export: async (input, ctx) => JSON
  surfaces/view/                    this package's screen (with `out`, built at install)
  channels/<name>/                  channel adapters (discord, slack, ...)
  harness/<name>/                   execution adapter, bundled with the package
  services/<name>/                  source services (container or process)

The grammar is relay.manifest.yaml, a JSON Schema with commentary. A full worked example manifest is relay.yaml in the repo root. The management shell itself is a package: packages/system.

Design principles

1. The manifest is the BOM. relay.yaml owns structure and paths, the tree owns content. A file unreachable from the manifest does not exist to the substrate.
2. Fail-loud. A mismatch between declaration and reality fails validation and install. There are no warnings, only judgments.
3. Declarations are caps, grants are approvals. edges and dir services in the manifest are applications. Activation happens at install or via relay grant, lands in the ledger, and can never exceed what was declared.
4. Credentials never live in the tree. Manifests declare only the shape of auth (none, token, oauth). Values sit in the vault: macOS Keychain, with a 0600 file fallback.
5. Harness-neutral agents. Agents ship as a neutral bundle (persona, skills, commands, meta). Translating it into any native format is entirely the adapter's job, so packages are not married to one CLI.
6. Minimal ground. A session stands on one granted folder: its workspace, confirmed at install. One more folder means a dir service, and paths a session must never touch go in hooks.deny. The substrate home (~/.relay) is denied to every session, always.

At the root of these six principles sits one premise: everything can be expressed as an agent package.

State on disk

Contributing

Read CONTRIBUTING.md first. The highest-leverage contributions right now:

• Harness adapters for other coding agents (Gemini CLI, Qwen Code, local models): implement the verbs (session, setup, models, commands, info) over the neutral bundle. The bundled claude-code and codex adapters in packages/system/harness are the reference; kimi and pi show the minimal shape. Each is a single shell script.
• Surface references: example screens showing the contract where a view calls its own agent's verbs and the substrate API with the package token.
• Channel adapters (Telegram, email, web widget): map an external identity to a principal and dispatch through RELAY_API.
• Service recipes: working url service declarations (auth, verify) for popular SaaS.
• Conformance checks: extend the harness and channel contract checks judged by relay harness-check.
• Docs and translations.

Security issues go to SECURITY.md, not the public issue tracker.

License

MIT.

Built by RelayAX.