Skip to Content
Getting StartedQuickstart

Quickstart

Get productive with Agent Harbor in under five minutes by choosing one of the three adoption paths below, then explore branching, session time travel, and multi-agent reviews.

Path 1: Install, Log In & Launch Across Your Fleet

Use this path to connect your workstation to the Agent Harbor control plane and dispatch tasks from the Web UI, Desktop App, TUI (ah tui), or mobile/chat channels.

1. Install the ah CLI

Run the official installer for your shell:

# macOS / Linux / WSL (POSIX shell)
curl -fsSL https://install.agent-harbor.com | sh
 
# Windows (PowerShell)
irm https://install.agent-harbor.com/windows | iex

Verify the binary and inspect local host capabilities:

ah --version
ah health

2. Authenticate and Enrol Your Machine

Log in to https://agent-harbor.com (or pass --server <url> for a self-hosted hub):

ah login

ah login performs three actions:

  1. Completes browser OAuth2 (Authorization Code + PKCE) or device-code authentication and stores a renewable session token.
  2. Signals your local ah server daemon to self-enrol this workstation as an owner-scoped executor over mTLS QUIC.
  3. Initialises or unlocks your client-side encrypted credential vault so your agent accounts synchronise across your fleet.

3. Launch the Interactive TUI or Dispatch Remotely

Open the terminal dashboard:

ah tui

Or check your enlisted executors and launch a session targeted at a specific machine or OS capability:

ah executor list
ah claude --requires os.linux "Run the integration suite and fix failing tests"

Path 2: Change Nothing — Prepend ah (ah <agent> Minimal-Impact Mode)

If you already run AI coding agents in a terminal, keep your exact command line and prepend ah:

ah claude "Add input validation to the signup handler"
ah codex "Fix the race condition in worker_pool.rs"
ah agy "Write unit tests for the parser module"
ah grok "Benchmark the serialiser"
ah copilot "Update the release workflow"
ah amp "Refactor the database connection pool"
ah cursor "Update the billing settings component"
ah opencode "Implement the healthcheck endpoint"
ah qwen "Add localisation keys for French and German"
ah agy "Audit crate visibility boundaries"

What Happens Automatically in Minimal-Impact Mode

  • Native Agent UI (--agent-ui-style native): The agent renders its own interactive terminal interface without alteration.
  • Local OS Sandbox (--sandbox-type local): Enabled by default. Host credential directories (~/.ssh, ~/.aws, ~/.gnupg) are hidden and writes stay inside the workspace.
  • In-Place Working Copy (--working-copy in-place): The agent edits your current working tree directly unless you request an isolated branch (--branch <name>) or snapshot (--from-snapshot <id>).
  • Live Anti-Halting Supervision: Detects hung commands, interactive stdin blocks, and runaway loops.
  • Session Recording & Remote Streaming (events.ahr): Captures a complete .ahr recording and, when logged in via ah login, streams live state to your control plane so you can run ah session attach <id> from another terminal or device.
  • Automatic Sandbox Pass-Through: If you pass a native sandbox/permission bypass flag on the command line (such as ah claude --dangerously-skip-permissions ... or ah claude ... -- --dangerously-skip-permissions or --yolo), Agent Harbor automatically disables its own sandbox (--no-sandbox) and forwards the flag to the underlying agent.

See Direct Agent Launchers & Minimal-Impact Mode for full details.

Path 3: Self-Host the Agent Harbor Hub

Deploy your own control plane on a cloud VM, Kubernetes cluster, NixOS server, or local machine.

Option A: Start the Unified Server Binary

ah server start \
  --rest-host 0.0.0.0 \
  --rest-port 3001 \
  --fleet-listen 0.0.0.0:4433 \
  --server-ca-cert /etc/agent-harbor/ca.pem \
  --server-ca-key /etc/agent-harbor/ca-key.pem \
  --server-token-key /etc/agent-harbor/token.key \
  --db-path /var/lib/agent-harbor/state.sqlite

Option B: Connect Your Fleet to the Self-Hosted Hub

On your workstation, authenticate against your hub:

ah login --server https://ah.example.com --api-key-file ~/.config/agent-harbor/hub.key

To enrol a shared build server or cloud VM, mint a single-use bootstrap token and install the enrolment entry on the target machine:

# On your operator workstation:
ah executors mint-token --server https://ah.example.com --executor-id build-linux-01
 
# On build-linux-01:
ah enroll install \
  --remote-server https://ah.example.com \
  --fleet-url https://ah.example.com:4433 \
  --bootstrap-token-file /etc/agent-harbor/bootstrap.token \
  --unless-enrolled
ah enroll daemon enable

See Multi-Host Fleet, Cloud Executors & Self-Hosting for prepared cloud images (AWS AMI, GCP, Azure, Hetzner, DigitalOcean, OCI, Docker, NixOS).

Essential Next Commands

Once you have run your first agent session, try these core workflows:

# Create an isolated copy-on-write branch and run an agent inside it
ah branch create --name auth-experiment
ah claude --branch auth-experiment "Prototype passkey login"
 
# Inspect the diff produced in the branch
ah branch diff auth-experiment
 
# List recent sessions and attach to a running session's live terminal
ah session list
ah session attach <session-id>
 
# Run an automated 12-lens code review on your changes
ah review changes
 
# Generate a specification and execute a multi-milestone implementation plan
ah spec "Add WebAuthn passkey authentication"
ah plan --from-spec specs/
ah implement

Where to Go Next

Under the hoodInstallation