Let your AI agent run commands on your servers
without ever handing it the SSH key.
Quick start · How it works · Docs · Lock Family · Website
lockssh is a Lock of the Lock Family, harness security for AI agents. Allow-listed commands run at once, the rest waits for you, and the SSH key never leaves the console.
It works with any MCP client (Claude Code, Codex, Cursor, Gemini CLI, …) or
through the lockssh CLI, run confined (as lea runs agents).
Note
0.x: flags and the policy format may still change between minor versions. v0.3.0 is the latest release. lox add lockssh and lox run
serving it ship in lockhub v0.11.0
(lockhub#133), and
lockssh v0.3.0's confined agents in v0.12.0; an older lox does not know
lockssh.
- Your agent can do the routine checks: a service's status, recent logs, the disk.
- It never holds the key or the password. A console in its own account and container holds them, and the only SSH connection.
- Only the commands you allowed run without asking you, and the agent's arguments can never inject shell syntax.
- Personal values and secrets are masked before the model sees them, and every command is audited, without its output.
lockssh runs in Docker. It also takes lockhub's lox v0.12.0 or later
(Quick start) and cosign v2.5.0 or later: lox add and
lox run verify every image with cosign. The lockfamily meta formula
installs the whole family, lockssh, lox and cosign included. With Homebrew
(Linux or macOS):
brew trust davidgodefroid/tap
brew install davidgodefroid/tap/lockfamilyOr lockssh alone, with lox and cosign (the lockssh formula does not pull
them in):
brew install davidgodefroid/tap/lockssh davidgodefroid/tap/lox cosignThe formula installs the lockssh launcher and pins the release images by
digest, checked with cosign when the formula was bumped. Upgrade with
brew upgrade lockssh, not lockssh update.
Without Homebrew, download the install script from the release you install, read it, then run it with that release:
V=vX.Y.Z
curl -fsSLO "https://raw.githubusercontent.com/DavidGodefroid/lockssh/$V/scripts/install.sh"
less install.sh
LOCKSSH_VERSION=$V sh install.shIt checks the release's cosign signatures and installs the lockssh
launcher, which runs every command in the signed image
ghcr.io/davidgodefroid/lockssh:X.Y.Z, by digest. Install
lockhub's lox v0.12.0 or later
beside it.
lockssh versionprints the launcher's and the image's versions;lockssh updateupdates both.- The release's
-vaultimage adds the pinned Vault CLI forcredentials = "vault"(LOCKSSH_VAULT=1). - Your own build, Windows (WSL 2) and migrating from a host install: docs/docker.md.
It takes lockhub's lox v0.12.0 or later: v0.11.0 is the first that knows
the lockssh lock type
(lockhub#133), and
v0.12.0 the first that supports lockssh v0.3.0's confined agents. The
console runs hub-attached only, and an older lox cannot start it.
-
In your project, write a
lockfamily.yamlwith the hub alone (once):lox init
-
Add an SSH host, guided and applied at once (host, port, login, key file in the lock's home, allow rules; never a secret):
lox add lockssh
It pins the latest signed lockssh release, runs
lockssh profile add,lockssh init claudeandlockssh doctorfor you, declares the lock inlockfamily.yaml, offers to copy your key into the console's home, and shows the lock's review as it starts. Another agent:lockssh init codex,lockssh init cursororlockssh init gemini. -
Keep
lox runopen in a terminal of its own: it starts the console with its hub and serves the decisions.lox run
-
Ask your agent: "Is nginx running on web1? Show the last errors." It calls
lockssh_status, thenlockssh_runwith["systemctl", "status", "nginx"]and["journalctl", "-u", "nginx", "-n", "50", "--no-pager"].
A profile, in .lockssh/config.toml:
[profiles.web]
host = "web1.example.com"
user = "lockssh-ro"
key = "~/.ssh/id_ed25519" # in the console account, never the agent's
allow = ["uptime", "df -h", "systemctl status *", "journalctl -u * -n * --no-pager"]|
🔑 One key holder |
✅ Allow rules, no prompt |
|
👤 The rest, approved |
🚫 No shell, masked output |
lox runstarts the console in its own container, as thelocksshaccount, with an egress to the profile's host only (lockhub v0.12.0 or later, lockhub#133). It shows the profile's policy for approval, logs in over SSH (trusting the host key only on your answer), and checks the account.- The agent's
lockssh mcp(or CLI) runs as another account and reaches the console only through its socket. The console serves it only if it runs confined (in a container, with no reach to the host's container runtime or Lock Family state, as lea runs agents); an agent on the host is refused unless a non-production profile setsunconfined = true(docs/usage.md). - Each request is an argv, matched against the approved allow rules:
- a match runs at once;
- anything else is refused, or becomes a signed ticket on lockhub that you
decide with
lox approve, the lea deck or a paired phone.
- The console runs the command in an SSH session of its own (no PTY, no stdin), bounded in time and output. It masks stdout and stderr, and audits the request.
lockssh_run with ["journalctl", "-u", "nginx", "-n", "2", "--no-pager"]:
{
"command": "journalctl -u nginx -n 2 --no-pager",
"rule": "journalctl -u * -n * --no-pager",
"action": "run",
"exit_status": 0,
"stdout": "[alert] worker process 812 exited on signal 9\n[error] upstream timed out, client: ⟦ip:9K2QF7XM3RDA⟧\n",
"stderr": "",
"duration_ms": 41,
"masked": {"ip": 1}
}The same value gets the same pseudonym for the whole console run, so the agent can still correlate; the next run draws new ones.
Clear output needs your switch in the console and a decided ticket, never an auto rule, except the values a PII allow rule of the approved policy names (never a secret).
What lockssh enforces and what it does not: docs/security-model.md. In short:
- the key, the connection and the policy are the human's;
- a rule allows a program with arguments but cannot know what the program
does with them: never allow
find -exec,sh -c,sudo, editors or pagers with globs; - masking covers what the detectors recognise, not every personal datum.
| Doc | What it covers |
|---|---|
| docs/usage.md | Profiles, allow rules, output, auto rules, the console, commands and MCP tools, refusal codes |
| docs/configuration.md | The company's managed configuration (managed.toml, lockfamily's docs/managed.md): bounds, defaults, managed profiles, lockssh managed show|check |
| docs/docker.md | The image, the launcher, project setup, Vault, wiring each agent, an agent in its own container |
| docs/security-model.md | Parties, what lockssh enforces, what it does not |
| CHANGELOG.md | Release notes |
Every Lock is built on the same console, separation and approval model, and one hub approves for all of them. Start at lockfamily.dev.
| Repo | What it does |
|---|---|
| lockfamily | The family site and install.sh: everything in one install |
| locksql | SQL databases: the agent queries, PII comes back masked; connections and writes wait for you |
| lockmq | RabbitMQ: masked queue inspection; connections, peeks and unmasked reads wait for you |
| lockfile | Files (S3, SFTP, disk): the agent asks yes/no questions about files it never reads |
| lockhttp | Outbound HTTP(S): reads of trusted hosts pass; anything that sends data or reaches an unknown host waits for you |
| locklog | Logs: masked, bounded log search; the agent reads the logs, not the people in them |
| lockssh | Commands over SSH: allow-listed commands run at once, the rest waits for you; the SSH key never leaves the console |
| lockhub | The approval hub and its lox CLI: lox run approves outside the agent's harness |
| lockkit | The shared Go core of every Lock: console, policies, masking, signed tickets, audit, MCP wiring |
| lea | Runs many agents in containers, wired to the Locks |
-
Contributing: see CONTRIBUTING.md. lockssh is built on lockkit; build and test with:
CGO_ENABLED=0 go build ./cmd/lockssh go test ./... go test -tags integration -run TestOpenSSH ./internal/sshconsole/ # OpenSSH in Docker
Requires Go 1.26 or later. The animated demo is generated:
python3 scripts/brand/demo.py > docs/assets/demo.svg. -
Security: report vulnerabilities privately, as SECURITY.md describes.