Getting started¶
Three steps to a hardened agent loop:
- Run the control plane (Docker)
- Install the CLI
- Wire the CLI into your agent harnesses
1. Run the control plane¶
The control plane is a small Go HTTP service that lives in a Docker container. It evaluates policy, drives install plan/apply, and signs every decision into the ledger.
curl -O https://raw.githubusercontent.com/openagentlock/openagentlock/main/docker-compose.yml
# Optional external guardrails:
# export NVIDIA_API_KEY=...
# export OPENROUTER_API_KEY=...
docker compose up -d
NVIDIA_API_KEY enables the shipped runtime-classifier path. OPENROUTER_API_KEY currently enables OpenRouter catalog discovery only.
docker pull ghcr.io/openagentlock/agentlockd:latest
docker run -d --name agentlock \
-v agentlock-state:/var/lib/agentlock \
-p 127.0.0.1:7878:7878 \
-p 127.0.0.1:7879:7879 \
-e NVIDIA_API_KEY \
-e OPENROUTER_API_KEY \
ghcr.io/openagentlock/agentlockd:latest
The CLI runs on your host and is the only process that touches host configs (~/.claude/settings.json, ~/.codex/hooks.json, ~/.cursor/hooks.json); the daemon never reads or writes there, so no bind mount is needed. State lives in the agentlock-state named volume.
The service binds to 127.0.0.1:7878 (CLI / hook traffic) and 127.0.0.1:7879 (local web dashboard). Neither port should ever be exposed to a non-loopback interface.
Verify it is up:
For a fuller local check after install or when hooks behave unexpectedly, run:
This is read-only. It checks daemon reachability, ledger verification, policy/session APIs, detected harnesses, hook wiring, and whether a hook is pointed at a different daemon URL than the one being checked.
2. Install the CLI¶
Verify:
3. Wire it up¶
This prints a table of every agent harness it found on your machine. Today, end-to-end hooks are wired for Claude Code, Codex CLI, Cursor, and Gemini CLI; other harnesses are detected but the installer flags them as not yet implemented. See Status.
Then pick a signer tier and run install. Two recommended paths:
For ledger-signed entries you need an attested signer (TOTP / hardware key). Install accepts unattested sessions for the file-writing step, but ledger entries from those sessions get the red UNATTESTED banner. Enroll a TOTP signer once, then use it for install:
# 1. one-time enrollment — pick a passphrase, scan the QR with your authenticator
agentlock signer enroll --tier totp --passphrase 'your-passphrase-here'
# the CLI prints an otpauth:// URI; scan it with Google Authenticator,
# 1Password, Authy, Bitwarden, etc.
# 2. install with a TOTP-attested session
agentlock install --tier totp --code 123456 --passphrase 'your-passphrase-here'
# 123456 is the current 6-digit code from your authenticator app.
Ledger entries get the yellow TOTP-BACKED — MEDIUM ASSURANCE banner.
Useful for getting a feel for the install/uninstall flow without setting up a signer. Allow unattested sessions on the daemon:
docker rm -f agentlock
docker run -d --name agentlock \
-e AGENTLOCK_ALLOW_UNATTESTED=1 \
-v agentlock-state:/var/lib/agentlock \
-p 127.0.0.1:7878:7878 -p 127.0.0.1:7879:7879 \
ghcr.io/openagentlock/agentlockd:latest
agentlock install # default tier is unattested
Ledger entries get the red UNATTESTED — LEDGER NOT SIGNED banner. Don't use in prod.
Pick the harnesses to harden, review the diff, confirm. The installer writes harness-specific configuration (e.g. ~/.claude/settings.json hook entries, ~/.codex/hooks.json, plus [features].hooks = true in ~/.codex/config.toml — auto-set on first install, with a backup of the original) and registers a clean rollback path you can invoke later with agentlock uninstall. Codex Desktop is supported through the shared Codex ~/.codex hook files.
For Codex CLI and Codex Desktop, trust the hook after install from Codex CLI: run /hooks, select the OpenAgentLock hook, and press t. Codex Desktop does not expose its own /hooks trust UI.
Open the dashboard at http://127.0.0.1:7879/ to watch live activity. If you'd rather stay in the terminal, agentlock dashboard opens a TUI with the same ledger tail, sessions, gates, and monitor⇄enforce flip.
What happens next¶
Out of the box, the control plane runs in monitor mode: every tool call is logged but nothing is blocked. Use the dashboard to review activity, then flip rules to enforce when you're confident. See Policies and the five gates.
For stronger local signing, macOS can use the shipped OS-keychain signer. Hardware-key signers (YubiKey PIV / FIDO2), Linux Secret Service, and Windows DPAPI remain roadmap. See Signers.