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.

Claude Code Codex CLI Aider Gemini CLI Any CLI agent
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

What's New

NEW

Kubernetes Backend

Run agents as K8s Pods via the AgentRequest CRD. Same isolation model, cluster-scale concurrency. NetworkPolicy per pod.

v2.8.1

Atomic Staging

Bind-mount staging now uses host-side snapshots to prevent torn reads and race conditions during container launch.

5 Agents

Gemini CLI Support

Full agent profile for Google Gemini CLI joins Claude Code, Codex CLI, and Aider as supported agents out of the box.

Technology Deep Dive: Why we chose Podman over 10+ alternatives
Solution Type Isolation macOS Rootless Self-Host Trade-offs
Kapsis (Podman) Container Strong ✓ ✓ ✓ Best for local dev, macOS + Linux
Kapsis (K8s) K8s Pod Strong Cluster ✓ ✓ Best for teams, cluster-scale concurrency
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, copy-on-write filesystem. Best for local dev.
Kubernetes: Same isolation via CRD operator. Best for teams and cluster-scale workloads.

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": "2026-02-19T10:30:00Z",
  "updated_at": "2026-02-19T10: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.

Core 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 rootless. K8s Pods use runAsNonRoot with dropped capabilities. Both prevent privilege escalation.

# Copy-on-Write filesystem
filesystem:
  mode: overlay
# Host files unchanged
New in v2.14.0

Tamper-Evident Audit Trail

Every agent action is recorded as a hash-chained JSONL event log. SHA-256 hash links make tampering detectable — if any event is modified, the chain breaks.

Hash chain — Each event links to the previous via SHA-256
Real-time detection — Credential exfil, mass deletion, suspicious commands
Post-run reports — Timeline, statistics, security alerts, chain verification
Auto-classification — Events tagged as credential, network, filesystem, git ops
# Enable audit for an agent run
audit:
  enabled: true

# Verify chain integrity after run
$ audit-report.sh --latest --verify
  Hash chain: VALID (142 events)
  Alerts: 0

# Each event is hash-linked
{"seq":42, "event_type":"tool_use",
 "tool_name":"Bash",
 "prev_hash":"a3f2...",
 "hash":"7b1c..."}

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 or K8s Secrets
K8s NetworkPolicy — Per-pod egress rules enforced by the cluster (K8s backend)
Tamper-evident audit trail — Hash-chained JSONL logs with real-time pattern detection

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"

Documentation

Architecture

System design, isolation layers, and data flows
Config Reference

Complete YAML configuration options
Build Profiles

Container build profiles and customization
Git Workflow

Branch lifecycle, worktree vs overlay modes
Security Hardening

AppArmor, seccomp, and container hardening
Network Isolation

DNS filtering, IP pinning, and allowlists
Status Tracking

Real-time JSON progress monitoring
Installation

Detailed setup for all platforms
GitHub Setup

GitHub integration and authentication
Cleanup

Disk space management and reclamation
Setup Guide

Initial setup and dependency configuration
Contributing

Development guide, testing, and logging

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.

Kubernetes backend 

kapsis ~/project --backend k8s --task "add input validation"

Run agents as K8s Pods instead of local containers. Same flags, cluster-scale.

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 ships with pre-built profiles for Claude Code, Codex CLI, Aider, and Gemini CLI. Any CLI-based agent that runs in a terminal can be used with a custom profile.

What about API keys and credentials?

Credentials are securely injected at runtime from your macOS Keychain or Linux secret-tool via the secret store integration. They're never written to disk inside the container.

Can I use my IDE while the agent works?

Yes! In worktree mode, changes are written to a real 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 used daily for production development at scale.

What platforms are supported?

macOS (Apple Silicon and Intel) and Linux for the Podman backend. Any Kubernetes cluster for the K8s backend. Use --backend k8s to run agents as Pods.

Can I run multiple agents in parallel on the same project?

Yes! Each agent gets its own isolated container with a separate git worktree and filesystem. Run as many agents as your machine can handle — they cannot interfere with each other.

How does network isolation work?

Kapsis runs a dnsmasq instance inside each container that only resolves domains on the allowlist. Unknown hosts return NXDOMAIN. On K8s, a per-pod NetworkPolicy adds port-level egress filtering on top of DNS filtering. Choose between filtered (default), none (air-gapped), or open modes.

Can I run agents on Kubernetes instead of locally?

Yes! Use --backend k8s to run agents as Kubernetes Pods via the AgentRequest CRD. An in-cluster operator manages pod lifecycle, status bridging, and NetworkPolicy enforcement. Same flags, same isolation model, cluster-scale concurrency.