Skip to main content
Copied to clipboard!
v... — Production Ready

Run AI Agents
Without Fear

Run multiple AI coding agents in parallel. Total isolation. Zero conflicts.
The safest way to let LLMs edit your code.

Install Now Read Docs
kapsis — zsh
➜
➜

Why Kapsis?

The problem with running AI agents directly — and how Kapsis solves it

✗ → ✓

"Approve?" ×100

YOLO mode

Full autonomy in a safe sandbox

✗ → ✓

Network anywhere

DNS allowlist

Only approved domains reachable

✗ → ✓

Modifies your files

Isolated sandbox

Host files stay untouched

✗ → ✓

Agent conflicts

Parallel sandboxes

Each agent fully isolated

Technology Deep Dive: Why we chose Podman over 10+ alternatives
Solution Type Isolation macOS Rootless Self-Host Trade-offs
Kapsis (Podman) Container Strong ✓ ✓ ✓ Best balance for AI agent sandboxing
Docker Container Strong ✓ ⚠ ✓ Root daemon by default
Bubblewrap Namespace Medium ✗ ✓ ✓ No network isolation
Firecracker MicroVM Very Strong ✗ ✗ ✓ AWS infra, Linux only
gVisor User kernel Very Strong ✗ ✓ ✓ Syscall overhead
E2B Cloud VM Strong Cloud N/A ✗ Per-minute pricing
Modal Cloud Strong Cloud N/A ✗ ML-focused

Podman: Rootless containers, macOS native, OCI compatible, copy-on-write filesystem. Runs anywhere — local dev, CI/CD, or servers.

Minimal Overhead

Kapsis adds negligible overhead to your workflow

Seconds
Not minutes to start
Lightweight
Minimal memory footprint
CoW
Only changes stored
Native
No CPU emulation

Installation

RECOMMENDED macOS & Linux 
brew tap aviadshiber/kapsis && brew install kapsis
Post-install: Run kapsis-setup --build to build the container image.
Package security: All packages are GPG signed. Releases include checksums.sha256 for verification.
macOS (Apple Silicon) or Linux Git 2.0+ yq 4.0+ Podman 4.0+ (auto-installed by setup)
GAME CHANGER

Work in YOLO Mode safely.

Normally, flags like --dangerously-skip-permissions or --yes-always are terrifying. They risk your OS and your files.

With Kapsis, they are safe. Every destructive command is trapped inside a disposable container.

  • Agent deletes root? Container dies, Host lives.
  • Agent installs malware? It's isolated.
  • Full autonomy without the anxiety.
CONTAINER ISOLATION
$ claude --dangerously-skip-permissions
> Agent attempting to delete database config...
> Agent installing unknown npm packages...
> Agent modifying system PATH...
[KAPSIS MONITOR]: Host System Integrity: 100% (Safe)

Complete Workflow Example

See exactly how Kapsis works: from task specification to pull request.

STEP 1 specs/rate-limit.md
Task Specification 
# Add Rate Limiting to API Endpoints

## Objective
Implement rate limiting for all public API endpoints to prevent abuse.

## Requirements
- [ ] Add RateLimiter middleware using Redis
- [ ] Limit: 100 requests/minute per API key
- [ ] Return 429 status with Retry-After header

## Context
- JIRA: DEV-1234
- Files: src/middleware/, src/api/

## Testing
- [ ] Unit tests for RateLimiter class
- [ ] Integration test with Redis mock
STEP 2 agent-sandbox.yaml
Configuration (optional) 
agent:
  command: "claude --dangerously-skip-permissions"

environment:
  keychain:
    ANTHROPIC_API_KEY:
      service: "Claude Code-credentials"

resources:
  memory: 8g
  cpus: 4

git:
  auto_push:
    enabled: true
STEP 3 Terminal
Launch the Agent
➜ kapsis ~/ecommerce-api \
--spec specs/rate-limit.md \
--branch feature/DEV-1234-rate-limiting
✓ Sandbox created with Copy-on-Write filesystem
✓ API key retrieved from keychain
✓ Branch feature/DEV-1234-rate-limiting created
▶ Agent running in container...
LIVE kapsis-status --json
Real-time Progress 
{
  "agent_id": "a3f2b1",
  "project": "ecommerce-api",
  "branch": "feature/DEV-1234-rate-limiting",
  "phase": "implementing",
  "progress": 52,
  "message": "Writing src/middleware/RateLimiter.ts",
  "started_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:34:22Z"
}
COMPLETE Final Result
~8 minutes 
{
  "phase": "complete",
  "progress": 100,
  "exit_code": 0,
  "message": "Task completed successfully",
  "pr_url": "https://github.com/acme/ecommerce-api/pull/127",
  "commits": [
    "feat: add RateLimiter middleware with Redis",
    "test: add unit tests for rate limiting"
  ],
  "files_changed": 6
}

Files Created by Agent

+ src/middleware/RateLimiter.ts +142 lines
+ src/middleware/RateLimiter.test.ts +89 lines
~ src/api/routes.ts +12 lines
~ package.json +2 lines
View Pull Request #127 →

Feedback Loop: Need changes?

Review the PR, add comments, then re-run with an updated spec. The agent continues from the current branch state.

# Update spec with PR feedback, re-run same command
➜ kapsis ~/ecommerce-api --spec specs/rate-limit-v2.md --branch feature/DEV-1234-rate-limiting
# Agent pulls latest, reads feedback, continues work...

Defense in Depth

Multiple layers of isolation protect your host system from rogue AI agents.

New Feature

