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
protected_dotfiles = ["~/.ssh", "~/.gnupg", "~/.aws"]
# pass_env is ADDITIVE to the built-in defaults (RUST_LOG, NO_COLOR, TZ, CI,
# POSIXLY_CORRECT, ... — the full list is on the environment-variables page)
# and to whatever the tool's own catalogue entry declares (python gets
# PYTHONUNBUFFERED from its entry, not from you). 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

Precedence

When the same setting is declared in several places, the most specific wins:

[global] section

| index_max_age_secs | int | 86400 | How often the global tool index + policy artifact are checked (a conditional GET — a new version is downloaded only if the host has one). The schedule is the last check, success or not; a name the index doesn't resolve is checked on a separate 30-minute schedule. Same "no --update needed" posture as image_max_age_secs. 0 checks every run; a very large value disables it. See Freshness below. |

Git config. There is no key for this anymore. The ~/.gitconfig mount now comes from the signed catalogue — git's own entry declares it — so it is applied only when git is actually involved (primary, composed, or pulled in by an inline package install), not unconditionally into every container. The old [global] mount_git_config key no longer exists; a typo'd key is rejected at load time, which is how the removal is enforced.

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 Validation below.

[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. Two forms — the bare image string, or a table with the full field set:

[tools]
rg = "kapsl.sh/rg:latest"                              # simple form
python = { image = "kapsl.sh/python:3.12", command = "python3" }
aws-cli = { image = "kapsl.sh/aws-cli:latest", pass_env = ["AWS_SECRET_ACCESS_KEY"] }

The full mapping syntax — env files, version lines, groups — is Tool Mappings.

seccomp

The values are the ones kapsl --info <tool> prints, so what you read there is what you write here:

Most tools need nothing here: the catalogue declares a class and kapsl enforces it. This exists for the case where that classification is wrong for you — a net-denied tool you genuinely use over the network. An entry needs no image alongside it, so overriding a class does not pin a version: gawk = { seccomp = "net-listen" }.

There is deliberately no CLI flag for this. Relaxing a confinement boundary should cost opening a file someone can review. It also means an exploited tool cannot reach it: config is read on the host before the container exists.

system_paths

Some tools find their data at an absolute path compiled in at build time, which no relocation of the image's prefix can satisfy. autoconf hardcodes /usr/share/autoconf; move its binaries to a kapsl prefix and it dies in BEGIN, before its own code runs. system_paths declares the exposure and the run honours it:

[tools]
autoconf = { system_paths = [{ from = "{prefix}/share/autoconf", at = "/usr/share/autoconf" }] }

• from is a DIRECTORY inside the tool's own image. {prefix} expands to the image's own install prefix, so the declaration survives a republish moving the version segment. A composable image's rootfs is the prefix's contents, so from must live under it.
• at is the absolute container path the subtree is exposed at, read-only. The catalogue restricts it to /usr/share/ and from to a directory, both checked at publish time.

Mechanically it is the engine's own image-subpath mount (--mount type=image,subpath=) — the same primitive the composable prefix mounts use. The subtree is projected out of the image's rootfs directly: no extraction, no host-side state, no cache to clean, and read-only is the mount type's only mode.

Two run-time rules: no two tools in one run may claim the same at with different content (the run fails and names both), and a host mount you already asked for at at wins — the image's declaration is dropped.

The Apple container runtime has no image mounts at all (warn-only, like every other composed tool there) and composable runs do not reach k8s yet, so the exposure is a no-op there.

[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 Package 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.

[enforce] section

The same per-tool settings as [tools], but a project cannot override them. By default a project's .kapslrc wins over [tools] — it is the more specific scope, and you reviewed it at the trust prompt; that is usually what you want. What .kapslrc cannot express is "I set this limit and I mean it". For a confinement boundary that is the whole reason to set one, so [enforce.<name>] takes precedence over everything, .kapslrc included:

[enforce.gawk]
seccomp = "net-denied"

Only seccomp is honoured here today. Any other field is a load-time error rather than a silent no-op — an [enforce] entry that looks binding and is not would be the worst possible failure for this table.

[groups] section

Named sets of composable tools:

[groups]
mylinters = ["flake8", "mypy", "black"]

A group name expands at a compose position — kapsl -e mylinters vim composes the three tools into vim's container. A group names a set; it grants nothing and cannot nest. The catalogue's own projects (coreutils and the rest) are looked up the same way — a group or a project is only ever expanded where a compose entry is expected, never as a fallback for an unresolved tool name, and a user-defined group of the same name shadows the built-in.

Validation

kapsl validates kapsl.toml when it loads it. A TOML syntax error, an unknown key, or a value of the wrong type prints an error naming the file and exits before anything runs — a broken config fails loudly on every run, never silently falling back to defaults. That is deliberate: a config that quietly stops applying is indistinguishable from one that is, and this one at least tells you which.

The same rule covers the explicit-path case: a missing file at the default location is normal (fresh install, defaults apply); a missing file at a path named by KAPSL_CONFIG is an error, because silently running with defaults would hide the typo.