Skip to content

Quickstart: connect a repo and pair an agent

Doc type: Tutorial  ·  Scope: Harne8 platform (this repository) Verified: 2026-08-18, against agent/cmd/h8 and harne8-agent-identity-unification/harne8-agent-desktop-shell (specs).

This gets a local repo connected to Harne8 and a machine paired, in the fewest real steps. Everything here is the actual CLI shipped in this repo — no placeholder commands.

What you'll have at the end

  • h8, a small native binary, paired to your machine.
  • Your local repo materialized as a project on your Harne8 backend, with onboarding (POSE detection, indexing) already triggered.

1. Prerequisites

  • Go 1.26+ — only to build the agent; it has zero external dependencies.
  • A Harne8 backend URL you have access to (e.g. https://api.harne8.com, or http://localhost:8788 for a local dev stack).

2. Build the agent

There is no installer yet — you build the ~3,000-line, stdlib-only binary from source:

# from the root of this repository
go -C agent build -o h8 ./cmd/h8
install -m 0755 agent/h8 ~/.local/bin/h8   # optional: put it on PATH

Verify it built:

h8 push        # prints usage (no args) — confirms the binary works

3. Pair this machine

Pairing gives your machine a durable identity, approved once in the Portal. It's the identity h8 push/h8 agent loop use afterward — no shared team secret to hunt down.

h8 agent pair --agent-id "$(hostname)" --backend https://api.harne8.com

You'll see a short code:

h8: pairing started. Approve this agent in the Portal with code:

    ABCD-1234

Waiting for approval (expires in 300s)...

Open the Portal's Agents page, enter that code, and approve. The CLI picks up the approval automatically and saves the paired credential to ~/.harne8/agent.json (permissions 0600).

4. Connect your repo

h8 push --name "My Repo" /path/to/your/repo

h8: uploading "/path/to/your/repo" as proj.my-repo -> https://api.harne8.com (full)
h8: ingested proj.my-repo
h8: onboarding started for proj.my-repo

Because you paired in step 3, push authenticates with that identity automatically — no token to configure. The project appears in the Portal under Projects; once onboarding finishes it shows spec counts and an Open board button.

Prefer a GUI?

Harne8 Desktop (agent-desktop/ in this repo, binary h8-desktop) wraps the exact same pairing and push logic in a native window — build it with wails3 build from that directory, or package it (task package) as a .deb/.rpm/AppImage. Once h8-desktop is on your PATH, h8 desktop launches it too.

Troubleshooting

Symptom Cause
connection refused Wrong --backend. Confirm with curl -s <backend>/healthz → ok.
invalid agent credential (401) Pairing was revoked or points at a different backend — run h8 agent pair again.
ingest: ... 401, no prior pairing Set --token/HARNE8_AGENT_TOKEN to your team's CONDUCTOR_AGENT_TOKEN (ask whoever runs your backend), or pair instead (recommended — no shared secret to obtain).
Project stays pending, never turns failed A repo without .pose/ degrades gracefully — that alone isn't a failure.

Full command reference, every flag, and the paired-vs-token identity model: see Agent reference.