openlatch-client 0.2.2

OpenLatch is the agent-agnostic execution control layer for enterprise AI agents. This repository is its open-source capture-and-enforce adapter: the node that runs inside a coding agent's own execution path, evaluates every covered action against that agent's Autonomy Zone before it runs, and is what gives an agent the control level Enforced.

It is Mode 1 — the native hook — the first of three adapters onto one policy brain. It plugs into agents through their native lifecycle hooks, decides locally, and forwards what it sees to the control plane.

This README is for people working on the client. If you want to use OpenLatch, start at docs.openlatch.ai — npx @openlatch/client init and you are done.

Where this node sits

OpenLatch runs a five-step control loop around each agent's Agent Autonomy Zone — the operating envelope of what an agent may do, authored on the platform as intent policies across five dimensions (Quality, Economics, Security, Safety, Compliance) and compiled to deterministic rules. This client touches four of the five steps. None of the authoring happens here.

Four properties shape the code more than any feature does:

The three adapters

Verdicts, and which ones this node enforces today

The verdict vocabulary is Allow, Ask, Block or Optimize. What this binary can express is narrower than the vocabulary, and this is the honest map of it. A verdict is deterministic because an explicit policy produced it.

Staging is per rule: observe records the match and allows the action, enforce applies the verdict — Monitor and Enforce in the product. Most restrictive wins across matching rules, and every rule is coerced to observe when the bundle's enforcement_enabled is false.

Deny enforcement is event-scoped. Only pre-action events have somewhere to put a deny; on a post-action event it degrades to {} and survives in the record alone.

Develop

git clone https://github.com/OpenLatch/openlatch-client && cd openlatch-client
cargo build
cargo test

Rust 1.88+, no other prerequisites. cargo build produces both binaries in target/debug/.

Work in a sandbox, not on your own machine

openlatch init installs into ~/.openlatch, writes ~/.claude/settings.json, and points every live Claude Code session on the host at its boundary listener. You do not want your work-in-progress build doing that.

olbox gives you a complete install that cannot touch your own — its own state directory, its own agent config, its own ports:

cargo install --path tools/sandbox --locked    # once

olbox enter dev         # a shell inside the sandbox
openlatch init          # installs into the sandbox and nothing else
claude                  # this session — and only this session — is routed
exit                    # and you are back on your own machine

It lives in tools/sandbox rather than in the client, because sandboxing is what we need and the client is what customers install. olbox list, olbox exec dev -- <cmd>, olbox destroy dev, and eval "$(olbox env dev)" if you would rather not use a subshell — the README covers all of it.

Under the hood it is five environment variables derived from the name, which are supported client seams you can also set by hand. Getting one wrong is not a failed test — it writes your real ~/.claude/settings.json — which is why the tool exists.

openlatch uninstall --purge works inside a sandbox and removes the install; olbox destroy removes the sandbox itself.

A sandbox is never supervised: the OS unit is machine-global and carries no environment, so one installed from a sandbox shell would supervise your real install from your dev binary. supervision enable refuses there, init skips it, and doctor reports Persistence as not applicable. Use openlatch start — a sandbox is a session of work, not something that should survive a reboot.

Verify before you push

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features
cargo test --lib --no-default-features   # proves openlatch-hook links no `core`

tools/e2e holds the end-to-end harness; it drives a real daemon, so run it under olbox exec <name> -- or in its Docker mode — never straight against your own install. It enforces that itself and will refuse to start on a machine whose isolation seams are unset, printing the commands to fix it.

The output contract

Every command that reports health renders from one model (src/cli/report.rs) over the same eleven sections. Three rules decide what you see, and they are enforced by tests rather than by review:

Eleven sections, always all reported, under three groups — the questions a reader asks in the order they ask them:

A green section is one line. Anything else lists what needs attention, with its cause and its remedy. -v unfolds every check.

Runtime
  Environment  ✓    3 passed, 1 not applicable
  Daemon       ✓    2 checks passed
  Persistence  ⚠    Disabled at your request (user_opt_out)   [OL-1513]
                    The daemon will not restart after a logout, a reboot, or a crash.
                    source : [supervision] disabled_reason = "user_opt_out"
                    remedy : Run `openlatch supervision enable` to re-arm it.
  Update       ✓    Daemon is serving the installed version (0.1.18)

Platform
  Cloud        ✓    Connected: http://localhost:5173 (0 event(s) forwarded)
  Telemetry    ·    Disabled by user (opt-out honoured)

