Configuration

boks works without any configuration file. When you need to override defaults — custom tool mappings, SSH agent forwarding, pass-through environment variables — create a boks.toml file.

Config file location

You can override the path with the BOKS_CONFIG environment variable:

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

Minimal example

[tools]
rg = "boks.sh/rg:latest"

[global]
pass_env = ["GITHUB_TOKEN", "AWS_*"]
forward_ssh_agent = true

What's in this section

• Configuration File — full reference for boks.toml
• Tool Mappings — map tool names to custom images
• Environment Variables — pass host env vars into containers
• Override Configuration — per-run overrides via flags
• Project Config — a project's own .boksrc invocation overlay

Pages in this section

• Configuration File
• Tool Mappings
• Environment Variables
• Offline Mode
• Per-Run Overrides
• Config Validation
• Project Config