Quick Start

This guide gets you from zero to running your first containerized tool in about five minutes.

Prerequisites

You need a container runtime. boks works with:

  • Podman (recommended — rootless, no daemon)
  • Docker (used automatically when Podman is not installed)
# Verify a runtime is available
podman --version   # or: docker --version

On macOS, install Podman Desktop from podman.io and start the Podman machine before using boks.

Install boks

curl -fsSL https://boks.sh/install | sh

This downloads the binary for your platform, verifies its checksum, and installs it to ~/.local/bin/boks.

Then add ~/.local/bin to your PATH if it isn't already:

export PATH="$HOME/.local/bin:$PATH"
# Add the above line to your ~/.bashrc or ~/.zshrc

Verify the install:

boks --help

You should see the boks logo and a list of flags.

Your first command

Run jq without installing it:

$ echo '{"name": "boks"}' | boks jq '.name'
  ■ PULLED boks.sh/jq:latest · 9 MB · 1.8s
  ■ SCANNED 38 packages · no findings
  ■ RUN jq '.name'
"boks"

The first run pulls the image. Subsequent runs are near-instant from cache.

Search for tools

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

Search matches tool names, descriptions, and tags from the index.

Run a tool with a specific version

Append @version to pin to a container image tag:

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

Install a shim

For tools you use frequently, create a shim so you don't need to type boks every time:

boks --install jq

This creates a symlink at ~/.local/bin/jq → boks. Now you can run jq directly:

echo '{"x": 1}' | jq '.x'

Security in action

By default, tools cannot write to your filesystem:

boks python -c "open('test.txt', 'w').write('hello')"
# PermissionError: [Errno 30] Read-only file system: 'test.txt'

Grant write access with --cap rw:

boks --cap rw python -c "open('test.txt', 'w').write('hello')"

By default, tools have no network access:

boks curl https://example.com
# curl: (6) Could not resolve host: example.com

Grant network access with --cap net:

boks --cap net curl https://example.com

Build a Python environment

Install packages inline:

boks python@3.12:requests,jinja2 -c "import requests; print(requests.__version__)"

Or from a requirements.txt:

boks --cap net -e @pip:requirements.txt python@3.12 script.py

What's next

  • Installation — other install methods, uninstalling
  • Basic Usage — all flags, working directory, CI mode
  • Environments — Python, Node.js, and other language environments
  • Configuration — local tool overrides, SSH agent, pass-through env vars