Offline Mode

--offline (or [global] offline = true for a permanently offline host) runs kapsl with no host-side network activity at all: no image pulls, no freshness refreshes of a stale floating tag, no scanner-image pulls, no vulnerability-database build, no catalogue fetch, no VEX fetch. Only what is already cached locally is used.

$ kapsl --offline [email protected] script.py

# kapsl.toml
[global]
offline = true

What changes

• Image pulls. A cached image is used as-is — no best-effort freshness refresh is even attempted. An image that is not cached at all fails immediately with a clear error, rather than hanging on an unreachable registry.
• Vulnerability scanning. The scan still runs — against the cached vulnerability database (GRYPE_DB_AUTO_UPDATE=false), and the scanner container itself has no network, online or off: a scan never fetches, so the instrument cannot change underneath the measurement. A scan that can run offline still denies, prompts and notifies on known CVEs, exactly as online. What offline changes is the failure shape when the scan cannot run:
  • no vulnerability database cached at all → the run fails: "a scan with no database finds nothing, which is indistinguishable from a clean result. Run once without --offline."
  • database cached but the scanner image is not → the run is unscanned, and kapsl asks before proceeding (and, with no TTY, fails — there is nobody to ask).
• Environment builds. A cached environment is used as-is. Building a new environment — a package combination never installed before — fails fast, because installing packages needs network, rather than starting a build that would die confusingly partway through.
• kapsl --update is rejected outright when --offline is also passed: refreshing the catalogue is a network operation.

What is unaffected

--offline only governs kapsl's own host-side network use. It has no effect on the container's network access — that is still controlled by the tool's declared capabilities and --cap net, same as always. A tool that needs network at runtime (git clone, curl) still needs --cap net regardless of --offline.

Preparing a sealed machine

Run once, without --offline, to populate exactly what the offline runs will need: pull the images, build the environments you use, and let the scanner cache its image and vulnerability database. Then --offline after that. The failure messages above are the readiness checklist: if an offline run can name a missing image or a missing database, that is the thing to cache next time you are connected.

Typical uses: a host with no connectivity at all, running tools set up while online; CI runners that intentionally block egress except to a small allowlist; a slow connection where you do not want a freshness check on every run.