Quick Start

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

Prerequisites

You need a container runtime. kapsl 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 kapsl.

Install kapsl

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

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

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:

kapsl --help

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

Your first command

Run jq without installing it:

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

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

Search for tools

kapsl --search dns
kapsl --search python
kapsl --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:

kapsl [email protected] --version
kapsl [email protected] --version
kapsl node@18 --version
kapsl node@22 --version

Install a shim

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

kapsl --install jq

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

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

Security in action

By default, tools cannot write to your filesystem:

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

Grant write access with --cap rw:

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

By default, tools have no network access:

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

Grant network access with --cap net:

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

Build a Python environment

Install packages inline:

kapsl [email protected]:requests,jinja2 -c "import requests; print(requests.__version__)"

Or from a requirements.txt:

kapsl --cap net -e @pip:requirements.txt [email protected] 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