Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

docs: lead with the device, then get out of the way

deehwa6a6c26d666c
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d53079516..2f9eb7e6a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -10,6 +10,15 @@ design, and it is the difference between an engine that works and one that fails
**Everything about the provider spec** is below, where the most useful contributions are usually not
code at all.
+## Conventions across this repository
+
+- **Specs are numbered.** Every normative statement has a stable id, so a failure can point at a
+ clause rather than a symptom, and a conformance runner can assert one check per id.
+- **Specs are compatibility contracts.** Optional fields may be added; nothing published is renamed,
+ removed, retyped or reinterpreted without a new revision served alongside the old one.
+- **Reference implementations carry no runtime dependencies.** You should be able to read one end to
+ end and know what your own implementation has to do, without installing anything to understand it.
+
## Found a gap in the spec?
Say so. The profile is written against one product's needs, and the first partners to implement it
diff --git a/README.md b/README.md
index b0f68b09e..061e70620 100644
--- a/README.md
+++ b/README.md
@@ -1,61 +1,91 @@
# Autonomous Harness
-The [Autonomous Harness](https://www.autonomous.ai/harness) is a device and a service for running
-coding agents: one sentence, spoken to a disc on your desk, dispatched to the agents already running
-on your laptop, your server, and in the cloud.
+**[Harness](https://www.autonomous.ai/harness) is a disc on your desk that runs your coding agents.**
+Speak one sentence to it and the work goes to the agents already running on your laptop, your
+servers, and in the cloud. The screen shows you what all of them are doing.
+
+Keyboard = type. Mouse = point. **Harness = delegate.**
https://github.com/user-attachments/assets/97848065-61c6-40df-be66-a8247f69aa4c
-This repository is where the parts other people need to build against are published — specs,
-reference implementations, and the tools to check your own work against them.
+## How it works
-| | |
-|---|---|
-| [`cli/`](cli/README.md) | **`harness` CLI** — run the coding-agent CLIs you already use (Claude Code, Codex, Cursor, OpenCode, Pi, Hermes, Command Code, Devin, Muse Code) in tmux on your own machine and drive them from the web app or the device. End-to-end encrypted browser channel; the agents stay your processes with your credentials |
-| [`cli/src/engines/`](cli/src/engines/README.md) | **Agent frameworks** — one folder per agent Harness can drive. **Adding a tenth is a pull request**, and that page is the whole job in dependency order |
-| [`provider/`](provider/README.md) | **Provider protocol** — make your own agent platform available on the Machine. Users connect it with a URL and a credential, then drive it from the web app or the device. A profile of [A2A](https://github.com/a2aagent/A2A) v1.0.1, with a reference implementation and a conformance runner |
+One device, every machine you own. The agents stay your processes, on your hardware, with your
+credentials — Harness watches them and gives you one place to steer them from.
-More will be published here as it stabilises. Each section is self-contained: its own README, its own
-packages, its own tests.
+```
+ Harness (the disc) web app
+ └────────────┬────────────┘
+ │ end-to-end encrypted
+ ┌─────────┴─────────┐
+ │ Autonomous relay │ ciphertext in, ciphertext out
+ └─────────┬─────────┘
+ ┌───────────────────────┼───────────────────────┐
+ │ │ │
+ your laptop your server your platform
+ `harness join` `harness join` your HTTP API
+ │ │ │
+ claude · codex hermes · muse agents running on
+ cursor · … opencode · … your own servers
+
+ └─────── ENGINES ───────┘ └──── PROVIDER ────┘
+```
-## Getting started
+The relay never sees your work in the clear. It moves ciphertext between the device and your
+machines; the keys live on the endpoints.
-Every section stands on its own — start with its README.
+## Get started
+
+Node ≥ 20 and `tmux`. Create a machine in the web app, then paste its token:
+
+```bash
+curl -fsSL https://harness.autonomous.ai/install.sh | bash -s -- <token>
+harness join # connect this computer
+harness status # running? shows the chat link
+```
-### Making your agent work with Harness
+Now start `claude`, `codex`, `cursor` or any supported agent in a tmux pane. It shows up as an agent
+you can talk to from the browser and the device. Full CLI reference: [`cli/README.md`](cli/README.md).
-There are two ways in, and which one you want depends on where your agent runs. Pick the wrong one
-and you will do a lot of work in the wrong place, so start here:
+## Make your agent work with Harness
-| Your agent is… | You want | Where |
+**One question decides everything: does your agent run on the user's computer, or on yours?**
+
+| | **Engine** | **Provider** |
|---|---|---|
-| **A CLI the user runs on their own machine**, writing a transcript to disk as it goes | an **engine** — a folder in the CLI that translates your transcript into Harness's event stream | [`cli/src/engines/README.md`](cli/src/engines/README.md) |
-| **A hosted platform** the user reaches over the network with a URL and a credential | a **provider** — implement the A2A profile and run the conformance suite against your endpoint | [`provider/README.md`](provider/README.md) |
+| **Your agent runs** | on the user's own computer | on your servers |
+| **Harness reaches it by** | reading the transcript it already writes to disk | calling your HTTP API over the network |
+| **You write** | a normalizer, in TypeScript, in this repo | an HTTP endpoint, in any language |
+| **You ship it by** | opening a pull request here | deploying your own service |
+| **The user connects it by** | installing your CLI | pasting a URL and a credential |
+| **Today** | Claude Code, Codex, Cursor, OpenCode, Pi, Hermes, Command Code, Devin, Muse Code | your platform |
+| **Start here** | [`cli/src/engines/README.md`](cli/src/engines/README.md) | [`provider/README.md`](provider/README.md) |
-Rough guide: if the user types your agent's name in a terminal, it is an engine. If they log into it,
-it is a provider. Nine engines ship today; adding the tenth is a pull request.
+If the user types your agent's name in a terminal, you want an **engine**. If they log into your
+service, you want a **provider**.
```bash
-# provider: run the reference implementation, then check your own endpoint against it
+# engine — typecheck and replay the recorded-session fixtures
+cd cli && npm install && npm run typecheck && npm test
+
+# provider — run the reference implementation, then check your endpoint against it
cd provider/reference-provider && npm install && npm run dev
npm run conformance -- --url https://your-endpoint --key <credential>
-
-# engine: typecheck and replay the recorded-session fixtures
-cd cli && npm install && npm run typecheck && npm test
```
-## Conventions across this repository
+The provider protocol is a profile of [A2A](https://github.com/a2aagent/A2A) v1.0.1, with a reference
+implementation and a conformance runner you can point at your own endpoint.
+
+## What's in here
-- **Specs are numbered.** Every normative statement has a stable id, so a failure can point at a
- clause rather than a symptom, and a conformance runner can assert one check per id.
-- **Specs are compatibility contracts.** Optional fields may be added; nothing published is renamed,
- removed, retyped or reinterpreted without a new revision served alongside the old one.
-- **Reference implementations carry no runtime dependencies.** You should be able to read one end to
- end and know what your own implementation has to do, without installing anything to understand it.
+| | |
+|---|---|
+| [`cli/`](cli/README.md) | The `harness` CLI — bridges the agent CLIs on your machine to the web app and the device |
+| [`cli/src/engines/`](cli/src/engines/README.md) | One folder per agent Harness can drive. Adding the tenth is a pull request |
+| [`provider/`](provider/README.md) | The provider protocol — spec, reference implementation, conformance runner |
## Contributing, security, licence
-- Gaps in a spec, or a clause its runner cannot actually verify, are the most useful thing to report —
- see [CONTRIBUTING.md](CONTRIBUTING.md).
-- Security reports: **not the issue tracker** — see [SECURITY.md](SECURITY.md).
-- Licensed under [Apache-2.0](LICENSE).
+- Adding an agent framework, or a gap in the spec — [CONTRIBUTING.md](CONTRIBUTING.md).
+- Security reports: **not the issue tracker** — [SECURITY.md](SECURITY.md).
+- [Apache-2.0](LICENSE).