Configuration

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

Config file location

You can override the path with the KAPSL_CONFIG environment variable:

KAPSL_CONFIG=/path/to/kapsl.toml kapsl python --version

Minimal example

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

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

What's in this section

• Configuration File — full reference for kapsl.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 .kapslrc invocation overlay

Pages in this section

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