<p align="center">
<img src="./assets/banner.jpg" alt="OpenLatch — Security infrastructure for AI agents" width="600" />
</p>
<h3 align="center">See what your agent does. Block what it shouldn't.</h3>
<p align="center">
<a href="https://github.com/OpenLatch/openlatch-client/actions/workflows/pr-checks.yml"><img src="https://github.com/OpenLatch/openlatch-client/actions/workflows/pr-checks.yml/badge.svg" alt="PR Checks" /></a>
<a href="https://codecov.io/gh/OpenLatch/openlatch-client"><img src="https://codecov.io/gh/OpenLatch/openlatch-client/graph/badge.svg" alt="codecov" /></a>
<a href="https://crates.io/crates/openlatch-client"><img src="https://img.shields.io/crates/v/openlatch-client.svg" alt="crates.io" /></a>
<a href="https://www.npmjs.com/package/@openlatch/client"><img src="https://img.shields.io/npm/v/@openlatch/client.svg" alt="npm" /></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="License" /></a>
<a href="https://openlatch.slack.com"><img src="https://img.shields.io/badge/Slack-join%20us-4A154B?logo=slack&logoColor=white" alt="Slack" /></a>
</p>
---
**OpenLatch** is a thin, open-source security forwarder that plugs into AI agents via their **native lifecycle hooks**. One command installs protection across all your agents — no proxies, no code changes, no configuration.
```bash
npx @openlatch/client init
```
That's it. `init` auto-detects your installed agents, writes the hook configs, and starts the daemon that forwards events to the cloud for real-time security analysis.
<!-- TODO: Replace with VHS terminal recording once available -->
<!-- <p align="center">
<img src="https://raw.githubusercontent.com/OpenLatch/openlatch-client/main/assets/demo.gif" alt="OpenLatch demo" width="700" />
</p> -->
## 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
- **Protection** — real-time detection of tool poisoning, credential leakage, prompt injection, and dangerous shell commands
- **Zero friction** — deploys from inside your agent in one command, auto-detects platforms, requires no security expertise
## Supported Platforms
OpenLatch works across **3 operating systems** and **8 agent platforms** from day one.
| Agent Platform | macOS | Windows | Linux | Hook Events |
| -------------- | :---: | :-----: | :---: | ----------: |
| Claude Code | :white_check_mark: | :white_check_mark: | :white_check_mark: | 24 |
| Cursor | :white_check_mark: | :white_check_mark: | :white_check_mark: | 5 |
| Windsurf | :white_check_mark: | :white_check_mark: | :white_check_mark: | 5 |
| GitHub Copilot | :white_check_mark: | :white_check_mark: | :white_check_mark: | 6 |
| Codex CLI | :white_check_mark: | :white_check_mark: | :white_check_mark: | 4 |
| Gemini CLI | :white_check_mark: | :white_check_mark: | :white_check_mark: | 4 |
| Cline | :white_check_mark: | :white_check_mark: | :white_check_mark: | 4 |
| OpenClaw | :white_check_mark: | :white_check_mark: | :white_check_mark: | 4 |
## Threat Coverage
| Threat Category | What it catches |
| --------------- | --------------- |
| **Tool Poisoning** | Malicious MCP servers, tampered tool definitions, supply chain attacks on agent tooling |
| **PII & Credential Leakage** | API keys, tokens, passwords, and personal data leaving your machine via agent actions |
| **Prompt Injection** | Injected instructions hidden in files, tool outputs, or web content that hijack agent behavior |
| **Shell Command Guardrails** | Destructive commands (`rm -rf /`), privilege escalation, crypto miners, reverse shells |
| **Supply Chain** | Compromised dependencies, typosquatted packages, unsigned binaries |
| **Attack Path Analysis** | Multi-step attack chains that combine individually benign actions into a malicious sequence |
## Quick Start
### Install via npm (recommended)
```bash
npx @openlatch/client init
```
### Install via Cargo
```bash
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](https://github.com/OpenLatch/openlatch-client/releases) page. After the binary is on your `PATH`, run `openlatch init` to auto-detect agents and install hooks.
## Usage
```bash
# Auto-detect agents, install hooks, and start the daemon
openlatch init
# 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
| Command | Description |
| ------- | ----------- |
| `openlatch init` | Auto-detect agents, install hooks, start daemon. Safe to re-run. |
| `openlatch status` | Show daemon status, uptime, and event counts |
| `openlatch start [--foreground]` | Start the daemon (or run in foreground) |
| `openlatch stop` | Stop the daemon |
| `openlatch restart` | Restart the daemon |
| `openlatch logs [-f] [-n N] [--since T]` | View event logs. `-f` follows, `-n` limits count, `--since` filters by time |
| `openlatch doctor` | Diagnose configuration and connectivity issues |
| `openlatch doctor --fix` | Auto-heal common issues (config, hooks, daemon, binary). Creates `.bak` siblings and a journal so changes can be reverted with `--restore`. |
| `openlatch doctor --restore` | Reverse the most recent `--fix` run. Surgical merge for `~/.claude/settings.json` preserves user edits to non-OpenLatch hooks. |
| `openlatch doctor --rescue [--since 24h] [--output PATH] [--yes]` | Bundle a redacted diagnostic ZIP for sharing with support. Privacy filter runs on every text file; tokens are hard-redacted. |
| `openlatch uninstall [--purge] [--yes]` | Remove hooks and stop daemon. `--purge` deletes all data |
| `openlatch supervision {install,uninstall,enable,disable,status}` | Manage the OS-native supervisor that keeps the daemon alive after reboot (launchd / systemd --user / Task Scheduler). Installed by default during `openlatch init`; opt out with `openlatch init --no-persistence`. |
| `openlatch docs` | Open documentation in browser |
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
| Flag | Description |
| ---- | ----------- |
| `--json` | Machine-readable JSON output (parseable by `jq`) |
| `--verbose` / `-v` | Show extra operational detail |
| `--debug` | Show internal state and timings (implies `--verbose`) |
| `--quiet` / `-q` | Suppress all output except errors |
| `--no-color` | Disable colored output |
### Exit Codes
| Code | Meaning |
| ---- | ------- |
| 0 | Success |
| 1 | Security findings detected |
| 2 | Usage error (invalid arguments) |
| 3 | Resource not found |
| 4 | Permission denied |
| 5 | Conflict |
| 130 | Interrupted (Ctrl+C) |
### 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 agents, the client forwards events, and the cloud runs detection:
```
┌─────────────────────────────────────────────────────────────────┐
│ Your Machine │
│ │
│ ┌──────────┐ hook event ┌──────────────────────────────┐ │
│ │ Claude │─────────────▶│ │ │
│ │ Code │ │ OpenLatch Client │ │
│ ├──────────┤ │ (localhost:7443) │ │
│ │ Cursor │─────────────▶│ │ │
│ ├──────────┤ │ 1. Wrap in envelope │ │
│ │ Copilot │─────────────▶│ 2. Redact credentials │ │
│ ├──────────┤ │ 3. Forward to cloud │────┼──▶ OpenLatch Cloud
│ │ Gemini │─────────────▶│ 4. Return verdict │◀───┼── (allow / deny)
│ │ CLI │ │ 5. Write local audit log │ │
│ ├──────────┤ │ │ │
│ │ ... │─────────────▶│ │ │
│ └──────────┘ ◀─ verdict ─ └──────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
```
**Key design decisions:**
- **Hook-native** — OpenLatch plugs into each agent's official hook/extension system. It runs inside the agent runtime, not as a network proxy. Events cannot be bypassed.
- **Thin client, smart cloud** — the client wraps events in a standard envelope and forwards them. All detection, normalization, and analysis happens cloud-side.
- **Privacy-first** — credentials and secrets are redacted locally via regex-based filtering before anything leaves your machine.
- **Fail-open** — if the cloud is unreachable, agents continue working normally. Events are logged locally and synced later.
## Configuration
OpenLatch works with zero configuration. For advanced use cases:
```bash
# Configuration precedence (highest to lowest):
# 1. CLI flags
# 2. Environment variables (OPENLATCH_*)
# 3. Project config (.openlatch.json)
# 4. User config (~/.openlatch/config.toml)
# 5. Defaults
```
| Environment Variable | Description | Default |
| -------------------- | ----------- | ------- |
| `OPENLATCH_API_KEY` | Your OpenLatch API key | — |
| `OPENLATCH_API_URL` | Cloud API base URL. Callers append `/api/v1/...` path segments. | `https://app.openlatch.ai` |
| `OPENLATCH_APP_URL` | Web app URL used for browser auth. Falls back to `OPENLATCH_API_URL` (with a trailing `/api` stripped, for back-compat with overrides). | `https://app.openlatch.ai` |
| `OPENLATCH_LOG_LEVEL` | Logging verbosity | `info` |
| `OPENLATCH_FAIL_MODE` | Behavior when cloud is unreachable | `open` |
## Security
OpenLatch is a security product — we hold ourselves to a high standard:
- **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](SECURITY.md) for our full security policy
## Contributing
We welcome contributions! Whether it's bug fixes, new agent integrations, or documentation improvements.
- Read our [Contributing Guide](.github/CONTRIBUTING.md) to get started
- Check [good first issues](https://github.com/OpenLatch/openlatch-client/labels/good%20first%20issue) for entry points
- Join our [Slack](https://openlatch.slack.com) to connect with the team
## License
Licensed under the [Apache License 2.0](LICENSE).
## Links
| Resource | URL |
| -------- | --- |
| Website | [openlatch.ai](https://openlatch.ai) |
| Documentation | [docs.openlatch.ai](https://docs.openlatch.ai) |
| Slack | [openlatch.slack.com](https://openlatch.slack.com) |
| Twitter / X | [@openlatch](https://x.com/openlatch) |
| GitHub | [github.com/OpenLatch](https://github.com/OpenLatch) |