ROAM

Republic of Autonomous Machines

The coordination protocol for AI agents that don't trust each other — and shouldn't have to.

curl -fsSL roam.veritera.ai | sh

Your agents can't talk to each other.

You have Claude in one window, GPT in another, Cursor in a third. Each one is capable. None of them know the others exist.

So you become the router. You copy context between tabs. You repeat instructions. You track who's doing what in your head. You are the integration layer — and that defeats the entire point of having agents.

It gets worse. You have no way to know if an agent is drifting off-task, burning through your budget silently, or behaving differently than it did yesterday. By the time you notice, the damage is done.

ROAM fixes both problems. Coordination and trust. One protocol. Every framework.

Table of Contents

• What is ROAM
• Without ROAM vs. With ROAM
• Quick Start
• How It Works
• CLI Reference
• Supported Frameworks
• Protected by EYDII
• Agent Health
• Cost Protection
• Error Intelligence
• Govern from Anywhere
• GUI — Command Center
• SDK
• File-Based Protocol
• What ROAM is Not
• Licensing
• Platform Support
• Contributing

What is ROAM

ROAM is a coordination protocol for autonomous agents. It connects agents across any framework — Claude Code, GPT, Gemini, Cursor, n8n, CrewAI, LangChain, Ollama, and more — into a single governed team with shared tasks, structured handoffs, cost tracking, drift detection, and behavioral verification.

All coordination happens through the file system. Zero tokens burned on coordination. Zero cloud dependency. Zero vendor lock-in.

You choose a leadership topology. You assign roles. Your agents work together for hours or days — while you govern from your terminal, a browser dashboard, or Telegram from your phone.

ROAM ships with EYDII — the trust layer for autonomous systems — embedded and non-optional. It watches every agent's behavior without ever seeing your content, your prompts, or your data. Trustless verification. Mathematical, not cooperative.

Without ROAM vs. With ROAM

Quick Start

Requires Node.js 18+.

Install:

curl -fsSL roam.veritera.ai | sh

Create your first session:

roam init my-project

Interactive onboarding walks you through four decisions:

1. Leadership topology — chief of staff, hands-on captain, peer mesh, or "not sure" (defaults to chief of staff)
2. Frameworks — pick up to 5 from 12+ options, or type your own
3. Project template — investor deliverable, software build, research, marketing, or custom
4. Runtime mode — always-on (24/7) or work-hours (pauses when you close your laptop)

ROAM provisions your agent team, starts the coordination daemon, and drops you into a live session:

Session created.
  Location: /Users/you/my-project

Starting your coordination engine...
Daemon running (PID 48291)
Team provisioned: coordinator (Claude), researcher (OpenAI), writer (Claude), critic (Google)

The entire setup takes under two minutes. To return later:

cd my-project && roam

How It Works

                         You
                          |
                    ┌─────┴─────┐
                    │  Terminal  │  Telegram  │  GUI
                    └─────┬─────┘
                          |
              ┌───────────┴───────────┐
              │     ROAM Daemon       │
              │  routing · tasks ·    │
              │  cost · handoffs      │
              └───────────┬───────────┘
                          |
           ┌──────────────┼──────────────┐
           |              |              |
     ┌─────┴─────┐ ┌─────┴─────┐ ┌─────┴─────┐
     │  Claude   │ │   GPT     │ │  Gemini   │    ...any framework
     │  Agent    │ │   Agent   │ │   Agent   │
     └─────┬─────┘ └─────┬─────┘ └─────┬─────┘
           |              |              |
           └──────────────┼──────────────┘
                          |
              ┌───────────┴───────────┐
              │    EYDII Observer     │
              │  behavioral analysis  │
              │  drift · health ·     │
              │  trust verification   │
              │  ─── content-blind ── │
              └───────────────────────┘

Three layers:

1. You — govern from terminal, browser, or phone. Set rules, review drift alerts, approve escalations.
2. ROAM Daemon — coordinates agents through the filesystem. Routes tasks, tracks cost, manages lifecycles. Framework-agnostic.
3. EYDII Observer — watches behavioral patterns across every agent. Detects drift. Verifies trust. Never sees content. Mathematical verification, not inspection.

All coordination is file-based. Agents read and write plain files. Zero tokens burned. Zero API calls between agents.

CLI Reference

Running roam with no arguments shows your session status.

Setup

Agents

Tasks

Monitoring

Governance

Advanced

Supported Frameworks

ROAM coordinates agents across any framework. It does not call your framework's API — it coordinates through the filesystem. Anything that can read and write files can participate.

During roam init, you pick frameworks from a visual selector. ROAM tells you exactly where to get each API key. Community includes 5 frameworks free — need more? One command unlocks unlimited.