Three Network Isolation Modes

none Air-Gapped

Complete network isolation. No external connections allowed.

--network-mode=none
DEFAULT
filtered DNS Allowlist

Only approved domains resolve. Everything else returns NXDOMAIN.

--network-mode=filtered
open Unrestricted

Full network access. Use only when necessary.

--network-mode=open

Pre-configured Allowlist Categories

Git Hosts npm / PyPI / Maven AI APIs (Claude, GPT, Gemini) Container Registries Custom Domains

DNS-Based Filtering

dnsmasq runs inside the container, blocking unknown hosts at the DNS layer. Includes rebinding attack protection.

# network-allowlist.yaml
network:
  mode: filtered
  allowlist:
    hosts:
      - github.com
      - "*.github.com"

SSH Key Verification

Host keys are verified against official provider APIs (GitHub, GitLab, Bitbucket) to prevent MITM attacks.

# Verified via API
ssh:
  verify_hosts:
    - github.com
    - gitlab.com

Rootless Containers

Podman runs without root privileges. Even container escape leaves attacker as unprivileged user.

# Copy-on-Write filesystem
filesystem:
  mode: overlay
# Host files unchanged

Security Guarantees

Data exfiltration blocked — Unknown hosts return NXDOMAIN
DNS rebinding protection — Private IPs rejected in responses
MITM prevention — SSH keys verified against official APIs
Fail-safe defaults — Container aborts if filtering fails
Host filesystem safe — Changes trapped in overlay layer
Credential isolation — API keys injected at runtime from keychain

Docs & Agent Profiles

Kapsis separates the Container Environment (resources, mounts) from the Agent Logic (commands, flags).

1 Agent Profiles

Profiles define what runs inside the container. You can create custom YAML files for any CLI tool. 

agent:
  command: "claude --dangerously-skip-permissions -p \"$(cat /task-spec.md)\""
  workdir: /workspace

# API keys injected from host keychain
# account can be string or array (for fallback)
environment:
  keychain:
    ANTHROPIC_API_KEY:
      service: "Claude Code-credentials"
    JIRA_TOKEN:
      service: "my-jira"
      account: ["primary@example.com", "${USER}"]

# SSH hosts verified against official APIs
ssh:
  verify_hosts:
    - github.com
    - gitlab.com

2 Sandbox Resources

The `agent-sandbox.yaml` (or CLI overrides) controls the container's physical limits and isolation rules.

  • resources:
    Controls memory (e.g., 8g) and cpus (e.g., 4). Crucial for heavy compile tasks.
  • network:
    mode: filtered (default) enables DNS allowlist via dnsmasq. mode: none for air-gapped. mode: open for unrestricted.
  • ssh:
    verify_hosts: [github.com] enables MITM-protected SSH via official API verification.
  • maven:
    block_remote_snapshots: true prevents the agent from fetching unstable dependencies.
  • filesystem:
    Defines overlay mounts. By default, the project is mounted Read-Only + Copy-On-Write layer.

3 Security Profiles

Choose a security profile based on your threat model. Hover or tap a profile to see details.

Less Secure More Secure
DEFAULT CONFIG standard + seccomp

The out-of-box configuration. Uses standard profile with seccomp.enabled: true. Balances security and compatibility for typical development.

Capabilities dropped no-new-privileges PID limit: 1000 Seccomp filtering Blocks ptrace/mount/bpf
When to use: Recommended starting point for most projects
Usage examples 
# Default (standard)
kapsis ~/project --task "implement feature"

# Untrusted code
kapsis ~/project --security-profile strict --task "review PR"

# Debug (minimal + isolated network)
kapsis ~/project --security-profile minimal --network-mode none --task "debug"

Quick Start: 3 Steps

1 Create a task spec 
# specs/fix-auth.md

# Fix Login Bug

## Problem
Users get 401 errors when
logging in with email+password

## Requirements
- [ ] Fix token validation
- [ ] Add error logging
- [ ] Add regression test
2 Launch the agent 
➜ kapsis ~/my-app \
    --spec specs/fix-auth.md \
    --branch fix/login-401

Agent ID: b7c3a1
Branch: fix/login-401
▶ Running in isolated container...

# Agent reads spec, explores code,
# makes changes, commits, pushes
3 Monitor & review PR 
➜ kapsis-status --watch

b7c3a1 │ implementing │ 65%
       │ Editing AuthService.ts

# Few minutes later...

b7c3a1 │ complete │ 100%
       │ PR: github.com/.../pull/42

Quick inline task 

kapsis ~/project --task "add input validation to UserForm component"

For simple tasks, skip the spec file entirely.

Interactive mode 

kapsis ~/project --interactive

Drop into an isolated shell for manual exploration.

Troubleshooting & Ops

Debug Logs

View the launch sequence and container output.

tail -f ~/.kapsis/logs/kapsis-launch-agent.log

Cleanup

Reclaim disk space and kill hanging containers.

./scripts/kapsis-cleanup.sh --all

Frequently Asked Questions

Does this work with my agent?

Yes! Kapsis works with any CLI-based agent: Claude Code, Aider, Codex, or any custom agent that runs in a terminal.

What about API keys and credentials?

Credentials are securely injected from your macOS Keychain or SSH agent. They're never written to disk inside the container.

Can I use my IDE while the agent works?

Yes! Changes sync to a git worktree on your host. Open it in your favorite IDE and watch the agent's progress in real-time.

Is Kapsis production ready?

Yes! Version ... is a stable release. We use it daily for production development at scale.

What platforms are supported?

macOS and Linux.