Policy sits under Coverage, not Platform: the bundle arrives from the cloud but the evaluation is local and authoritative — it is about what this host enforces, not about what leaves it.

Exit codes

7 matters: openlatch doctor && deploy must not succeed on a host where nothing is captured or enforced.

Commands

Noun-verb aliases: hooks install = init, daemon start = start, and so on — identical arguments, pinned by test.

Global flags: --json, --verbose/-v, --debug, --quiet/-q, --no-color. Every diagnostic's JSON carries the same sections[] the human rendering shows.

Architecture

Hooks live inside the agent, the client decides locally, the platform authors rules and runs analysis.

┌─────────────────────────────────────────────────────────────────┐
│  Your Machine                                                   │
│                                                                 │
│  ┌──────────┐  hook event   ┌──────────────────────────────┐    │
│  │  Claude  │──────────────▶│   OpenLatch Client           │    │
│  │  Code    │               │   (localhost:7443)           │    │
│  │          │               │                              │    │
│  │          │               │   1. Wrap in envelope        │    │
│  │          │               │   2. Evaluate resident       │    │
│  │          │               │      policy in-process       │    │
│  │          │  ◀─ verdict ──│   3. Redact credentials      │    │
│  └──────────┘               │   4. Write local audit log   │    │
│                             │   5. Batch → forward         │────┼──▶  OpenLatch platform
│                             │      ◀── policy bundle       │◀───┼──   (the policy brain:
│                             └──────────────────────────────┘    │      zone, rules, analysis)
└─────────────────────────────────────────────────────────────────┘

• Hook-native, not a proxy — the decision point runs inside the agent's own runtime, so it evaluates the action rather than the traffic. Model-call economics additionally use a loopback listener on 127.0.0.1.
• Local-authoritative verdicts — the daemon evaluates a resident policy bundle in-process; the verdict path never touches the network. The cloud serves rules, it does not decide.
• The daemon owns ANTHROPIC_BASE_URL — written after its bind succeeds and a synthetic round trip proves the listener can reach the provider, removed on teardown. Nothing else writes it, so the agent config can never name a listener that does not exist.
• Fail-static, not fail-open — a resident bundle keeps enforcing offline forever. Genuine fail-open is limited to "no bundle was ever fetched" and "the hook binary cannot reach the daemon".
• Privacy-first — credentials are redacted locally before anything leaves the machine.

Two binaries ship: openlatch (<30 MB, the CLI and daemon) and openlatch-hook (<20 MB, spawned per hook event, fails open to ~/.openlatch/logs/fallback.jsonl).

The product perimeter — what the client does, and what it deliberately does not — is AGENTS.md. Subsystem detail (envelope format, policy engine, subsystem supervision, the boundary's wiring invariants, releasing) lives in .claude/rules/, one file per subsystem, scoped to the paths it governs.

Supported agents

Claude Code, on macOS, Windows and Linux, across 12 hook events. It is the reference implementation, and the only agent this node can currently make Enforced. Other coding agents are recognised as envelope agent_type values — cursor, windsurf, github-copilot, codex-cli, gemini-cli, cline, openclaw — so their events store and attribute correctly, but init cannot install their hooks yet.

Adding one means an AgentBinding in src/hooks/bindings/ and a verdict translator in src/hook_output/ — without the translator a deny is discarded before the developer ever sees it, which is worse than not enforcing. The translator comes first.

Configuration

Precedence: CLI flags → environment (OPENLATCH_*) → ~/.openlatch/config.toml → defaults.

Cloud forwarding is not optional. [cloud] enabled and OPENLATCH_CLOUD_ENABLED are still parsed so existing configs keep loading, but they are ignored — a client that captures events and sends them nowhere is a log rotator. Point [cloud] api_url elsewhere to change where events go.

Auto-update, its quiet-window deferral and its rollback sentinel are documented in the module rustdoc of src/core/update.rs; openlatch update --check --json is the manual probe.

Releases

Two artifacts on independent version lines, both cut by release-please from Conventional Commits:

The schema packages are versioned only by changes under schemas/, so a major bump means a breaking change to the events exchanged with the platform and nothing else. Pin them independently. Details in .claude/rules/release-lines.md.

Why it is open source

The platform is closed; this node is Apache-2.0, for three enterprise reasons.

Security

• Report vulnerabilities to security@openlatch.ai; private vulnerability reporting is enabled on this repository
• Releases are built with SLSA provenance via GitHub Actions
• Full policy: SECURITY.md

Contributing

Read the Contributing Guide, pick a good first issue, and join us on Slack.

Licensed under Apache-2.0.