Skip to content
DavidGodefroidPublic

About

Harness security for AI agents, for SSH: a Lock of the Lock Family. Let your AI agent run commands on your servers without ever handing it the SSH key.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

lockssh: your AI agent runs the command, you hold the key.

CI Latest release License: Apache 2.0 Go version

Let your AI agent run commands on your servers
without ever handing it the SSH key.

An agent (here Claude Code) 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.

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.

Why 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.

Install

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/lockfamily

Or lockssh alone, with lox and cosign (the lockssh formula does not pull them in):

brew install davidgodefroid/tap/lockssh davidgodefroid/tap/lox cosign

The 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.sh

It 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 version prints the launcher's and the image's versions; lockssh update updates both.
  • The release's -vault image adds the pinned Vault CLI for credentials = "vault" (LOCKSSH_VAULT=1).
  • Your own build, Windows (WSL 2) and migrating from a host install: docs/docker.md.

Quick start

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.

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

    lox init
  2. 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 claude and lockssh doctor for you, declares the lock in lockfamily.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 cursor or lockssh init gemini.

  3. Keep lox run open in a terminal of its own: it starts the console with its hub and serves the decisions.

    lox run
  4. Ask your agent: "Is nginx running on web1? Show the last errors." It calls lockssh_status, then lockssh_run with ["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"]

Highlights

🔑 One key holder
The key or password lives in the console's account (mode 0600); a passphrase or password is asked at start or read from Vault. Never in the agent's account, the socket, a result, an error or the audit log.

✅ Allow rules, no prompt
systemctl status *, journalctl -u * -n * --no-pager: a command an allow rule of the approved policy matches runs at once. * and ? never cross /; the program is always literal.

👤 The rest, approved
Anything else is refused or, with exec = true, becomes a signed ticket on lockhub that you decide in lox run, the lea deck or on a paired phone. It runs once, for that agent, that argv, that policy.

🚫 No shell, masked output
Every argument is quoted: ;, |, $(...) stay literal. No PTY, no stdin, no forwarding. stdout and stderr are capped, then masked: emails, public IPs, cards, IBANs, phones, secrets.

How it works

  1. lox run starts the console in its own container, as the lockssh account, 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.
  2. 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 sets unconfined = true (docs/usage.md).
  3. 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.
  4. 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.

What the agent gets

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).

Safety model

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.

Documentation

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

The Lock Family

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 · Security · License

  • 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.

  • License: Apache License 2.0. See LICENSE and NOTICE.

About

Harness security for AI agents, for SSH: a Lock of the Lock Family. Let your AI agent run commands on your servers without ever handing it the SSH key.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages