@openlatch/client 0.1.18 → 0.3.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +79 -295
- package/package.json +7 -7
package/README.md
CHANGED
|
@@ -1,351 +1,135 @@
|
|
|
1
1
|
<p align="center">
|
|
2
|
-
<img src="https://raw.githubusercontent.com/OpenLatch/openlatch-client/main/assets/banner.jpg" alt="OpenLatch —
|
|
2
|
+
<img src="https://raw.githubusercontent.com/OpenLatch/openlatch-client/main/assets/banner.jpg" alt="OpenLatch — the execution control layer for enterprise AI agents" width="600" />
|
|
3
3
|
</p>
|
|
4
4
|
|
|
5
|
-
<h3 align="center">
|
|
5
|
+
<h3 align="center">Greater control should enable greater autonomy.<br /><em>Dare to Let Go.</em></h3>
|
|
6
6
|
|
|
7
7
|
<p align="center">
|
|
8
8
|
<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>
|
|
9
|
-
<a href="https://codecov.io/gh/OpenLatch/openlatch-client"><img src="https://codecov.io/gh/OpenLatch/openlatch-client/graph/badge.svg" alt="codecov" /></a>
|
|
10
|
-
<a href="https://crates.io/crates/openlatch-client"><img src="https://img.shields.io/crates/v/openlatch-client.svg" alt="crates.io" /></a>
|
|
11
9
|
<a href="https://www.npmjs.com/package/@openlatch/client"><img src="https://img.shields.io/npm/v/@openlatch/client.svg" alt="npm" /></a>
|
|
12
10
|
<a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="License" /></a>
|
|
13
11
|
<a href="https://openlatch.slack.com"><img src="https://img.shields.io/badge/Slack-join%20us-4A154B?logo=slack&logoColor=white" alt="Slack" /></a>
|
|
14
12
|
</p>
|
|
15
13
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
```
|
|
23
|
-
|
|
24
|
-
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.
|
|
25
|
-
|
|
26
|
-
<!-- TODO: Replace with VHS terminal recording once available -->
|
|
27
|
-
<!-- <p align="center">
|
|
28
|
-
<img src="https://raw.githubusercontent.com/OpenLatch/openlatch-client/main/assets/demo.gif" alt="OpenLatch demo" width="700" />
|
|
29
|
-
</p> -->
|
|
30
|
-
|
|
31
|
-
## Why OpenLatch?
|
|
32
|
-
|
|
33
|
-
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.
|
|
34
|
-
|
|
35
|
-
OpenLatch gives you:
|
|
36
|
-
|
|
37
|
-
- **Visibility** — audit logs of every tool call, shell command, and file access across all your agents
|
|
38
|
-
- **Control** — actions run through the agent's own lifecycle, the point where OpenLatch is positioned to enforce policy deterministically before they execute
|
|
39
|
-
- **Zero friction** — deploys from inside your agent in one command, auto-detects platforms, no code changes
|
|
40
|
-
|
|
41
|
-
## Supported Agents
|
|
42
|
-
|
|
43
|
-
OpenLatch attaches in three flavors, one per class of agent:
|
|
44
|
-
|
|
45
|
-
| Flavor | Agents | How it attaches | Status |
|
|
46
|
-
| ------ | ------ | --------------- | ------ |
|
|
47
|
-
| Coding agents | Claude Code | Native lifecycle hooks | **Shipping** |
|
|
48
|
-
| Coding agents | Cursor, Windsurf, GitHub Copilot, Codex CLI, Gemini CLI, Cline, OpenClaw | Native lifecycle hooks | Planned |
|
|
49
|
-
| Cloud agent platforms | Azure AI Foundry, AWS Bedrock | SDK + tool/MCP gate | Planned |
|
|
50
|
-
| Agentic Python frameworks | LangChain / LangGraph-class | Framework middleware | Planned |
|
|
51
|
-
|
|
52
|
-
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.
|
|
53
|
-
|
|
54
|
-
| Coding Agent | macOS | Windows | Linux | Hook Events |
|
|
55
|
-
| ------------ | :---: | :-----: | :---: | ----------: |
|
|
56
|
-
| Claude Code | :white_check_mark: | :white_check_mark: | :white_check_mark: | 12 |
|
|
57
|
-
|
|
58
|
-
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.
|
|
59
|
-
|
|
60
|
-
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.
|
|
61
|
-
|
|
62
|
-
## Behavioral Coverage
|
|
63
|
-
|
|
64
|
-
OpenLatch captures the agent behaviors that matter — the raw signal the platform's modules act on:
|
|
14
|
+
<p align="center">
|
|
15
|
+
<a href="https://openlatch.ai">Website</a> ·
|
|
16
|
+
<a href="https://openlatch.ai/docs/">Docs</a> ·
|
|
17
|
+
<a href="https://app.openlatch.ai">Dashboard</a> ·
|
|
18
|
+
<a href="https://openlatch.slack.com">Slack</a>
|
|
19
|
+
</p>
|
|
65
20
|
|
|
66
|
-
|
|
67
|
-
| -------- | ------------------ |
|
|
68
|
-
| **Tool Poisoning** | Malicious MCP servers, tampered tool definitions, supply chain attacks on agent tooling |
|
|
69
|
-
| **PII & Credential Leakage** | API keys, tokens, passwords, and personal data leaving your machine via agent actions |
|
|
70
|
-
| **Prompt Injection** | Injected instructions hidden in files, tool outputs, or web content that hijack agent behavior |
|
|
71
|
-
| **Shell Command Guardrails** | Destructive commands (`rm -rf /`), privilege escalation, crypto miners, reverse shells |
|
|
72
|
-
| **Supply Chain** | Compromised dependencies, typosquatted packages, unsigned binaries |
|
|
73
|
-
| **Attack Path Analysis** | Multi-step attack chains that combine individually benign actions into a malicious sequence |
|
|
21
|
+
---
|
|
74
22
|
|
|
75
|
-
|
|
23
|
+
**[OpenLatch](https://openlatch.ai) is the execution control layer for enterprise AI agents.** It turns human intent into **Agent Intent Policies** across each agent's **Autonomy Zone** — security, safety, compliance, economics and quality — and makes a deterministic decision on every covered action before it executes: allow, ask, block or optimize.
|
|
76
24
|
|
|
77
|
-
|
|
25
|
+
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**.
|
|
78
26
|
|
|
79
|
-
|
|
80
|
-
npx @openlatch/client init
|
|
81
|
-
```
|
|
27
|
+
It plugs into the agent's native lifecycle hooks, decides locally and in-process, and forwards what it saw to the platform afterwards. The agent never waits on the network, and the verdict never depends on it.
|
|
82
28
|
|
|
83
|
-
|
|
29
|
+
## Quick start
|
|
84
30
|
|
|
85
31
|
```bash
|
|
86
|
-
|
|
87
|
-
openlatch
|
|
32
|
+
npx @openlatch/client init # installs the client, detects your agents, wires their hooks
|
|
33
|
+
openlatch auth login # links this machine to your OpenLatch account (opens the browser)
|
|
34
|
+
claude # use your agent as usual — every tool call is now covered
|
|
88
35
|
```
|
|
89
36
|
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
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.
|
|
93
|
-
|
|
94
|
-
## Usage
|
|
95
|
-
|
|
96
|
-
```bash
|
|
97
|
-
# Auto-detect agents, install hooks, and start the daemon
|
|
98
|
-
openlatch init
|
|
99
|
-
|
|
100
|
-
# Point the client at a self-hosted platform (persisted to config.toml).
|
|
101
|
-
# Use the console origin, not the API port: it proxies /api/v1 AND serves
|
|
102
|
-
# the /cli-auth page that browser login opens.
|
|
103
|
-
openlatch init --api-url http://127.0.0.1:5183
|
|
37
|
+
`openlatch status` shows what is captured and enforced on this host. The [dashboard](https://app.openlatch.ai) shows the events and the verdicts. Full walkthrough: [Getting started](https://openlatch.ai/docs/getting-started/).
|
|
104
38
|
|
|
105
|
-
|
|
106
|
-
openlatch status
|
|
39
|
+
The installer runs on Node.js. macOS, Windows and Linux are supported.
|
|
107
40
|
|
|
108
|
-
|
|
109
|
-
openlatch logs
|
|
110
|
-
|
|
111
|
-
# Tail events in real time
|
|
112
|
-
openlatch logs -f
|
|
113
|
-
|
|
114
|
-
# Show events from the last hour
|
|
115
|
-
openlatch logs --since 1h
|
|
116
|
-
|
|
117
|
-
# Start/stop/restart the daemon
|
|
118
|
-
openlatch start
|
|
119
|
-
openlatch stop
|
|
120
|
-
openlatch restart
|
|
121
|
-
|
|
122
|
-
# Run daemon in foreground (useful for debugging)
|
|
123
|
-
openlatch start --foreground
|
|
124
|
-
|
|
125
|
-
# Diagnose configuration and connectivity issues
|
|
126
|
-
openlatch doctor
|
|
127
|
-
|
|
128
|
-
# Remove hooks and stop daemon
|
|
129
|
-
openlatch uninstall
|
|
130
|
-
|
|
131
|
-
# Remove hooks, stop daemon, and delete all data (~/.openlatch/)
|
|
132
|
-
openlatch uninstall --purge
|
|
133
|
-
|
|
134
|
-
# Open documentation in browser
|
|
135
|
-
openlatch docs
|
|
136
|
-
```
|
|
137
|
-
|
|
138
|
-
### Command Reference
|
|
139
|
-
|
|
140
|
-
| Command | Description |
|
|
141
|
-
| ------- | ----------- |
|
|
142
|
-
| `openlatch init` | Auto-detect agents, install hooks, start daemon. Safe to re-run. |
|
|
143
|
-
| `openlatch status` | Show daemon status, uptime, and event counts |
|
|
144
|
-
| `openlatch start [--foreground]` | Start the daemon (or run in foreground) |
|
|
145
|
-
| `openlatch stop` | Stop the daemon |
|
|
146
|
-
| `openlatch restart` | Restart the daemon |
|
|
147
|
-
| `openlatch logs [-f] [-n N] [--since T]` | View event logs. `-f` follows, `-n` limits count, `--since` filters by time |
|
|
148
|
-
| `openlatch doctor` | Diagnose configuration and connectivity issues |
|
|
149
|
-
| `openlatch doctor --fix` | Auto-heal common issues (config, hooks, daemon, binary). Creates `.bak` siblings and a journal so changes can be reverted with `--restore`. |
|
|
150
|
-
| `openlatch doctor --restore` | Reverse the most recent `--fix` run. Surgical merge for `~/.claude/settings.json` preserves user edits to non-OpenLatch hooks. |
|
|
151
|
-
| `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. |
|
|
152
|
-
| `openlatch uninstall [--purge] [--yes]` | Remove hooks and stop daemon. `--purge` deletes all data |
|
|
153
|
-
| `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`. |
|
|
154
|
-
| `openlatch inventory {list,log,rescan,status,inspect,projects,ack}` | Inspect configuration monitoring: list observed config sources (MCP servers, skills, commands, hooks, rules), tail `ai.openlatch.config.*` events from the audit log, force a rescan, report monitor health, drill down on a single source (`inspect`), enumerate observed project roots (`projects`), and acknowledge pending alerts (`ack`). |
|
|
155
|
-
| `openlatch docs` | Open documentation in browser |
|
|
156
|
-
|
|
157
|
-
Noun-verb aliases are also available: `openlatch hooks install` = `init`, `openlatch hooks uninstall` = `uninstall`, `openlatch daemon start` = `start`, etc.
|
|
158
|
-
|
|
159
|
-
#### Persistence
|
|
160
|
-
|
|
161
|
-
`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.
|
|
162
|
-
|
|
163
|
-
### Troubleshooting
|
|
164
|
-
|
|
165
|
-
When something goes wrong, prefer this order:
|
|
166
|
-
|
|
167
|
-
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).
|
|
168
|
-
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.
|
|
169
|
-
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.
|
|
170
|
-
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 `~`.
|
|
171
|
-
|
|
172
|
-
Combined `openlatch doctor --fix --rescue` runs the rescue first to snapshot the pre-fix state, then heals.
|
|
173
|
-
|
|
174
|
-
### Global Flags
|
|
175
|
-
|
|
176
|
-
| Flag | Description |
|
|
177
|
-
| ---- | ----------- |
|
|
178
|
-
| `--json` | Machine-readable JSON output (parseable by `jq`) |
|
|
179
|
-
| `--verbose` / `-v` | Show extra operational detail |
|
|
180
|
-
| `--debug` | Show internal state and timings (implies `--verbose`) |
|
|
181
|
-
| `--quiet` / `-q` | Suppress all output except errors |
|
|
182
|
-
| `--no-color` | Disable colored output |
|
|
183
|
-
|
|
184
|
-
### Exit Codes
|
|
185
|
-
|
|
186
|
-
| Code | Meaning |
|
|
187
|
-
| ---- | ------- |
|
|
188
|
-
| 0 | Success |
|
|
189
|
-
| 1 | Security findings detected |
|
|
190
|
-
| 2 | Usage error (invalid arguments) |
|
|
191
|
-
| 3 | Resource not found |
|
|
192
|
-
| 4 | Permission denied |
|
|
193
|
-
| 5 | Conflict |
|
|
194
|
-
| 130 | Interrupted (Ctrl+C) |
|
|
195
|
-
|
|
196
|
-
### Binaries
|
|
197
|
-
|
|
198
|
-
OpenLatch ships two binaries:
|
|
199
|
-
|
|
200
|
-
- **`openlatch`** (<30MB) — full CLI for setup, daemon management, and log viewing.
|
|
201
|
-
- **`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.
|
|
202
|
-
|
|
203
|
-
## How It Works
|
|
204
|
-
|
|
205
|
-
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:
|
|
41
|
+
## How it works
|
|
206
42
|
|
|
207
43
|
```
|
|
208
44
|
┌─────────────────────────────────────────────────────────────────┐
|
|
209
|
-
│
|
|
45
|
+
│ Developer's machine │
|
|
210
46
|
│ │
|
|
211
47
|
│ ┌──────────┐ hook event ┌──────────────────────────────┐ │
|
|
212
|
-
│ │
|
|
213
|
-
│ │
|
|
214
|
-
│ │ │
|
|
215
|
-
│ │ │
|
|
216
|
-
│ │ │
|
|
217
|
-
│ │ │
|
|
218
|
-
│ │ │ ◀─ verdict
|
|
219
|
-
│ └──────────┘
|
|
220
|
-
│ │ 5. Batch → forward
|
|
221
|
-
│ │ ◀── policy bundle
|
|
222
|
-
│ └──────────────────────────────┘ │
|
|
48
|
+
│ │ Coding │──────────────▶│ OpenLatch client │ │
|
|
49
|
+
│ │ agent │ │ (127.0.0.1) │ │
|
|
50
|
+
│ │ │ │ │ │
|
|
51
|
+
│ │ │ │ 1. Wrap in envelope │ │
|
|
52
|
+
│ │ │ │ 2. Evaluate resident │ │
|
|
53
|
+
│ │ │ │ policy in-process │ │
|
|
54
|
+
│ │ │ ◀─ verdict ──│ 3. Redact credentials │ │
|
|
55
|
+
│ └──────────┘ │ 4. Write local audit log │ │
|
|
56
|
+
│ │ 5. Batch → forward │────┼──▶ OpenLatch platform
|
|
57
|
+
│ │ ◀── policy bundle │◀───┼── (policies, analysis,
|
|
58
|
+
│ └──────────────────────────────┘ │ dashboard)
|
|
223
59
|
└─────────────────────────────────────────────────────────────────┘
|
|
224
60
|
```
|
|
225
61
|
|
|
226
|
-
**
|
|
227
|
-
|
|
228
|
-
- **
|
|
229
|
-
- **
|
|
230
|
-
- **Privacy-first** — credentials and secrets are redacted locally via regex-based filtering before anything leaves your machine.
|
|
231
|
-
- **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.
|
|
232
|
-
|
|
233
|
-
## Updating openlatch
|
|
234
|
-
|
|
235
|
-
`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.
|
|
236
|
-
|
|
237
|
-
```bash
|
|
238
|
-
# Disable the worker (env or config):
|
|
239
|
-
export OPENLATCH_AUTO_UPDATE=false
|
|
240
|
-
# or, persistently:
|
|
241
|
-
echo -e "[update]\nauto_update = false" >> ~/.openlatch/config.toml
|
|
242
|
-
```
|
|
243
|
-
|
|
244
|
-
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.
|
|
62
|
+
- **Inside the agent, not a proxy in front of it.** The decision point is the agent's own hook lifecycle, so it sees the *action* rather than the traffic. Model calls additionally pass through a loopback listener, so cost and token usage are measured on the same host.
|
|
63
|
+
- **Local-authoritative.** The resident policy bundle is the authority, not a cache of one. Evaluation reads an in-memory handle and returns.
|
|
64
|
+
- **Fail-static, not fail-open.** A resident bundle keeps enforcing offline, forever. A failed refresh keeps the last known good.
|
|
65
|
+
- **Privacy-first.** Credentials are redacted locally before anything leaves the machine.
|
|
245
66
|
|
|
246
|
-
|
|
67
|
+
## What a verdict does
|
|
247
68
|
|
|
248
|
-
|
|
249
|
-
# Probe the registry; never modifies anything.
|
|
250
|
-
openlatch update --check --json
|
|
69
|
+
The verdict vocabulary is **Allow, Ask, Block or Optimize**. What this client can express today is narrower than the vocabulary, and this is the honest map of it. A verdict is deterministic because an explicit policy produced it.
|
|
251
70
|
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
71
|
+
| Verdict | On the wire / in the bundle | What this client does today |
|
|
72
|
+
| ------- | --------------------------- | ------------------------- |
|
|
73
|
+
| **Allow** | `allow`, `approve` | The action proceeds. `approve` is a user-confirmed allow |
|
|
74
|
+
| **Ask** | No wire variant — an `allow` / `approve` carrying `context` | Rendered to Claude Code as `permissionDecision: "ask"`, the alert as its reason. It **allows and flags**; it does not hold the agent waiting on a human. It prevents recurrence, not the first occurrence |
|
|
75
|
+
| **Block** | `deny` — the only action a `kind=command` rule may take | Reaches the agent as a native deny at `pre_tool_use`, naming the rule that produced it |
|
|
76
|
+
| **Optimize** | `kind=request` rules: `prefix_reorder`, `history_trim`, `prompt_edit` | **Measurement only.** Out of the box the boundary observes, reports what a transform *would* have saved, and forwards the original bytes |
|
|
255
77
|
|
|
256
|
-
|
|
78
|
+
Each rule runs in Monitor (record the match, allow the action) or Enforce (apply the verdict). Most restrictive wins across matching rules.
|
|
257
79
|
|
|
258
|
-
|
|
80
|
+
## Supported agents
|
|
259
81
|
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
82
|
+
| Agent | Control level | Notes |
|
|
83
|
+
| ----- | ------------- | ----- |
|
|
84
|
+
| **Claude Code** | **Enforced** | macOS, Windows and Linux, across its 12 lifecycle hook events. Verdicts are delivered in the agent's own hook-output shape |
|
|
85
|
+
| Cursor · Windsurf · GitHub Copilot · Codex CLI · Gemini CLI · Cline · OpenClaw | Recognised | Their events store and attribute correctly; `init` cannot install their hooks yet |
|
|
263
86
|
|
|
264
|
-
|
|
87
|
+
Making an agent **Enforced** is a hook binding plus a verdict translator. Both are contributions we welcome — see [Contributing](#contributing).
|
|
265
88
|
|
|
266
|
-
##
|
|
89
|
+
## Behind a corporate proxy
|
|
267
90
|
|
|
268
|
-
|
|
91
|
+
`init` finds the route on its own: it probes what is already configured, then walks the OS's own proxy settings (Windows, macOS, GNOME), and only asks if none of them reach the platform. Kerberos/Negotiate uses the logged-on identity; a TLS-inspecting proxy needs only its root CA in `ca_bundle`. Proxy credentials go to the OS keychain, never to a file.
|
|
269
92
|
|
|
270
93
|
```bash
|
|
271
|
-
|
|
272
|
-
#
|
|
273
|
-
# 2. Environment variables (OPENLATCH_*)
|
|
274
|
-
# 3. User config (~/.openlatch/config.toml)
|
|
275
|
-
# 4. Defaults
|
|
94
|
+
openlatch init --proxy http://proxy.corp:8080 --ca-bundle /etc/ssl/corp-root.pem
|
|
95
|
+
openlatch proxy test # walks the chain hop by hop and names the failing one
|
|
276
96
|
```
|
|
277
97
|
|
|
278
|
-
|
|
279
|
-
| -------------------- | ----------- | ------- |
|
|
280
|
-
| `OPENLATCH_API_KEY` | Your OpenLatch API key | — |
|
|
281
|
-
| `OPENLATCH_API_URL` | Cloud API base URL. Callers append `/api/v1/...` path segments. | `https://app.openlatch.ai` |
|
|
282
|
-
| `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` |
|
|
283
|
-
| `OPENLATCH_LOG` | Logging verbosity (`error` / `warn` / `info` / `debug` / `trace`) | `info` |
|
|
284
|
-
| `OPENLATCH_DIR` | State directory — config, logs, outbox, daemon port/token. Override to run a second isolated instance. | `~/.openlatch` |
|
|
285
|
-
| `OPENLATCH_PORT` | Local daemon port. `init` binds this exact port and fails with OL-1500 if it is taken; unset, it probes 7443-7543 for the first free one. | `7443` |
|
|
286
|
-
| `OPENLATCH_SKIP_KEYRING` | Treat the OS keychain as unavailable, so `OPENLATCH_API_KEY` is used instead. The credential chain is keychain → env var → encrypted file, so a stale keychain entry otherwise wins over the env var. | unset |
|
|
287
|
-
| `OPENLATCH_CLOUD_ENABLED` | Set to `false` to stop forwarding events to the cloud | `true` |
|
|
288
|
-
| `OPENLATCH_CLOUD_BATCH_MAX_EVENTS` | Events per ingest batch. Clamped to `1..=100`; `1` restores one POST per event. | `50` |
|
|
289
|
-
| `OPENLATCH_CLOUD_BATCH_MAX_WAIT_MS` | Flush deadline, anchored to the first buffered event | `5000` |
|
|
290
|
-
| `OPENLATCH_POLICY_ENABLED` | Local policy evaluation. Set to `false` to opt out — a complete off switch, not observe mode. | `true` |
|
|
291
|
-
| `OPENLATCH_BOUNDARY_ENABLED` | Model-boundary listener (the loopback proxy that captures model-call economics + attribution). Set to `false` to stop binding the pinned loopback port. While enabled, the daemon points the agent at the listener via `ANTHROPIC_BASE_URL` — but only once a synthetic request has proven the listener can actually reach the provider, and it removes the pointer again if that stops being true. Being wired disables Claude Code Remote Control. | `true` |
|
|
292
|
-
| `OPENLATCH_BOUNDARY_UPSTREAM` | Where the boundary forwards. Every model call and every provider credential on this host goes here, so change it only for a local harness or a deliberate gateway. | `https://api.anthropic.com` |
|
|
293
|
-
| `OPENLATCH_INVENTORY_ENABLED` | Configuration-plane monitoring (MCP servers, skills, rules, hooks) | `true` |
|
|
294
|
-
| `OPENLATCH_TELEMETRY_DISABLED` | Set to `1` to opt out of anonymous usage telemetry | unset |
|
|
295
|
-
| `OPENLATCH_NPM_REGISTRY` | npm registry origin used by `openlatch update` (override for testing) | `https://registry.npmjs.org` |
|
|
296
|
-
| `OPENLATCH_UPDATE_CHECK` | Set to `false` to disable the daemon's startup version check | `true` |
|
|
297
|
-
| `OPENLATCH_AUTO_UPDATE` | Set to `false` to disable the background auto-update worker | `true` |
|
|
298
|
-
| `OPENLATCH_UPDATE_CHECK_INTERVAL_SECS` | Worker poll cadence (E2E override; production keeps the default) | `21600` (6h) |
|
|
299
|
-
| `OPENLATCH_UPDATE_QUIET_WINDOW_SECS` | Seconds of hook silence required before a non-critical apply | `60` |
|
|
300
|
-
| `OPENLATCH_UPDATE_MAX_DEFER_SECS` | Hard cap on cumulative deferral before applying anyway | `86400` (24h) |
|
|
301
|
-
| `OPENLATCH_CLOUD_OUTBOX_MAX_BYTES` | Cap on `~/.openlatch/outbox.jsonl` size before drop-oldest eviction (0 disables) | `104857600` (100 MB) |
|
|
302
|
-
| `OPENLATCH_CLOUD_FALLBACK_MAX_BYTES` | Cap on `~/.openlatch/logs/fallback.jsonl` size before drop-oldest via offset advance (0 disables) | `52428800` (50 MB) |
|
|
98
|
+
The hosts to open, every `[proxy]` key and every `OL-122x` code: [docs/egress.md](docs/egress.md).
|
|
303
99
|
|
|
304
|
-
##
|
|
100
|
+
## Configuration
|
|
305
101
|
|
|
306
|
-
|
|
102
|
+
`openlatch init` writes `~/.openlatch/config.toml`, and every key has an `OPENLATCH_*` environment variable that overrides it. Precedence is CLI flags → environment → `config.toml` → defaults. The full list is in [docs/configuration.md](docs/configuration.md).
|
|
307
103
|
|
|
308
|
-
|
|
309
|
-
- **Private vulnerability reporting** enabled on this repository
|
|
310
|
-
- All releases are built with **SLSA provenance** via GitHub Actions
|
|
311
|
-
- See [SECURITY.md](SECURITY.md) for our full security policy
|
|
104
|
+
## Documentation
|
|
312
105
|
|
|
313
|
-
|
|
106
|
+
| Where | What |
|
|
107
|
+
| ----- | ---- |
|
|
108
|
+
| [openlatch.ai/docs](https://openlatch.ai/docs/) | Installation, getting started, how it works, FAQ, privacy |
|
|
109
|
+
| [docs/configuration.md](docs/configuration.md) | Environment variables, `config.toml`, what the daemon writes into the agent's config |
|
|
110
|
+
| [docs/egress.md](docs/egress.md) | Proxies, the hosts to open, Kerberos, troubleshooting codes |
|
|
111
|
+
| [docs/cli.md](docs/cli.md) | Command reference, health reports, exit codes |
|
|
112
|
+
| [docs/evaluate-protocol.md](docs/evaluate-protocol.md) | Evaluation process frames, caller-owned session state, errors and diagnostics |
|
|
113
|
+
| [CHANGELOG.md](CHANGELOG.md) | What changed in each release |
|
|
314
114
|
|
|
315
|
-
|
|
115
|
+
## Contributing
|
|
316
116
|
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
117
|
+
```bash
|
|
118
|
+
git clone https://github.com/OpenLatch/openlatch-client && cd openlatch-client
|
|
119
|
+
cargo build # Rust 1.88+, no other prerequisites
|
|
120
|
+
cargo test
|
|
121
|
+
```
|
|
321
122
|
|
|
322
|
-
|
|
323
|
-
major bump means a breaking change to the events exchanged between the client
|
|
324
|
-
and the platform — and nothing else. Pin them independently of the client
|
|
325
|
-
version; they carry no dependency on it.
|
|
123
|
+
Never run a development build against your own install: `openlatch init` rewires every live agent session on the host. The [Contributing Guide](.github/CONTRIBUTING.md) covers the sandbox that prevents it, the checks CI runs, Conventional Commits and the PR process; [AGENTS.md](AGENTS.md) states what the client does and what it deliberately does not.
|
|
326
124
|
|
|
327
|
-
|
|
328
|
-
from Conventional Commits. Contributor-facing details are in
|
|
329
|
-
[AGENT.md](AGENT.md#releasing--two-independent-version-lines).
|
|
125
|
+
Pick a [good first issue](https://github.com/OpenLatch/openlatch-client/labels/good%20first%20issue), or join us on [Slack](https://openlatch.slack.com).
|
|
330
126
|
|
|
331
|
-
##
|
|
332
|
-
|
|
333
|
-
We welcome contributions! Whether it's bug fixes, new agent integrations, or documentation improvements.
|
|
127
|
+
## Security
|
|
334
128
|
|
|
335
|
-
-
|
|
336
|
-
-
|
|
337
|
-
-
|
|
129
|
+
- Report vulnerabilities to **security@openlatch.ai**; private vulnerability reporting is enabled on this repository
|
|
130
|
+
- Releases are built with SLSA provenance via GitHub Actions
|
|
131
|
+
- Full policy: [SECURITY.md](SECURITY.md)
|
|
338
132
|
|
|
339
133
|
## License
|
|
340
134
|
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
## Links
|
|
344
|
-
|
|
345
|
-
| Resource | URL |
|
|
346
|
-
| -------- | --- |
|
|
347
|
-
| Website | [openlatch.ai](https://openlatch.ai) |
|
|
348
|
-
| Documentation | [docs.openlatch.ai](https://docs.openlatch.ai) |
|
|
349
|
-
| Slack | [openlatch.slack.com](https://openlatch.slack.com) |
|
|
350
|
-
| Twitter / X | [@openlatch](https://x.com/openlatch) |
|
|
351
|
-
| GitHub | [github.com/OpenLatch](https://github.com/OpenLatch) |
|
|
135
|
+
This client is licensed under [Apache-2.0](LICENSE). The OpenLatch platform — policy authoring, analysis and the dashboard — is a commercial product; see [openlatch.ai](https://openlatch.ai).
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@openlatch/client",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "OpenLatch runtime enforcement node — the capture-and-enforce
|
|
3
|
+
"version": "0.3.3",
|
|
4
|
+
"description": "OpenLatch runtime enforcement node — the capture-and-enforce adapter that evaluates every covered action against a coding agent's Autonomy Zone before it runs",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"repository": {
|
|
7
7
|
"type": "git",
|
|
@@ -20,10 +20,10 @@
|
|
|
20
20
|
"postinstall": "node lib/postinstall.js"
|
|
21
21
|
},
|
|
22
22
|
"optionalDependencies": {
|
|
23
|
-
"@openlatch/client-darwin-arm64": "0.
|
|
24
|
-
"@openlatch/client-darwin-x64": "0.
|
|
25
|
-
"@openlatch/client-linux-x64": "0.
|
|
26
|
-
"@openlatch/client-linux-arm64": "0.
|
|
27
|
-
"@openlatch/client-win32-x64": "0.
|
|
23
|
+
"@openlatch/client-darwin-arm64": "0.3.3",
|
|
24
|
+
"@openlatch/client-darwin-x64": "0.3.3",
|
|
25
|
+
"@openlatch/client-linux-x64": "0.3.3",
|
|
26
|
+
"@openlatch/client-linux-arm64": "0.3.3",
|
|
27
|
+
"@openlatch/client-win32-x64": "0.3.3"
|
|
28
28
|
}
|
|
29
29
|
}
|