Agent reference

Doc type: Reference  ·  Scope: Harne8 platform (this repository) Verified: 2026-08-18, against agent/cmd/h8/main.go and agent/pkg/{client,pack,pairing,projectid} (specs harne8-agent-identity-unification, harne8-agent-desktop-shell).

h8 is a native, stdlib-only Go binary (~3,000 lines) that connects a machine to the Harne8 platform: pairing, pushing a local repo, and running the execution loop. New here? Start with the Quickstart instead — this page is the full reference.

Identity: paired vs. token

Two ways to authenticate, in order of preference:

1. Paired identity (h8 agent pair) — a durable, per-machine identity approved once in the Portal. push and loop use it automatically once it exists. Revoking it in the Portal invalidates it everywhere at once, the same way for both ingest and execution.
2. Shared token (HARNE8_AGENT_TOKEN / --token) — a team-wide secret (CONDUCTOR_AGENT_TOKEN on the backend), scoped only to ingest/onboard/wiki-bundle. Used automatically as a fallback when no pairing exists on disk — the practical path for headless machines and CI, where an interactive pairing approval isn't possible.

Both are read from ~/.harne8/agent.json (override with --credential-file), permissions 0600. Pairing done via the CLI or via Harne8 Desktop is the same file — either one pairs the machine for both.

Commands

agent pair — pair this machine

h8 agent pair --agent-id <id> [--backend <url>] [--token <t>] [--poll <secs>] [--credential-file <path>]

Flag	Required	Default	Notes
--agent-id	yes	—	Stable local identifier for this machine (e.g. hostname).
--backend	no	http://localhost:8788	Conductor API base URL.
--token	no	—	Bearer token, optional in dev.
--poll	no	5	Poll interval in seconds (server may override via the pairing response).
--credential-file	no	~/.harne8/agent.json	Where the approved pairing is saved.

Prints a user_code to approve in the Portal's Agents page; polls until paired, expired, or revoked.

push — connect a local repo

h8 push [flags] <folder>

Flags must precede the folder argument.

Flag	Required	Default	Notes
--name	yes, unless --project	—	Display name; project_id is derived as proj.<kebab-case>.
--project	no	derived from --name	Explicit project_id override.
--backend	no	$HARNE8_BACKEND_URL, or the paired backend if paired	Conductor API base URL.
--token	no	$HARNE8_AGENT_TOKEN	Bearer fallback; ignored when a paired identity exists.
--exclude	no	—	Repeatable. node_modules/.DS_Store are always excluded.
--no-onboard	no	false	Skip triggering onboarding after ingest (trigger it later from the Portal/API).
--full	no	false	Force a full upload, ignoring local delta-sync state.
--credential-file	no	~/.harne8/agent.json	Paired credential to read.

Sends the whole folder except excluded paths (.git is included when present, enabling commit-history indexing). Symlinks are never followed. Re-running push after the first one sends only the delta (changed/deleted files) unless --full is set or the server's state has diverged, in which case it falls back to a full upload automatically.

run — plan and start a task

h8 run --project <id> (--spec <slug> | --prompt <text>) [--follow] [--json] [--enrich] [--title <t>] [--handle <h>]

Drafts and starts a task from an existing spec (--spec) or a natural language prompt (--prompt, mutually exclusive with --spec). --follow streams the task's timeline via SSE until it reaches a terminal state.

agent loop — execute tasks automatically

h8 agent loop --project <id> [--executor platform-worker|edge-runner] [--preset <name>] [--poll <secs>] ...

Polls for READY_FOR_AGENT tasks and executes them. Uses the paired credential automatically when one exists (--credential-file to point elsewhere); --runner-id defaults to the paired agent_id when paired. --executor edge-runner runs the Harness locally via --harness-bin, --workspace, --out; see the flag list in h8 agent loop (no args) for the full set, including edge-runner account-auth flags (--auth-home-base, --allow-interactive-login).

status — show the paired identity

h8 status [--credential-file <path>]

Prints agent_id, backend, and the credential file path — never the credential itself.

doctor — validate local pairing

h8 doctor [--credential-file <path>]

Checks the credential file exists, has 0600-or-tighter permissions, and parses to a non-empty agent_id/credential. Prints ok: paired agent <id>; credential permissions are restricted on success.

Environment variables

Variable	Used by	Equivalent flag
HARNE8_BACKEND_URL	push, run, loop	--backend
HARNE8_AGENT_TOKEN	push, run, loop	--token

Harne8 Desktop (GUI)

agent-desktop/ in this repository is a native app (Wails v3) with the same Pair and Push flows in a window instead of a terminal — same credential file, same Go logic, no reimplementation. Not yet packaged as a downloadable installer (build/signing pipeline is a separate, not-yet-scheduled piece of work); build it yourself:

cd agent-desktop
wails3 build            # requires Wails v3 + platform webview deps (webkitgtk/gtk4 on Linux)
./bin/h8-desktop

Security notes

• The agent only reads the folder you point it at — it never exposes your filesystem over the network.
• All connections are outbound (your machine → backend); nothing connects back to you.
• Prefer pairing over the shared token: it's revocable per-machine, the token is a team-wide secret.