Basic Usage

Running a tool

boks [OPTIONS] [TOOL] [ARGS]...

Prepend boks to any tool name. boks looks up the image, pulls it if needed, and runs the tool in an ephemeral container with your current directory mounted at /boks/workdir.

boks jq --version
boks python --version
boks rg "TODO" .

The first run pulls the image. Subsequent runs use the local cache and start in milliseconds.

Pinning versions

Append @tag to use a specific image tag:

boks python@3.11 --version
boks python@3.12 --version
boks node@18 --version
boks node@22 --version

Security flags

By default, containers have no network access and the working directory is mounted read-only.

Flag	Effect
`--cap net`	Allow network access
`--cap rw`	Allow writes to working directory
`--cap ro`	Force read-only working directory (overrides image defaults)
`--cap nomount`	Skip mounting the working directory entirely — tighter than `ro`, for tools with no legitimate use for it
`--privileged`	Drop all capability restrictions
`--cap rwimg`	Allow writes to the image filesystem
`-p, --port <HOST:CONTAINER>`	Publish a container port to the host (implies `--cap net`)

See CLI Reference for the complete flag list, including the browser/clipboard relays and scan controls.

boks --cap net curl https://example.com
boks --cap rw python -c "open('out.txt', 'w').write('done')"

Platform and runtime

boks --platform linux/amd64 python --version
boks --runtime docker python --version      # force Docker over Podman

Installing shims

For tools you use frequently, create a shim so you can skip the boks prefix:

boks --install rg
rg "TODO" .    # same as: boks rg "TODO" .

Shims are symlinks at ~/.local/bin/<tool> → boks. boks reads argv[0] to determine the tool name.

Listing shims

boks --list

Searching the tool index

boks --search dns
boks --search python
boks --search kubernetes

Search matches tool names, descriptions, and tags.

CI mode

In CI, pass --non-interactive (or set the CI environment variable) to disable TTY allocation:

boks --non-interactive python -c "import sys; print(sys.version)"

boks auto-detects CI=true and disables TTY automatically.

Reclaiming disk

boks --status    # what boks is storing, by category
boks --clean     # leaked scan scratch + boks-env-* environment images

Bare boks --clean removes only what costs nothing to recreate: leaked per-run scan scratch, and container images boks built for environment builds (named boks-env-*). Base images are never affected.

Pass a target to go further — boks --clean cache drops every regenerable cache including the vulnerability database, and asks first. See the commands reference for the full target list, --dry-run, and what --clean refuses to remove.

Kubernetes

Run a tool as a temporary pod in your current cluster context:

boks --k8s python --version
boks --k8s --namespace staging python script.py
boks --k8s --node worker-1 htop

See Kubernetes for more.

Common patterns

# Process stdin
echo '{"x":1}' | boks jq '.x'

# Use a requirements file
boks -e @pip:requirements.txt python@3.12 script.py

# Network access for downloads
boks --cap net python -c "import urllib.request; urllib.request.urlretrieve('https://example.com/file', 'file')"

# Portable shebang scripts
chmod +x script.py   # script starts with: #!/usr/bin/env -S boks python@3.12:requests
./script.py