openlatch-client 0.1.18

OpenLatch is the open-source runtime enforcement node for the OpenLatch AI Operations Platform. It plugs into AI agents via their native lifecycle hooks — capturing every action inside the agent's own lifecycle and positioned to enforce policy deterministically before an action executes. One command installs it across all your agents — no code changes, no configuration.

npx @openlatch/client init

That's it. init auto-detects your installed agents, writes the hook configs, and starts the daemon that captures agent activity and forwards it to the OpenLatch control plane.

Why OpenLatch?

AI agents execute shell commands, read files, call APIs, and install tools — all with your permissions. Most users have zero visibility into what their agents actually do.

OpenLatch gives you:

• Visibility — audit logs of every tool call, shell command, and file access across all your agents
• Control — actions run through the agent's own lifecycle, the point where OpenLatch is positioned to enforce policy deterministically before they execute
• Zero friction — deploys from inside your agent in one command, auto-detects platforms, no code changes

Supported Agents

OpenLatch attaches in three flavors, one per class of agent:

Claude Code is the only integration that attaches today, across macOS, Windows, and Linux. It is the reference implementation the remaining coding agents will follow.

Nine runtime lifecycle events — PreToolUse, PostToolUse, UserPromptSubmit, Notification, Stop, SubagentStop, PreCompact, SessionStart, SessionEnd — plus three configuration-plane events, ConfigChange, InstructionsLoaded and FileChanged, which the daemon dedupes against its own filesystem watcher.

The other coding agents are recognized as envelope agent_type values, so events forwarded on their behalf are stored and attributed correctly — but openlatch init cannot yet install their hooks, and openlatch doctor reports them as not_supported_in_v1. Adding one means a new AgentBinding in src/hooks/bindings/ plus a verdict translator in src/hook_output/; without the translator a deny is discarded before the developer sees it.

Behavioral Coverage

OpenLatch captures the agent behaviors that matter — the raw signal the platform's modules act on:

Quick Start

Install via npm (recommended)

npx @openlatch/client init

Install via Cargo

cargo install openlatch-client
openlatch init

Download binary

Pre-built binaries for macOS (ARM, Intel), Linux (x86_64, ARM), and Windows are available on the Releases page. After the binary is on your PATH, run openlatch init to auto-detect agents and install hooks.

Usage

# Auto-detect agents, install hooks, and start the daemon
openlatch init

# Point the client at a self-hosted platform (persisted to config.toml).
# Use the console origin, not the API port: it proxies /api/v1 AND serves
# the /cli-auth page that browser login opens.
openlatch init --api-url http://127.0.0.1:5183

# Check daemon status, uptime, and event counts
openlatch status

# View the 20 most recent security events
openlatch logs

# Tail events in real time
openlatch logs -f

# Show events from the last hour
openlatch logs --since 1h

# Start/stop/restart the daemon
openlatch start
openlatch stop
openlatch restart

# Run daemon in foreground (useful for debugging)
openlatch start --foreground

# Diagnose configuration and connectivity issues
openlatch doctor

# Remove hooks and stop daemon
openlatch uninstall

# Remove hooks, stop daemon, and delete all data (~/.openlatch/)
openlatch uninstall --purge

# Open documentation in browser
openlatch docs

Command Reference

Noun-verb aliases are also available: openlatch hooks install = init, openlatch hooks uninstall = uninstall, openlatch daemon start = start, etc.

Persistence

openlatch init registers an OS-native supervisor by default so the daemon auto-starts when you log in or reboot — persistence is a security property, not a convenience. All three backends (macOS launchd, Linux systemd --user, Windows Task Scheduler) are user-scope only; no admin prompt, no sudo. Opt out with openlatch init --no-persistence, or toggle later with openlatch supervision disable / enable. openlatch uninstall always tears the supervisor down before stopping the daemon so it cannot auto-restart underneath you.

Troubleshooting

When something goes wrong, prefer this order:

1. Diagnose — openlatch doctor lists every check that's failing (8 today: agent detection, config file, crash-report consent, auth token, daemon liveness, cloud reachability, hook installation, and recent fallback-log activity).
2. Heal — openlatch doctor --fix rewrites broken state files (config, token, hooks) and restarts the daemon. Every mutation is backed up to a .bak sibling and a journal at ~/.openlatch/fix-journal.json. Exit code is 0 when post-fix checks all pass and 1 otherwise.
3. Roll back — openlatch doctor --restore reads the journal and reverses each reversible action. ~/.claude/settings.json is restored via a surgical merge — non-OpenLatch hook entries you've added since --fix are preserved.
4. Bundle for support — openlatch doctor --rescue --yes produces openlatch-rescue-<ts>-<machid>.zip in $PWD. The bundle includes redacted state files, daemon /health + /metrics snapshots, binary metadata (SHA256 only — never bytes), and a per-pattern privacy-filter hit summary in MANIFEST.json. The bearer token in daemon.token is hard-redacted; absolute paths are anonymised to ~.

Combined openlatch doctor --fix --rescue runs the rescue first to snapshot the pre-fix state, then heals.

Global Flags

Exit Codes

