Relay

Relay — The control plane for your AI workforce

English · 简体中文

Relay helps users work with AI agents across threads, tasks, automations, and projects. Give agents names, roles, and skills, choose where they run, and keep a shared record of requests, runs, and results.

Relay uses a local-first architecture: the backend coordinates work, and daemons execute it on user or managed computers. Each daemon runs Codex, Claude Code, Pi, OpenCode, or Kimi in a workspace on the host or inside a BoxLite sandbox.

Features

• Home — Start your day with a ranked queue of approvals, questions, reviews, and blockers. Start ready tasks, follow running work, see upcoming due dates and automations, and use setup guidance to get your first agent working.
• Threads — Work with an agent, a team, or a project on the computer you choose. Follow streamed reasoning, commands, and tool calls. Stop, retry, or hand off work as needed.
• Tasks — Assign work to an agent or team, set priorities and due dates, and track it from backlog to done. Keep run history and output files with each task.
• Automations — Schedule recurring work daily, weekly, or monthly; Relay dispatches each run to its assignee.
• Projects — Bring a shared workspace and a roster of agents together on one computer.
• Agents and teams — Give each agent a runtime, role, personality, and skills. Group agents into teams that work Solo, Build → Review, Pipeline, or Lead-led.
• Skills — Publish versioned skill bundles and grant them to agents from a shared library.
• Computers — Enroll user or managed computers and see their health, runtimes, and running work.
• Administration — Manage users, computers, activity, and token usage from one Admin Console.

Product tour

Home brings what needs your attention and where your work stands into one daily starting point. Open a thread or task, answer a question, review a result, or snooze an item for later.

Projects A project board from backlog to done, with flow metrics.	Tasks Open tasks across projects, with queues for work that needs your attention.
Automations Recurring work with its cadence, next run, and assignee.	Teams Members, responsibilities, and how work moves between them.
Agents Runtime, host computer, role, personality, and skills.	Skills Versioned bundles with their files and revision history.
Computers What each computer is running and which runtimes are ready.	Admin Console Thread volume, fleet health, and token usage.

These screenshots use demo data and the dark theme. Generate them with script/readme-snapshots.

Quick start

You need Node.js 22.19+, npm, Python 3.12+, uv, and PostgreSQL. For the default BoxLite sandbox, you also need Docker, hardware virtualization, and credentials for the agents you plan to use.

Run the following commands from the repository root.

1. Install and configure

npm install
npm run build

Copy the environment examples and add your agent credentials (details in Local Development):

cp backend/.env.example backend/.env
cp web/.env.example web/.env.local
cp packages/.env.example packages/.env

2. Prepare the database and admin account

Relay stores sessions, tasks, events, and artifacts in PostgreSQL. Create the role and database specified by RELAY_DATABASE_URL in backend/.env. The example uses role relay and database relay on localhost:5432. Then apply the migrations:

make backend-migrate

Create the first admin account (there is no default password):

script/init_users.sh --password 'choose-a-strong-password'

3. Start the services

Start each service in its own terminal:

make backend                     # control plane on 127.0.0.1:8790
make daemon SANDBOX_ID=node_dev  # execution node connected to the backend
make web                         # web UI on 127.0.0.1:5000

Open http://127.0.0.1:5000 and sign in as admin.

Tests, database migrations, the supervisor, pre-commit hooks, and shutdown commands are covered in Local Development.

Project structure

backend/     Python / FastAPI control plane: API routes, event-sourced stores, scheduler, migrations
packages/    TypeScript workspaces
  relay-core/        Shared protocol, agent registry, CLI commands, prompts
  relay-daemon/      Execution plane: registers a computer and runs agent CLIs
  relay-supervisor/  Keeps user daemons provisioned and running
web/         Next.js web UI, exported statically and served by the backend
docs/        Architecture, API, deployment, design system, and ADRs
script/      User bootstrap, demo seeding, README snapshot generator
devbox/      The BoxLite guest image that sandboxed agents run in

Contributing

1. Get the stack running with the quick start.
2. Read AGENTS.md for repository guidance and invariants, and docs/adr/ for past design decisions.
3. Run npm test (TypeScript and Python suites) and make pre-commit-run before opening a pull request.
4. Update the matching page under docs/ when behavior changes.

CONTRIBUTING.md has the detailed layout and a guide to where each kind of change starts.

Deployment

docs/deployment.md covers hosting the web UI on Vercel and the backend plus Postgres on Railway. Run daemons on the computers that execute your agents; they connect to the backend over outbound HTTP(S).

Documentation

Start with the docs/ index for the canonical setup, API, architecture, design, and decision documents.

License

MIT. You may use, modify, distribute, and sell Relay, including in closed-source products, provided you retain the copyright and license notices. Third-party components and assets retain their own licenses.