v0.3A Lock of the Lock Family · open source · Apache 2.0

Your agent runs the command. You hold the key.

Any AI agent, run confined, can run commands on your servers over SSH without ever holding the key. Allow-listed commands run at once, the rest waits for you, and the output comes back masked.

Set it up in your project
lox init
lox add lockssh
lox run

lockssh v0.3 takes lockhub’s lox v0.12.0 or later: an older one does not know it or its confined agents. Docker on Linux or macOS; brew install davidgodefroid/tap/lockfamily installs both and cosign v2.5.0 or later, which lox verifies every image with; or the launcher of the install guide.

Part of the Lock Family: one hub (lox run) approves for every Lock.

lockssh · profile weblox run · default rules

systemctl status nginx
freeallow rule systemctl status *Runs at once. A client address in the output comes back as ⟦ip:9K2QF7XM3RDA⟧.
systemctl restart nginx
askedno allow rule, exec = trueA signed ticket: it runs once, for that agent and that argv.
rm -rf /var/log/nginx
refusedno allow rule, exec = falseE_NOT_ALLOWED: nothing runs.

Approved · y

What never leaves the console

The SSH key or password, the connection, and any output before it is masked.

Three requests on one profile, and what happens to each with the default rules.

See it run

An agent checks nginx on web1 through lockssh. systemctl status and journalctl match allow rules and run at once; the client address in the log comes back masked. The restart matches no allow rule: lox run shows the ticket, the human types y, and the agent runs it once. The SSH key stays in the lockssh console.
An agent (here Claude Code) checks nginx on web1. The status and the logs match allow rules and run at once; the restart waits for your y in lox run, then runs once.

What the agent gets

The agent sends an argv, never a command line. lockssh_run with ["journalctl", "-u", "nginx", "-n", "2", "--no-pager"] answers:

{
  "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.

A failing command is a result, not an error: its exit status and its stderr, masked like stdout.

Why lockssh?

An agent is good at the routine checks on a server: is the service up, what do the last errors say, is the disk full.

Giving it an SSH key gives it a shell: every command, every file the account can read, and the key itself to copy.

lockssh keeps the key and the connection in a console of yours, runs the commands you allowed, and asks you about the rest.

An agent with an SSH key compared with lockssh
PropertyAgent holds the keylockssh
Agent never holds the key, the password or the connectionNoYes
Agent cannot inject shell syntaxNoYes
Only the commands you allowed run unaskedNoYes
Anything else waits for you, then runs onceNoYes
Output masked before the model sees itNoYes
Host keys trusted only by youNoYes
No port, agent or X11 forwardingNoYes
Append-only audit of every commandNoYes

The agent runs what you allowed. The key stays with you.

Highlights

  • One key holder

    The key or password lives in the console’s account (mode 0600). A passphrase is asked at start or read from Vault. Never in the agent’s account, a result, an error or the audit.

  • Allow rules, no prompt

    systemctl status *, journalctl -u * -n * --no-pager: a command an approved rule matches runs at once. The program is always literal.

  • The rest, approved

    Anything else is refused or, with exec = true, becomes a signed ticket you decide in lox run. It runs once, for that agent, that argv, that policy.

  • No shell

    Every argument is quoted: ;, |, $(...) stay literal. Globs never match an option you did not write or climb out with ...

  • Masked output

    stdout and stderr are capped, then masked: emails, public IPs, cards, IBANs, phones, secrets. Clear output needs your switch and a ticket.

  • Pinned host keys

    A host key the console has never seen is trusted only on your answer; a changed key is always refused.

  • Bounded runs

    One SSH session per command: no PTY, no stdin, no forwarding. A timeout (30 s by default) and an output cap per stream.

  • Audit for you only

    Every request, refusal, decision and run goes to an append-only, hash-chained log in the console account, with the command masked and never its output.

Quick start

  1. Install the lockssh launcher and lockhub’s lox v0.12.0 or later and cosign v2.5.0 or later, or all three with brew install davidgodefroid/tap/lockfamily (install guide). Docker must be running.

  2. In your project, write a lockfamily.yaml with the hub alone (once):

    lox init
  3. Add an SSH host: host, port, login, key file in the lock’s home, allow rules. Never a secret.

    lox add lockssh
  4. In a terminal of its own, outside any agent, keep lox run open. It starts the console and serves your decisions.

    lox run
  5. Ask your agent: “Is nginx running on web1? Show the last errors.” It calls lockssh_status, then lockssh_run.

lox add wires Claude Code. For Codex, Cursor or Gemini CLI, also run lockssh init codex (or cursor, gemini).

Know the limits

A rule allows a program with arguments; it 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: names, postal addresses and free text reach the agent.

What a command can do is what the SSH account can do: give lockssh an account of its own, with only the rights the allow list needs.