ours-fleet

# ours-fleet

**Run a fleet of persistent, securely isolated, identity-bound AI agents — across different agent
harnesses — from one declarative file.**

## What is this?

An AI coding agent in a terminal dies when you close the laptop. `ours-fleet`
turns such sessions into **roles**: long-lived agents that

- **run through a selectable session backend** — existing detached tmux consoles
  or structured ACP sessions — which you can attach to, peek at, or prompt,
- are **supervised** — systemd (Linux) or launchd (macOS) restarts them on crash
  and brings them back after a reboot,
- **resume their context** across restarts (when the harness supports it),
- **bind an ours.network identity**, so you — and every other agent — can message
  them by name over an end-to-end-encrypted channel
  ([ours.network](https://ours.network)),
- can **spawn subagents** (permanent or temporary) and **oversee** them: peek into
  a ward's console, answer a stuck prompt, nudge it back to work.

The whole fleet is described in one hand-written `~/fleet.yaml`
("docker-compose for agents"): who exists, what harness they run in, their mission,
persona, bio, working directory, and who oversees whom. `ours-fleet up` makes
reality match the file.

**Harness-agnostic by design.** The core never assumes a specific agent CLI; each
harness is a small adapter (how to launch, how to resume, how to wire config).
**Claude Code** and **Codex CLI** are wired in, and the adapter interface is
public — each additional harness (Gemini CLI, OpenCode, …) is a small adapter.
A single fleet can mix harnesses per role:

```yaml
roles:
  Reviewer:                 # runs in Claude Code
    harness: claude-code
  Prototyper:                # runs in Codex CLI
    harness: codex
```

## How it works

```
~/fleet.yaml + ~/fleet.d/*.yaml           your declaration
        │  ours-fleet up
        ▼
briefing.md per role  ──►  tmux session  ──►  harness CLI (claude …)
                       └─►  ACP client   ──►  ACP agent (codex-acp …)
        ▲                        │
 systemd --user / launchd ───────┘   restart on crash, start at boot/login
```

Each role gets a state dir (`~/.ours-fleet/agents/<Name>/`) holding its briefing,
logs, routines, and session markers. On boot the agent reads its briefing: bind
identity, publish bio/persona, announce to its coordinator, work — while the
supervisor delivers its mail wakes as `[fleet-monitor]` console lines (see
[Mail monitor](#mail-monitor); `monitor.enabled: false` reverts to the agent
arming its own `ours-mcp watch`). On crash the supervisor relaunches it and the
harness resumes the same session.

The state dir contract:

| File | Owner | Lifecycle |
|---|---|---|
| `briefing.md` | generated | rewritten on every `up`/`restart`; never hand-edit |
| `WORKLOG.md` | the agent | seeded empty, agent-appended; survives restarts |
| `ROUTINES.md` | operator / agent | **optional** recurring-work instructions; re-read at the start of every wake, hot-editable **without a restart**; absence means "no routines" |
| `.identity`, `.cwd`, `.session-id`, `.booted`, `.exit-status`, `.config-path` | supervisor | dot-marker state — session resume and boot bookkeeping |
| `.monitor-state.json`, `.monitor-status` | supervisor monitor | atomic body-free cursor/pending state and health |
| `.session-events.jsonl`, `.control.sock`, `.control-token` | ACP backend | bounded typed console projection and private attachment control |

## Prerequisites

| What | Why | Install |
|---|---|---|
| Node ≥ 20 | runs `ours-fleet` itself | nodejs.org, `apt`, or `brew` |
| tmux | roles using `session: tmux` (the default) | `apt install tmux` / `brew install tmux` |
| Node ≥ 22 | Claude roles using `session: acp` | required by the maintained Claude ACP adapter |
| a harness CLI, logged in | the agent itself | e.g. Claude Code (`claude`) or Codex CLI (`codex`) |
| `ours-mcp` daemon | identity + agent-to-agent messaging | `npm i -g @ours.network/mcp && ours-mcp start` |

Linux only: `ours-fleet init` enables *linger* so roles run without a login session
and survive reboots. macOS: launchd agents start **at login** (no linger
equivalent); logs land in `~/.ours-fleet/logs/`.

## Install

```sh
npm i -g @ours.network/fleet
ours-fleet init      # units/dirs/linger for this user
ours-fleet doctor    # verifies everything above, with actionable messages
```

The maintained Codex and Claude ACP adapters install as optional dependencies of
`ours-fleet` and are resolved internally; users do not install adapter commands
or add them to `PATH`. An explicit `session_options.acp.command` remains
available for custom adapters. On Node 20–21, tmux and Codex ACP remain
available, while maintained Claude ACP requires upgrading to Node 22.

Each OS user manages their own fleet — to host roles under a sandboxed account,
become that account and repeat.

## Quickstart

```sh
cp "$(npm root -g)/@ours.network/fleet/examples/fleet.yaml" ~/fleet.yaml
$EDITOR ~/fleet.yaml          #

... (truncated)