How kapsl works

These pages are the whole design, in the order it needs to be read. Nothing in kapsl is left unexplained after them — every other page in the docs is a use case built on top of these.

  • How a run works — every step kapsl jq performs, from resolving the name to the container vanishing, and where each decision is recorded.
  • Always current — there is no upgrade command, by design. The three clocks that keep a tool current, and why that is a security mechanism, not a convenience.
  • The catalogue — the one signed document that maps a tool name to its declared security boundary, and the index at index.kapsl.sh that presents it.
  • The security model — the zero-trust defaults: no network, a read-only view of your directory, nothing readable that it shouldn't be — and how each boundary is enforced.
  • Scanned before it runs — the tool and the packages you asked for are scanned before first run. What the scan covers, the three bands of policy, and what the index already verified before you ever pulled the image.

After these pages you should be able to answer:

  • What exactly happens between typing kapsl python and Python starting — and where each decision is recorded.
  • Why a tool stays at the current version without anyone running an update, and what you give up when you pin a digest instead.
  • Where the answer to "may this tool use the network" lives, and who is allowed to change it.
  • What a container may read of your machine, and why ~/.ssh lists as empty instead of missing.
  • What kapsl python:requests is scanned for before requests ever runs, and what an answer of y at a findings prompt does.

Pages in this section

  • How a run works Every step one invocation performs, from name resolution to the container vanishing.
  • Always current No upgrade command, by design: the three clocks that keep a tool current, and the CVE-heal loop.
  • The catalogue The one signed document that maps a tool name to its declared security boundary, and the index that presents it.
  • The security model Zero-trust defaults and defence in depth: the CWD is the only world, your keys are not on the table, syscalls are policed, and every relaxation is explicit.
  • Scanned before it runs The composed set — the tool and the packages you asked for — is vulnerability-scanned before first run. CRITICAL findings stop and ask.