Offline Mode

--offline (or [global] offline = true for a permanently offline host) runs boks with no host-side network activity at all: no image pulls, no freshness refreshes of a stale floating tag, no scanner-image pulls, no grype DB update, no tool-index fetch. Only what's already cached locally is used.

boks --offline python@3.12 script.py

# boks.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 isn't cached at all fails immediately with a clear error, rather than hanging on an unreachable registry.
Vulnerability scanning. The grype scanner still runs against the already-cached vulnerability database (GRYPE_DB_AUTO_UPDATE=false), so a scan can still deny/prompt/notify on known CVEs. If the scanner image itself isn't cached, the scan is skipped (a warning is printed) rather than blocking the run — the same graceful degrade as scanner-unavailable today, just reached more often under --offline.
Environment builds. A cached environment (boks-env-*) is used as-is. Building a new environment (a package combination never installed before) fails fast — installing packages needs network — rather than starting a podman build that would fail confusingly partway through.
boks --update is rejected outright when --offline is also passed — updating the tool index is inherently a network operation.

What's unaffected

--offline only affects boks's own host-side network use. It has no effect on the container's own network access — that's still controlled independently by --cap net / [tools.<name>] capabilities = ["net"] / image labels, same as always. A tool that itself needs network at runtime (e.g. git clone, curl) still needs --cap net regardless of --offline.

Typical use

A slow connection where you don't want to check for a multi-GB image update on every run.
A host with no connectivity at all, running only tools/environments already set up while online.
CI runners that intentionally block egress except to a small allowlist.

Run once without --offline to populate whatever you'll need (pull the image, build the environment, let the scanner cache its DB), then use --offline afterward.