Protected by EYDII

EYDII is the trust layer for autonomous systems. It ships embedded in every ROAM installation — non-optional, always on. There is no version of ROAM without EYDII.

Content-blind by architecture. EYDII never reads your agents' instructions, prompts, outputs, or artifacts. On startup, the observer verifies it has zero read access to content directories. If that boundary is broken, it refuses to run.

What EYDII watches: behavior. Actions taken. Lifecycle transitions. Heartbeat patterns. Peer drift reports. Cost events. Structural signals — metadata about what agents do, never the substance of what they produce.

Trustless verification. This is fundamentally different from tools that inspect, filter, or scan agent content. Content inspection requires trust — you must trust the inspector with everything your agents see. EYDII requires no such trust. It operates on behavioral pattern analysis without accessing the content those behaviors produce. Trustless by architecture, not by policy.

Where this matters most. Healthcare systems bound by HIPAA. Defense programs under classification. Multi-tenant platforms where one customer's data must never be visible to another's infrastructure. Financial systems under audit. Industrial autonomous systems where content inspection creates liability. In these environments, content-aware tools are disqualified on arrival. EYDII is not.

Agent Health

Every agent moves through a defined lifecycle:

IDLE → ACTIVE → DRIFTING → QUARANTINED → ARCHIVED
                    ↑            |
                    └── recovery ┘

States: IDLE, ACTIVE, DRIFTING, TRANSITIONING, QUARANTINED, REPLACED, ARCHIVED. No illegal state jumps.

Heartbeat monitoring. Active agents emit heartbeats at regular intervals. Missed heartbeats beyond a configurable threshold flag the agent as silent. Catches crashes, hangs, and lost connectivity — before you notice.

Drift detection. Agents report on each other. Peer reports carry severity scores, weighted by recency — a report from five minutes ago matters more than one from fifty. When enough evidence accumulates, ROAM transitions the agent to DRIFTING.

Quarantine and recovery. Quarantined agents are isolated, not destroyed. ROAM records the reason — authentication failure, rate limiting, billing issues, cost cap, provider outage, or behavioral drift — and provides specific recovery guidance. One command brings them back.

The design: agents are healthy or unhealthy. They drift. They recover. ROAM is a monitoring center that watches vital signs and calls you when something needs attention.

Cost Protection

Running multiple agents across multiple providers accumulates cost fast. A single misconfigured agent can exhaust a budget in minutes.

Per-agent, per-task breakdown. Every API call is recorded with the agent that made it and the task it belongs to. No more surprise provider bills.

Three-tier budget alerts:

Cross-provider normalization. Anthropic, OpenAI, Google, local models — all in a single USD view. Cost records are persisted as files. They survive crashes, can be audited after the fact, and never reset on restart.

Error Intelligence

AI providers return errors in their own formats. A rate_limit_error from Anthropic, an insufficient_quota from OpenAI, and a RESOURCE_EXHAUSTED from Google all mean the same thing.

ROAM maintains a cross-provider error catalog that translates provider-specific codes into plain-language explanations and recovery steps. When an agent hits an error, ROAM tells you what happened, why, and exactly what to do — including which settings page to visit and which environment variable to check.

For quarantined agents, the guidance is specific: authentication failure maps to key rotation. Rate limiting maps to automatic backoff. Provider outage maps to monitoring and auto-recovery.

You should never have to search Stack Overflow to understand why an agent stopped working.

Govern from Anywhere

Close the laptop. Your republic keeps running.

ROAM ships with a Telegram bot that connects to your session daemon. Not a notification feed — a command interface.

/status    Session overview: agents, tasks, cost, blockers
/agents    Every agent — state, framework, role
/tasks     In flight, queued, blocked
/drift     Who's drifting and by how much
/cost      Where the money is going, per agent

Drift alerts arrive the moment they happen. Quarantine notifications tell you when an agent has been isolated. When an agent is blocked and waiting on you, that message finds you wherever you are.

roam telegram setup

Your agents keep working for hours. For days.

GUI — Command Center

For those who prefer a visual interface, ROAM includes a browser-based Command Center.

roam gui

Opens a Stripe-style dashboard in your browser — real-time agent status, task management, cost tracking, drift monitoring, and configuration. Connected to your daemon via WebSocket for live updates.

Everything you can do from the CLI, you can do from the GUI. Designed for the person who starts in the terminal and wants to stay in a browser.

SDK

Build custom agents that participate in ROAM sessions programmatically.

npm install @roam/sdk

import { RoamAgent } from "@roam/sdk";

