openlatch-provider 0.2.0

Self-service onboarding CLI + runtime daemon for OpenLatch Editors and Providers
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114

# openlatch-provider

> Self-service onboarding CLI + runtime daemon for OpenLatch Editors and Providers.

`openlatch-provider` is the third project in the OpenLatch family, sibling to [`openlatch-client`](https://github.com/OpenLatch/openlatch-client) (agent-side forwarder) and `openlatch-platform` (cloud control plane). It is **two things in one binary**:

| Mode | Trigger | Purpose |
| ---- | ------- | ------- |
| **Management CLI** | One-shot subcommands | Self-service onboarding + lifecycle ops for Editors and Providers |
| **Runtime daemon** | `openlatch-provider listen` | Receive HMAC-signed webhooks from `openlatch-platform`, verify, proxy events to vendor's localhost-hosted detection tools, return verdicts. Also spawns and supervises each binding's tool process per the manifest's `process:` block (one daemon = everything you need to start). Accepts both single-file v1 manifests and v2 `kind: Provider` manifests that compose multiple tool manifests via `tool_paths:` globs. |

## Install

```bash
# npm (recommended)
npx @openlatch/provider --version

# crates.io
cargo install openlatch-provider

# GitHub Releases (signed binaries + shell installer)
curl -fsSL https://openlatch.ai/install.sh | sh
```

Cross-platform: macOS (arm64 + x64), Linux (x64 + arm64), Windows (x64).

## Quickstart

```bash
# 1. Authenticate (browser-based PKCE) — required, init validates slugs against the platform
openlatch-provider login

# 2. Scaffold a new editor + first tool. Each slug you pick is checked
#    against api.openlatch.ai before the manifest is written; collisions
#    re-prompt in TTY or surface as OL-4280..OL-4283 in CI mode.
openlatch-provider init

# 3. Edit openlatch.yaml to declare your tool(s) and provider(s)
$EDITOR openlatch.yaml

# 4. Validate before publishing
openlatch-provider publish --dry-run

# 5. Publish
openlatch-provider publish

# 6. Run the production daemon — it spawns each tool process listed in the
#    manifest's `process:` blocks, waits for /healthz, restarts on crash,
#    and reaps the child tree on Ctrl+C. For multi-tool deployments
#    (e.g. `openlatch-sectools`), pass `--provider <path>` to the v2
#    `kind: Provider` manifest; tool manifests are auto-discovered from
#    its `tool_paths:` globs.
openlatch-provider listen --port 8443
# or for v2 multi-tool:
# openlatch-provider listen --provider ./openlatch-provider.yaml

# 7. Inspect or control the supervised tools (in another terminal —
#    daemon must have been started with `--admin-port <PORT>`).
openlatch-provider tools status --admin-port 8444
openlatch-provider tools logs <slug> --follow
openlatch-provider tools restart <slug>
openlatch-provider tools probe <slug>

# 8. Watch verified events flow through the daemon. Reads
#    ~/.openlatch/provider/logs/runtime-YYYY-MM-DD.jsonl directly, so it
#    works whether the daemon is up or not.
openlatch-provider events tail --follow
```

The daemon emits one `info!` line per processed event to stderr (colored
verdict in TTYs, JSON otherwise). Raise verbosity with `--verbose` /
`--debug` or by exporting `RUST_LOG=…` (standard `tracing-subscriber`
filter syntax).

## Examples

- [`tools/coinflip-tool/`](tools/coinflip-tool/) — a dummy detection tool
  (FastAPI + [`openlatch-tool-sdk`](pypi/tool-sdk/)) that randomly returns
  `allow`/`deny` verdicts. Use it to validate the full
  agent → client → platform → provider → tool pipeline locally; it is
  also exercised deterministically by the
  `openlatch-provider-e2e coinflip` E2E command.

## Status

v0.1.0 — first GA release. Auto-update is enabled by default for
npm-installed binaries (kill switch: `OPENLATCH_NO_AUTO_UPDATE=1`).
See [CHANGELOG.md](CHANGELOG.md) for releases and
[`docs/`](docs/) for the full reference.

## Documentation

- [Quickstart](docs/quickstart.md) — install -> register -> publish in <10 min.
- [`openlatch.yaml` reference](docs/manifest-reference.md)
- [Auth flows](docs/auth.md)
- [Runtime mode](docs/runtime-mode.md) — listen daemon, /v1/health, deploy patterns.
- [Webhook security](docs/webhook-security.md) — HMAC + replay + SSRF defense.
- [Tool authoring guides](docs/tool-authoring/) — Python (FastAPI), Node (Express/Hono), Rust (axum).
- [Deploy](docs/deploy/) — Docker, systemd, Caddy reverse-proxy.
- [CLI reference](docs/cli-reference.md) — every subcommand and flag (auto-generated).
- [Error code catalogue](docs/errors/) — `OL-42xx` codes with remediation steps.

The Rust binary, [`openlatch-tool-sdk`](pypi/tool-sdk/) (PyPI), and
[`@openlatch/tool-sdk`](npm/tool-sdk/) (npm) version in lock-step — one
conventional-commit PR triggers a single release-please Release PR that
bumps all three packages to the same `X.Y.Z`.

## License

Apache-2.0 — see [LICENSE](LICENSE).

## Security

See [SECURITY.md](SECURITY.md).