Configuration File

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

Override the path with BOKS_CONFIG:

BOKS_CONFIG=./boks.toml boks python --version

If the file does not exist, boks 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 = "boks.sh/rg:latest"
python = { image = "boks.sh/python:3.12", command = "python3" }
# per-tool pass_env: additive to [global], and the opt-in for a protected var
aws-cli = { image = "boks.sh/aws-cli:latest", pass_env = ["AWS_SECRET_ACCESS_KEY"] }

[theme]
enabled = true

[global] section

Freshness

boks 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, boks best-effort re-pulls it before scanning and running:

• Best-effort: if the refresh pull fails (no network, registry down), boks 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 boks.toml) are immutable by construction, and locally-built environment images (boks-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, boks 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 cached index.json/policy.json — the data --search, --info, and tool resolution all read. A cache older than the window (or missing entirely) is refreshed automatically before a run, same as boks --update but without you having to run it. This refresh 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. Skipped entirely with --offline.

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

[theme] section

boks'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 boks 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 = "boks.sh/rg:latest"
python = { image = "boks.sh/python:3.12", command = "python3" }

[package_providers] section

User-defined package providers, so you can teach boks a package manager without a code change. Each entry is a pair of templated install commands; boks 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 boks rather than with it. Everything here changes where boks gets its own data from, so everything here prints a warning on every run.

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

Point index_dir at a checkout's boks-index/ and your own index edits take effect immediately, with no publish step. boks --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 boks python anywhere. The alternative people reach for instead — a symlink at ~/.cache/boks/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 boks — it resolves to
              /Users/you/src/boks/boks-index. It will not be refreshed, and
              may not match the published catalogue.

The failures this prevents all have the same shape — boks 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.

BOKS_INDEX_DIR

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

BOKS_INDEX_DIR=/path/to/boks-index boks python --version

It exists for test suites and CI, which must not depend on whatever happens to be in a developer's cache. boks's own integration tests set it to the checkout's boks-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 BOKS_INDEX_DIR as the source so a reader knows to look at the environment rather than the config file.