Configuration File

The configuration file is kapsl.toml. kapsl looks for it in:

Override the path with KAPSL_CONFIG:

KAPSL_CONFIG=./kapsl.toml kapsl python --version

If the file does not exist, kapsl uses built-in defaults.

Full example

[global]
forward_ssh_agent = true
mount_git_config = true
protected_dotfiles = ["~/.ssh", "~/.gnupg", "~/.aws"]
# pass_env is ADDITIVE to the built-in defaults (RUST_LOG, NO_COLOR, TZ, CI,
# PYTHONUNBUFFERED, ...) — you do not need to restate those. Prefer naming
# variables exactly; a glob like "AWS_*" sweeps in credentials, and
# HTTP_PROXY can carry them in its URL.
pass_env = ["MYAPP_PROFILE"]
k8s_namespace = "tools"

[tools]
rg = "kapsl.sh/rg:latest"
python = { image = "kapsl.sh/python:3.12", command = "python3" }
# per-tool pass_env: additive to [global], and the opt-in for a protected var
aws-cli = { image = "kapsl.sh/aws-cli:latest", pass_env = ["AWS_SECRET_ACCESS_KEY"] }

[theme]
enabled = true

[global] section

Freshness

kapsl has no update or upgrade command — by design. A tool named without a pinned digest is expected to stay current automatically. Tags like python:3.13 and nmap:latest float forward on every upstream rebuild, so a cached image goes stale unless something re-checks the registry.

image_max_age_secs (default 604800, i.e. 7 days) is that something. When a run resolves an image that is already local but was pulled more than the window ago, kapsl best-effort re-pulls it before scanning and running:

• Best-effort: if the refresh pull fails (no network, registry down), kapsl uses the cached image and continues — the freshness window is a convenience, never a blocker. The vulnerability scan remains the security backstop.
• Never refreshed: digest-pinned images (tool@sha256:…, set via kapsl.toml) are immutable by construction, and locally-built environment images (kapsl-env-*) exist in no registry. Only registry-hosted floating tags refresh.
• A failed scan also triggers a refresh: if a scan finds CRITICAL vulnerabilities in a floating tag, kapsl re-pulls the newest version once and, if the image ID changed (the tag was rebuilt), re-scans it — a rebuild may have fixed the issue. If the tag hadn't moved, or the refresh failed, the scan failure stands and the run is blocked.

Set image_max_age_secs = 0 to check for a newer image on every run (slower, maximally current). Set it to a very large value to effectively disable the window.

The same idea applies to the index itself: index_max_age_secs (default 86400, i.e. 1 day) governs the scheduled check of index.json/policy.json — the data --search, --info, and tool resolution all read. The schedule is keyed on the last check, not the last download: kapsl sends the cached copy's ETag (a conditional GET), an unchanged host answers 304 and costs nothing, and only a genuinely new version is downloaded. A failed check retries on the same schedule rather than on every run. This check never delays the command it's attached to: it's bounded to a few seconds and simply abandoned — falling back to whatever's cached — if it hasn't finished by the time the run would otherwise be done.

One schedule runs tighter: a tool name that resolves nowhere triggers a check before the error, at most once every 30 minutes, since a newly published index entry is usually the reason the name was missing. Skipped entirely with --offline.

Unknown keys are rejected with an error — see Config Validation.

[theme] section

kapsl's own terminal branding: the orange left-bar status lines (always on, host-side, not configurable here — see the security docs), plus a colored PS1 and man-page (less/groff) color scheme injected into every container.

Both the default PS1 and the kapsl status lines automatically degrade for the terminal they're running in: truecolor (COLORTERM=truecolor/24bit) or a widely-supported 256-color fallback otherwise, and the ▍ bar glyph or a plain \| when the host locale (LANG/LC_ALL) isn't UTF-8.

[tools] section

Maps tool names to container images. See Tool Mappings for the full syntax.

[tools]
rg = "kapsl.sh/rg:latest"
python = { image = "kapsl.sh/python:3.12", command = "python3" }

[package_providers] section

User-defined package providers, so you can teach kapsl a package manager without a code change. Each entry is a pair of templated install commands; kapsl wraps them in the same build path a built-in provider uses (same base image, scan gate, and cache). See Custom Providers for the full model and worked examples.

[package_providers.mypm]
install_command_inline = "RUN mypm install {packages}"
install_command_file   = "RUN mypm install -r /tmp/{file}"

The provider name (the table key) must be ASCII alphanumeric and may not shadow a built-in (pip, npm, apk, …). Both are enforced at load time, along with the placeholder presence — a typo'd template fails loudly rather than silently installing nothing.

[dev] section

Settings for working on kapsl rather than with it. Everything here changes where kapsl gets its own data from, so everything here prints a warning on every run.

[dev]
index_dir = "/Users/you/src/kapsl/kapsl-index"

Point index_dir at a checkout's kapsl-index/ and your own index edits take effect immediately, with no publish step. kapsl --update does not refresh it, and it is under no obligation to match the published catalogue — a tool that resolves for you may not exist for anyone else.

Why it warns every single run, and why that is not excessive. The index decides which image every tool name resolves to, so an overridden one can point kapsl python anywhere. The alternative people reach for instead — a symlink at ~/.cache/kapsl/index/index.json — is invisible, survives forever, and silently outlives the checkout it points into. Both are detected and both warn:

▍  WARNING    [dev] index_dir is NOT managed by kapsl — it resolves to
              /Users/you/src/kapsl/kapsl-index. It will not be refreshed, and
              may not match the published catalogue.

The failures this prevents all have the same shape — kapsl reading a different file than you believe it is reading — and they surface a long way from the cause. Real examples: hours of edits to an index that was never being read because the symlink pointed at a different checkout; a "verification" that passed against the wrong file and confirmed nothing; and a catatonit: failed to exec pid1 that named neither the index nor the version involved. A warning you only see once you already suspect the index is worth nothing.

KAPSL_INDEX_DIR

Environment override for the same directory, taking precedence over [dev] index_dir:

KAPSL_INDEX_DIR=/path/to/kapsl-index kapsl python --version

It exists for test suites and CI, which must not depend on whatever happens to be in a developer's cache. kapsl's own integration tests set it to the checkout's kapsl-index/, so a run resolves against the tree it was built from and nothing else — the same commit then passes or fails identically on every machine, and an index change is exercised by the suite in the commit that makes it.

It warns like any other override, naming KAPSL_INDEX_DIR as the source so a reader knows to look at the environment rather than the config file.

KAPSL_INDEX_URL

Environment override for the index host — where index.json and policy.json are fetched FROM (as opposed to KAPSL_INDEX_DIR, which changes where they are read from):

KAPSL_INDEX_URL=http://localhost:8080 kapsl --update

The value is a base URL; the artifacts are requested at <base>/index.json and <base>/policy.json. It exists for the same reason as KAPSL_INDEX_DIR — test suites and CI — so a suite can stand up a local index server and exercise fetching, version changes, and the conditional-GET path against it instead of the published https://index.kapsl.sh.