Install

Install lockssh

lockssh runs in Docker. You install one lockssh command, a launcher that runs every command in the signed release image, and lockhub’s lox, which starts the console and serves your decisions.

Where things stand

lockssh 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 and cannot start its console. lox add lockssh pins the latest signed lockssh release.

lockssh has a Homebrew formula, on Linux and macOS. The lockfamily meta formula installs the whole family, lockssh, lockhub’s lox and cosign included. The lockssh formula alone pulls in neither lox nor cosign: name them with it.

lockssh, with Homebrew
brew trust davidgodefroid/tap
brew install davidgodefroid/tap/lockfamily   # or lockssh alone, with lox and cosign: brew install davidgodefroid/tap/lockssh davidgodefroid/tap/lox cosign

Homebrew asks you to trust a third-party tap once. Upgrade with brew upgrade lockssh. Without Homebrew, install the launcher, below.

Requirements

  • Docker, on Linux or on macOS (Docker Desktop). On Windows, install in WSL 2 with Docker Desktop’s WSL integration and run it there.
  • lockhub’s lox v0.12.0 or later: it starts the console and serves your decisions.
  • cosign v2.5.0 or later on PATH: lox add and lox run verify every image with it, and the install script and lockssh update check the release’s and the image’s signatures.
  • An SSH account for lockssh on each server, with only the rights the allow list needs: a user of its own, no sudo, read access to the logs it must read. Its login shell must be a POSIX shell.

The launcher

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                     # read it first
LOCKSSH_VERSION=$V sh install.sh

It checks the release’s cosign signatures and checksum, and installs the launcher as /usr/local/bin/lockssh (with sudo when needed; LOCKSSH_INSTALL_DIR for another directory).

The launcher runs its release’s image, ghcr.io/davidgodefroid/lockssh:X.Y.Z, by its verified digest, never by a tag that could be moved. Each command runs with the account it needs: the console as lockssh, the agent’s commands as agent, with the socket volume only. What runs where.

lockssh version             # the launcher's version and its image's
lockssh update [vX.Y.Z]     # a new launcher, then docker pull; signatures checked

For credentials = "vault", the release’s -vault image adds the pinned Vault CLI: set LOCKSSH_VAULT=1.

Set up a project

In your project, with lockhub’s lox v0.12.0 or later:

lox init           # a lockfamily.yaml with the hub alone (once)
lox add lockssh    # host, port, login, key file, allow rules; never a secret
lox run            # in a terminal of its own: starts the console, serves the decisions

lox add lockssh 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.

Reach the console’s own questions (the policy review, a new host key, a passphrase) with lox attach NAME, where NAME is the lock’s name; detach with Ctrl-P Ctrl-Q.

An SSH host profile

A profile is one SSH host, in the project’s .lockssh/config.toml, which is yours. It never holds a secret. lox add lockssh writes it through lockssh profile add, which you can also run yourself:

lockssh profile add --profile web --host web1.example.com --user lockssh-ro \
  --key "~/.ssh/id_ed25519" --allow uptime --allow "systemctl status *"
[profiles.web]
host        = "web1.example.com"
port        = 22
user        = "lockssh-ro"
auth        = "key"                # key | password
key         = "~/.ssh/id_ed25519"  # in the console account, never the agent's
credentials = "none"               # key: none | ask | keychain | vault
production  = false
exec        = false                # true: a command outside allow may be asked
allow       = ["uptime", "df -h", "systemctl status *", "journalctl -u * -n * --no-pager"]

[profiles.web.limits]
request_timeout  = "30s"           # a command running longer is killed
max_output_bytes = 65536           # per stream, before masking

The key goes in the console’s home volume, owned by the console account, mode 0600. A passphrase or password is asked by the console at its start (ask) or read from Vault (vault); the container has no OS keychain.

Every key of the profile, the allow-rule syntax and the auto rules are in the usage guide.

Wire your agent

lockssh init codex          # or claude, cursor, gemini; this project
lockssh doctor --fix        # the config, the consoles, .lockssh, the agent wiring

lockssh init writes the MCP command, lockssh mcp, which runs through the launcher in a throwaway container. Any MCP client works, run confined (as lea runs agents); init wires Claude Code, Codex, Cursor and Gemini CLI.

Keep the client’s tool timeouts: the console waits up to 5 minutes for an approval. Start the agent at the project root, or below it.

Your own build

docker build -t lockssh https://github.com/DavidGodefroid/lockssh.git
LOCKSSH_IMAGE=lockssh lockssh version

From a clone, sh scripts/lockssh … runs the image tagged lockssh. An agent in a container of its own, without the Docker socket: the Docker guide.