Quickstart

Joining a team? Start with Join a factory. Host owners can share a host with their team.

This page takes one laptop from nothing to a finished agent run you can search. Your laptop plays both parts: it sends the order and it runs the worker.

This page uses macOS or Linux. You need Docker running, Git, and Codex or Claude Code installed and logged in. Because this machine also runs the worker, it needs tmux too (brew install tmux). A laptop that only sends work to another host doesn’t; see what you need. You also need a clone of a repository you are happy to let an agent change, under ~/workspace, with an origin remote. This page uses ~/workspace/my-project. On Windows, see Windows.

1. Install

brew tap hev/tap
brew trust hev/tap
brew install hev/tap/hev

The install page covers Linux, Windows and building from source.

2. Start the daemon

hev up

hev up starts a local trace archive in Docker, writes ~/.hev/config.toml, and installs the capture daemon, hevd, under launchd on macOS or systemd on Linux. It needs no account and no key. Check it:

hev s

hev s shows the daemon’s last scan, how many units it indexed and the last error. On Linux, hev up installs a systemd user service. Without a usable user manager, run hev d under your own supervisor.

3. Configure one host

Dispatch reads ~/.config/hev/dispatch.toml on the machine that sends work. Create it with one host, the laptop itself:

workspace = "~/workspace"

[hosts.laptop]
local = true
cap = 2

local = true runs workers on this machine without SSH. cap is how many runs it takes at once. Confirm the host is reachable and has free slots:

hev dispatch hosts

4. Write an order

An order is a Markdown file with flat frontmatter and an ## Acceptance section. Save this as first-run.md:

---
name: first-run
host: laptop
repo: my-project
harness: codex
timeout: 30
---
Add a short "Development" section to README.md that says how to run the tests.
Commit on this branch. Do not push and do not open a pull request.

## Acceptance
- README.md has a Development section with the test command.
- The change is committed on branch d/first-run.

repo is a directory under workspace. base defaults to main; set it if your default branch has another name. Use harness: claude for Claude Code.

5. Dispatch it

hev dispatch first-run.md

Dispatch fetches origin, creates branch d/first-run from origin/main in a new worktree at ~/dispatch/first-run/wt, and starts a supervisor in the tmux session d-first-run. The supervisor owns the timeout and writes the result when the agent exits.

6. Watch it

hev dispatch ls
hev dispatch logs first-run -f
hev dispatch attach first-run

ls lists running runs with their state, age and trace. logs -f follows the worker’s output. attach opens its tmux session.

To add an instruction while it works, append to its inbox. The worker reads it between steps:

hev dispatch say first-run 'Keep the section under ten lines'

When it finishes, read the receipt:

hev dispatch show first-run

show prints the run’s metadata, status notes, report, result and inbox. The same files are on disk in ~/dispatch/first-run/.

7. Search its trace

The daemon scans every five minutes by default. Run hev index to index now, then filter by the order name:

hev index
hev traces list --order first-run
hev traces search "how to run the tests" --order first-run

Sessions whose working directory is under ~/dispatch/first-run/ carry order=first-run, so the worker’s whole session comes back under that name.

8. Clean up

hev dispatch clean first-run

clean removes the worktree and keeps the order, logs, report and result. It leaves the d/first-run branch in your clone.