Runtime
Orchestration kernel
Tasks, planner runtime, tools, memory, sessions, events, skills, artifacts, and the unified pause/resume primitive.
Go-native agent runtime · v1.16
Durable, steerable, event-driven AI agents in Go.
Most agent loops live in a goroutine and die with it. Harbor persists run state, so a paused run survives a process restart. Multi-isolation is mandatory from the first line — one user can hold many concurrent, isolated sessions. The Planner is swappable; the Runtime owns the mechanism. It all ships as one CGo-free static binary.
go install github.com/hurtener/Harbor/cmd/harbor@latest$ go install github.com/hurtener/Harbor/cmd/harbor@latest
$ harbor init # tiered harbor.yaml + companion docs
$ harbor validate ./harbor.yaml
✓ config valid
$ harbor dev # runtime + Protocol server
→ listening on http://127.0.0.1:18080
→ healthz ok · ReAct plannerCode is the proof
Five minutes to a working agent
No broker to stand up, no service mesh, no Python toolchain. Install the binary, scaffold a project, point it at one LLM provider — or skip the CLI and embed the runtime in your own Go program.
go install github.com/hurtener/Harbor/cmd/harbor@latest
mkdir my-agent && cd my-agent
harbor init # tiered harbor.yaml + AGENTS.md / CLAUDE.md / README.md
# edit harbor.yaml — uncomment one LLM provider block + set its API key env var
harbor validate ./harbor.yaml # fail-loud config check, file:line precision
harbor scaffold --name my-agent # the Go project + a worked agent + a test
harbor dev # local runtime + Protocol server on :18080The sdk/ facade is the supported public surface — importable from any external Go module behind a standing external-module compile smoke that runs in CI. For tests, harbortest/ is a public kit: RunOnce, AssertSequence, AssertNoLeaks, SimulateFailure, and EventLog.RecordedEvents.
Four-layer architecture
Runtime, Protocol, Console, CLI — separated on purpose
Harbor is not one monolith with a UI bolted on. Because observability rides the same wire contract a third party would use, the Runtime never imports the Console and the Console never reads internal Runtime objects. The same surface powers harbor dev, a remote-attached dashboard, and a third-party IDE or TUI client.
Console
Remote dashboard
IDE / TUI client
Harbor Protocol · 0.1.0 — the only contract clients get
Headless Runtimetasks · planner runtime · tools · memory · sessions · events · skills · artifacts · pause / resume
CLI — the single
harbor binary, 11 subcommandsProtocol
Versioned wire contract
The canonical event/state contract, pinned at 0.1.0 and versioned independently of the product release.
Console
Just a Protocol client
A SvelteKit UI baked into the binary, served only by harbor console — it reads canonical events, never internals.
CLI
The harbor binary
One CGo-free static binary with 11 subcommands that drives all of the above.
By construction, not by config
Three non-negotiable properties
These are not features you enable. They are invariants the codebase is built to enforce.
Multi-isolation from V1
Identity is the mandatory triple (tenant, user, session). Every identity-scoped storage method filters on it, and one conformance harness proves all six identity-scoped subsystems hold the boundary under concurrent load. The runtime fails closed on a missing component — no opt-out knob. One user can hold many concurrent sessions with zero cross-talk.
The Console is a Protocol client
All data flows through canonical events and state snapshots. There is no debug shortcut that leaks raw internals — the same contract a third-party client would consume is the only contract the Console gets.
The Planner is swappable
The Runtime owns mechanism — tasks, tools, memory, events, artifacts, pause/resume — and the Planner owns reasoning policy behind one interface. Two concretes ship on identical primitives today: the reference ReAct planner (the default) and a Deterministic planner that proves the seam is real.
Durable + steerable runs
Pause, redirect, resume — without losing context
Run state is persisted, not held in a goroutine. With a durable checkpoint store configured, a paused run survives a process restart via trajectory checkpoints, with a max-park sweeper for parked work.
One pause primitive
HITL approval, tool-side OAuth, A2A AUTH_REQUIRED, and operator pause all back onto the same unified pause/resume mechanism — not three reinventions.
Explicit steering surface
CANCEL · REDIRECT · INJECT_CONTEXT · PAUSE · RESUME · APPROVE · REJECT · PRIORITIZE · USER_MESSAGE — a named control instruction for each.
Fails loudly by design
ErrUnserializable when a pause can't be serialized, ErrToolContextLost on a handle miss — never a silent nil, nil. No try/catch that returns None.
Guarded at the LLM edge
ErrContextLeak and ErrContextWindowExceeded stop oversized or leaked context before it reaches the provider, not after.
The Harbor Protocol
A versioned wire contract, not an internal function call
The seam most agent frameworks never draw: a canonical, versioned contract between the Runtime and anything observing or controlling it — 110 canonical methods, over SSE + REST.
Task controlstart · cancel · pause · resume · redirect · inject_context · approve · reject · prioritizeevents.subscribeidentity-scoped streaming event subscriptionstate.historytail-first windowed event replaytopology.snapshotthe live run/agent topologysearch.* · tasks.* · tools.*semantic search, task lifecycle, tool catalogagent_config.* · governance.*durable config tiers, cost ceilings, rate limits
The runtime surface
Tasks. Tools. Memory. Sessions. Skills. Artifacts.
Harbor reads like an API surface, not a grab-bag.
Tools
Transport-agnostic across in-process, HTTP, MCP, and A2A — all registering into one catalog.
Memory
Session-scoped by default, with an opt-in Embedder seam for semantic memory and skill retrieval.
Tasks & events
A durable TaskService plus a durable EventBus that rehydrates its sequence counter across a restart.
Skills
A DB-backed, token-savvy catalog with a Skills.md importer (harbor skill import / rm).
Governance
Per-tenant cost ceilings, rate limits, and max-tokens, with a mandatory audit redactor on all telemetry.
LLM
Provider-agnostic client for OpenAI, Anthropic, Google, OpenRouter, and any OpenAI-compatible endpoint (NIM, vLLM, ollama, lm-studio).
Persistence triad · deploy your way
in-memory / SQLite / Postgres — at conformance parity
Three storage drivers ship for StateStore and MemoryStore — all held to a single conformance suite. No Postgres-only or SQLite-only features. ArtifactStore adds fs and s3 drivers on top.
| in-memory | SQLite | Postgres | |
|---|---|---|---|
| StateStore | ✓ | ✓ | ✓ |
| MemoryStore | ✓ | ✓ | ✓ |
| Single conformance suite | ✓ | ✓ | ✓ |
| CGo-free | ✓ | ✓ | ✓ |
| Best for | dev / embed | single-node | multi-node |
harbor devLocal Runtime, Protocol server, and config reload on your laptop — edit harbor.yaml and the dev stack rebuilds in place. The Console is served separately by harbor console.
harbor serveThe headless production sibling: verifies JWTs against a JWKS source (asymmetric algorithms only), mints no dev token, embeds no Console.
Same binary, no CGo, one file to ship.
Choose your planner
ReAct today, your policy tomorrow — same runtime
The swappable Planner is a real seam, not a slide. Two concretes ship on identical primitives, and the interface is the contract for everything that comes after.
ReAct
For agents that should think, call a tool, observe, and iterate.
The reference reasoning loop, and the default planner out of the box — the only self-registering, harbor.yaml-selectable driver.
Deterministic
For predictable, testable control flow.
A no-LLM, decision-tree planner you compose from typed steps via the SDK — and the on-disk proof that the Planner interface isn't biased toward an LLM-driven concrete.
Both implement the same Planner.Next interface on the same Runtime, RunContext, and Decision sum. Additional concretes (Plan-Execute, Graph, Workflow, Supervisor, MultiAgent, HumanApproval) are on the post-V1 roadmap — built against the same interface these two already prove.
Engineering rigor you can audit
The trust signal a solo OSS project can actually stand behind
No download counts, no logo wall, no testimonials. Just facts you can verify in the repo.
1static CGo-free binary
11CLI subcommands
110canonical Protocol methods
3conformance-equal stores
2planners on one interface
0.1.0Protocol, versioned apart
- Doc snippets executed in CI
- Per-phase live smoke gate
- Drift-audited Protocol reference
- External-module SDK compile gate
- Published master phase plan
- Apache-2.0 · SHA-256 release checksums
Recently shipped
v1.16.0 — parallel intent + task management
2026-07-18Parallel intent — the Batch decision
A single planner step can now dispatch multiple tools and spawn multiple background tasks at once; two or more spawns auto-group so they can be awaited as a unit. The old one-action-per-turn limit from the native-tool-calling migration is gone.
Task management with a real cancel hierarchy
Reserved _task_status / _cancel_task controls let a run inspect and cancel the tasks it spawned — descendant-scoped, so a run can never touch a sibling's tasks. Cancellation is operator > agent (own descendants) > cascade: there is no uncancellable task, and a human always has the last word.
Background-wake notifications + turn-failure honesty
Background resolution mirrors onto the conversation surface, and a failed foreground turn now shows a prominent × Turn failed line instead of going silently idle — on both the native TUI and the Console.
OAuth broker legs + prompt-cache telemetry
An insufficient-scope step-up becomes structured data instead of a retry storm, resource-bound token exchange and per-tool OAuth binding land, and provider cache read/write tokens now flow through the cost surface. All additive — the Harbor Protocol holds at 0.1.0.
Boot the whole runtime locally with one command
Then read the design RFC to see how it's built, or browse the 10 operator skills and 12 recipes that walk you from scaffold to production.
$ go install github.com/hurtener/Harbor/cmd/harbor@latest
$ harbor dev