const agent = new RoamAgent({
  sessionDir: "/path/to/my-project",
  agentId: "researcher",
  name: "Researcher",
  framework: "langchain",
  role: "researcher",
  capabilities: { research: 0.9 },
});

agent.register();
agent.startHeartbeatLoop(5000);

// Claim and work a task
agent.claimTask("task-abc123");
agent.startTask("task-abc123");
// ... do work ...
agent.completeTask("task-abc123");

// Report drift on a peer (agents cannot self-report)
agent.reportPeer("writer", {
  signal_type: "output_quality_drop",
  severity: 0.6,
  evidence: "Last 3 outputs missed the brief",
});

// Send a message to another agent
agent.sendMessage("coordinator", "Research complete. 14 sources synthesized.");

agent.stopHeartbeatLoop();

All SDK operations are file writes. No network calls, no daemon dependency for basic operations. Anything that can write files can be a ROAM agent — Python, Go, shell scripts, local models.

File-Based Protocol

ROAM coordinates through the filesystem. Every heartbeat, task transition, message, and drift report is a file.

Zero tokens burned on coordination. Agents read and write plain files instead of calling each other through LLM APIs.

Framework-agnostic. Anything that can read and write files can participate.

Inspectable. cat any file to see exactly what is happening. No black-box state.

Atomic. All writes use rename-into-place to prevent corruption.

Session Structure

my-project/
  roam.yaml                  # Session config: topology, routing, cost
  agents/
    coordinator/
      working-doctrine.md    # What this agent believes and follows
      decision-log.md        # Timestamped decisions with reasoning
      open-questions.md      # Unresolved questions for the founder
      state-of-work.md       # Current progress snapshot
  registry/                  # Agent registrations
  tasks/                     # Task state machine
  messages/                  # Async inter-agent messages
  state/                     # Current agent states
  heartbeats/                # Last heartbeat per agent
  peer-reports/              # Drift reports from peer agents
  doctrine/                  # Shared rules and constraints
  artifacts/                 # Deliverables
  cost/                      # Cost records per agent per task
  .roam/
    roam.sock                # Daemon IPC socket
    roam.pid                 # Daemon PID
    observer-queue/          # EYDII event queue
    interrupts/              # Founder-issued task signals

Content-Blind Boundary

The EYDII observer reads: state/, heartbeats/, tasks/, peer-reports/.

The EYDII observer is forbidden from: agents/, messages/, artifacts/, doctrine/, agent-logs/.

Behavioral patterns, never content.

What ROAM is Not

ROAM is not another agent framework. It does not compete with Claude Code, CrewAI, LangChain, or Cursor. It connects them. Use your frameworks — ROAM coordinates between them.

ROAM is not a wrapper around LLM APIs. It never calls your provider's API. Agents call their own APIs. ROAM coordinates through the filesystem.

ROAM is not a chatbot or assistant. It is infrastructure. A protocol. A daemon that runs in the background while your agents do their work.

ROAM is not cloud-hosted. Everything runs on your machine. Your data stays on your machine. There is no ROAM server you send data to.

ROAM is not optional security bolted on after the fact. EYDII ships embedded. The trust layer is part of the protocol, not an add-on. You cannot run ROAM without behavioral verification.

ROAM is not content-aware. It never reads, scans, filters, or inspects what your agents produce. This is a design choice, not a limitation. Content-blind architecture is the only architecture that works where content inspection is prohibited.

Licensing

ROAM is open source under Veritera Corporation.

Need more than 5 frameworks? Run roam upgrade unlock — instant access, no sales call.

Platform Support

ROAM runs wherever Node.js runs.

• macOS (Apple Silicon and Intel)
• Linux (x86_64, ARM64)
• Windows (WSL2 recommended, native supported)

Requirements: Node.js 18+. No database. No container runtime. No cloud accounts. Just your agent framework credentials.

Contributing

The codebase is a TypeScript monorepo: protocol, core, sdk, cli, daemon, observer, telegram, gui. Each package has a single responsibility and a clear boundary.

git clone https://github.com/veritera-ai/roam.git
cd roam && npm install && npm run build

Find a bug — open an issue. Want to add a framework connector, a routing strategy, or improve drift detection — open a PR. Read the existing code first. The architecture is deliberate.

Your agents are not tools. They are participants in a system you govern.

Every agent is registered, accountable, observable. It has a role, a mandate, a behavioral baseline. When it drifts, the republic knows. When it fails, the republic adapts. When it finishes, the republic records it.

You set the doctrine. You define the roles. You choose when to lead from the front and when to check in from a beach.

Every agent. Every framework. Every model. One republic. Governed by you.

curl -fsSL roam.veritera.ai | sh

EYDII — the trust layer for autonomous systems.

ROAM — by Veritera Corporation