Getting started

Start with one machine. It runs the hub (drover-server), a host daemon (drover-harnessd) and one harness. Add other hosts after one task works.

Before you start

You need:

macOS or Linux with Python 3.11 or later.
One supported harness, installed and signed in: Claude Code, Codex, Antigravity (agy) or DeepSeek Harness.
A PostgreSQL database, or a running Docker-compatible CLI so that the installer can manage one.
Xcode 16 or later and XcodeGen, only to build the iOS app.

Install

Select one control-store mode.

Managed. The installer creates a local PostgreSQL 17 container that listens on localhost only:

curl -fsSL https://raw.githubusercontent.com/arniesaha/drover/main/install.sh \
  | bash -s -- --control-store managed

Existing. You supply a PostgreSQL database. The installer does not create one:

export DROVER_CONTROL_DSN='postgresql://USER:PASSWORD@HOST/DATABASE'
curl -fsSL https://raw.githubusercontent.com/arniesaha/drover/main/install.sh \
  | bash -s -- --control-store existing

The installer does these steps:

Installs a release with verified checksums in ~/.drover/runtime/.
Initializes the control store.
Starts the hub and a local host daemon as user services.
Prints a QR code to pair your phone.

The installer stores the database connection string in ~/.drover/server.env with mode 0600. It does not install a container runtime.

Flag	Result
`--dry-run`	Prints each action and changes nothing.
`--verify-release`	Downloads the release and verifies its checksums. Does not write `~/.drover`.
`--url <host:port>`	Sets the address for pairing. Private addresses only.
`--version vX.Y.Z`	Installs a specified release.
`--adopt`	Migrates an existing source install.

Read install.sh and run it with --dry-run before you install.

Check the installation

Run the status commands:

drover-server status
drover-server doctor

List the hosts. Your machine is in the list:

curl -fsS \
  -H "Authorization: Bearer $(cat ~/.drover/api_token)" \
  http://127.0.0.1:7080/harness/hosts

Open http://127.0.0.1:7080/ in a browser on the hub machine and sign in.

Run a session

In the web cockpit or the iOS app, select a host, a harness and a project directory. Then send a small task.

To use the API instead:

Create a session:

BEARER="Authorization: Bearer $(cat ~/.drover/api_token)"

curl -fsS -X POST -H "$BEARER" -H 'Content-Type: application/json' \
  http://127.0.0.1:7080/harness/hosts/local/sessions \
  -d '{"mode": "structured", "harness": "claude-code", "cwd": "/path/to/your/project"}'

Send a turn. Replace SESSION_ID with the id from step 1:

curl -fsS -X POST -H "$BEARER" -H 'Content-Type: application/json' \
  http://127.0.0.1:7080/harness/sessions/SESSION_ID/turns \
  -d '{"text": "List the three largest files in this repository."}'

Replace local with a host id from /harness/hosts. If the session does not start, run the diagnosis. It changes nothing:

drover-server setup-check --host HOST --harness HARNESS --project PROJECT

Connect the iOS app

You build the app from source. A public beta is coming soon.

Generate and open the project:

brew install xcodegen
cd apps/drover
xcodegen generate
open Drover.xcodeproj

Select your Apple development team. Run the Drover scheme on a simulator or an iPhone with iOS 18 or later.
On the hub, run drover-server pair.
Scan the QR code in the app.

The code is single use and expires after ten minutes. The phone stores its credential in the iOS Keychain. If the camera is not available, select Or enter it by hand in Pair & Connect.

For a physical phone, the QR code must contain an address that the phone can reach. The installer sets this address. On a source install, set it before you pair:

# ~/.drover/config.toml
[server]
metrics_host = "0.0.0.0"
advertised_url = "<private-address>:7080"

metrics_host is the bind address. advertised_url is the address in the QR code. Use a private LAN address or a private Tailscale address. Read Security and privacy first.

Add another host

On the hub machine, run:

drover-server pair-host --name build-mac

Paste the printed command on the new machine. Its code is single use and expires after fifteen minutes.

The new machine installs only the host daemon. It registers as a direct host if the hub can reach it. If not, it registers as a relay host and dials out to the hub.

Enroll only machines that you control. See Known limits.

Build from source

Clone the repository and start the hub:

git clone https://github.com/arniesaha/drover.git
cd drover
uv sync --extra dev
export DROVER_CONTROL_DSN='postgresql://USER:PASSWORD@HOST/DATABASE'
uv run drover-server init
uv run drover-server control-store init
uv run drover-server run

In a second terminal, start a host daemon:

uv run drover-harnessd \
  --host-id local \
  --display-name "Local Mac" \
  --kind macos \
  --listen 127.0.0.1:7081 \
  --local-url http://127.0.0.1:7081 \
  --central-url http://127.0.0.1:7080

Set DROVER_CONTROL_DSN each time you start the hub from source. On first start, the hub creates ~/.drover/api_token with mode 0600.