Binaries

OpenLatch ships two binaries:

• openlatch (<30MB) — full CLI for setup, daemon management, and log viewing.
• openlatch-hook (<20MB) — minimal hook handler spawned by agent hooks. Reads event JSON from stdin, forwards to the daemon on localhost:7443, and writes the verdict to stdout. If the daemon is unreachable, it fails open (returns allow) and logs to ~/.openlatch/logs/fallback.jsonl. Not invoked directly by users.

How It Works

OpenLatch uses a three-layer architecture — hooks live inside your agent, the client decides locally and forwards events, and the cloud authors the 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      │    │
│  └──────────┘  (allow/deny) │   4. Write local audit log  │    │
│                             │   5. Batch → forward        │────┼──▶  OpenLatch Cloud
│                             │      ◀── policy bundle      │◀───┼──   (rules + analysis)
│                             └──────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘

Key design decisions:

• Hook-native — OpenLatch plugs into the agent's official hook/extension system. The enforcement path runs inside the agent runtime, never as a network proxy; events cannot be bypassed. (Model-call economics capture additionally uses a loopback listener on 127.0.0.1 — on by default, see [boundary].)
• Local-authoritative verdicts — the daemon evaluates a resident policy bundle in-process, so the verdict path never touches the network. The cloud authors and serves the rules; it does not decide. Correlation, cross-host analysis, and scanning stay cloud-side. Policy evaluation ships on (secure-by-default); [policy] enabled = false opts out — a complete off switch, not observe mode.
• Privacy-first — credentials and secrets are redacted locally via regex-based filtering before anything leaves your machine.
• Fail-static, not fail-open — a resident bundle keeps enforcing offline forever, and a failed refresh keeps the last-known-good bundle. Genuine fail-open is limited to two cases: no bundle was ever fetched, and the hook binary being unable to reach the daemon. Event forwarding is separately durable — events spool to outbox.jsonl and sync later.

Updating openlatch

openlatch auto-updates itself silently in the background. By default the running daemon polls the npm registry every six hours, downloads + verifies + applies new releases during quiet moments (no agent activity for sixty seconds AND no hook in flight), and re-execs into the new binary. The min_supported_client and cargo install gates from the manual path apply equally to the worker.

# Disable the worker (env or config):
export OPENLATCH_AUTO_UPDATE=false
# or, persistently:
echo -e "[update]\nauto_update = false" >> ~/.openlatch/config.toml

If the supervisor restarts the daemon at least three times within sixty seconds after a fresh update (sentinel + .bak siblings both present), the next start auto-rolls-back from the .bak files — running before logging is initialised, with output through stderr only. CI environments and cargo install-installed binaries are auto-detected and skip the worker entirely.

openlatch update is the manual escape hatch and works whether or not the worker is enabled:

# Probe the registry; never modifies anything.
openlatch update --check --json

# Apply the update if one is available.
openlatch update --apply --yes

When a daemon is running, the CLI routes the apply through the daemon's authenticated POST /admin/update RPC; the daemon downloads the tarball, verifies the SHA-512 integrity hash and minisign signatures against the trusted key baked into the binary, performs an atomic swap, drains in-flight HTTP traffic, and re-execs into the new binary. With no daemon running, the CLI performs the same swap in-process.

The pipeline refuses to apply when:

• The binary was installed via cargo install (run cargo install --force --locked openlatch-client instead — exit 5, OL-1505).
• The new release's min_supported_client is greater than the running version (run npm install -g @openlatch/client@latest to resync).
• A signature does not verify against the trusted key bundled into the running binary (exit 1, OL-1504).

The supported install paths are npm install -g @openlatch/client and npx @openlatch/client …. Direct curl-installs work but disable the npm-vs-actual drift detection in openlatch status. Releases marked Severity: critical (in the release commit footer) bypass the activity-aware deferral and apply on the next poll regardless of in-flight hook traffic.

Configuration

OpenLatch works with zero configuration. For advanced use cases:

# Configuration precedence (highest to lowest):
# 1. CLI flags
# 2. Environment variables (OPENLATCH_*)
# 3. User config (~/.openlatch/config.toml)
# 4. Defaults

Security

OpenLatch is the on-host runtime enforcement node of the AI Operations Platform — and we hold our own code to the same standard the platform is built to enforce for your agents:

• Responsible disclosure — report vulnerabilities to security@openlatch.ai
• Private vulnerability reporting enabled on this repository
• All releases are built with SLSA provenance via GitHub Actions
• See SECURITY.md for our full security policy

Releases

This repository publishes two artifacts on independent version lines:

The schema packages are versioned only by changes under schemas/, so a major bump means a breaking change to the events exchanged between the client and the platform — and nothing else. Pin them independently of the client version; they carry no dependency on it.

Both lines are cut by release-please from Conventional Commits. Contributor-facing details are in AGENT.md.

Contributing

We welcome contributions! Whether it's bug fixes, new agent integrations, or documentation improvements.

• Read our Contributing Guide to get started
• Check good first issues for entry points
• Join our Slack to connect with the team

License

Licensed under the Apache License 2.0.

Links