From 018e1f30d7f6a23d392f7c95dad64cf0966126dd Mon Sep 17 00:00:00 2001 From: DavidG Date: Sun, 15 Nov 2026 13:23:34 +0000 Subject: [PATCH] docs: say lockssh install needs lox and cosign The lockssh formula pulls in neither lox nor cosign, and lox add and lox run verify every image with cosign (v2.5.0 or later). The README, docs/docker.md and the site's install pages now name lox v0.12.0 or later and cosign v2.5.0 or later, lead with the lockfamily meta formula, and give the single-tool line with lox and cosign, as lockfamily#70 does. Co-Authored-By: Claude Opus 5.5 --- README.md | 24 ++++++++++++++++-------- docs/docker.md | 5 ++++- site/index.html | 4 ++-- site/install/index.html | 7 ++++--- 4 files changed, 26 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 29cafbd..af572d3 100644 --- a/README.md +++ b/README.md @@ -57,22 +57,28 @@ through the `lockssh` CLI, run confined (as lea runs agents). ## Install -lockssh runs in Docker. With Homebrew (Linux or macOS): +lockssh runs in Docker. It also takes lockhub's `lox` v0.12.0 or later +([Quick start](#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): ```sh brew trust davidgodefroid/tap -brew install davidgodefroid/tap/lockssh +brew install davidgodefroid/tap/lockfamily ``` -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`. The `lockfamily` meta formula -installs the whole family, lockssh included, with lockhub's `lox`: +Or lockssh alone, with `lox` and cosign (the `lockssh` formula does not pull +them in): ```sh -brew install davidgodefroid/tap/lockfamily +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: @@ -85,7 +91,9 @@ 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. +`ghcr.io/davidgodefroid/lockssh:X.Y.Z`, by digest. Install +[lockhub's `lox`](https://github.com/DavidGodefroid/lockhub) 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 diff --git a/docs/docker.md b/docs/docker.md index 3f2fd27..0edb3c9 100644 --- a/docs/docker.md +++ b/docs/docker.md @@ -42,7 +42,10 @@ on first use: `install.sh` checks the image's cosign signature too (and its `-vault` variant's) and writes the verified digests into the launcher, which runs the image by digest, never by a tag that could be moved. Linux and macOS (Docker Desktop); on Windows, install it in WSL 2 with Docker -Desktop's WSL integration and run it there. +Desktop's WSL integration and run it there. The console also takes +lockhub's `lox` v0.12.0 or later and cosign v2.5.0 or later: `lox add` and +`lox run` verify every image with cosign. The `lockssh` Homebrew formula +pulls in neither; the `lockfamily` meta formula installs both. ```sh lockssh version # the launcher's version and its image's diff --git a/site/index.html b/site/index.html index 27a4e34..ff1a5c7 100644 --- a/site/index.html +++ b/site/index.html @@ -64,7 +64,7 @@

Your agent runs the command. You hold the
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, or the launcher of the install guide.

+

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.

Install guide @@ -161,7 +161,7 @@

Highlights

Quick start

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

  2. +
  3. 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.

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

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

    diff --git a/site/install/index.html b/site/install/index.html index 9467243..a880812 100644 --- a/site/install/index.html +++ b/site/install/index.html @@ -64,12 +64,12 @@

    Install lockssh

    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 and lockhub’s lox included; or install lockssh by name.

    +

    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 davidgodefroid/tap/lockssh alone
    +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.

@@ -78,7 +78,8 @@

Where things stand

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.
  • -
  • cosign on PATH, for the install script and lockssh update: they check the release’s and the image’s signatures.
  • +
  • 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.