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

Web Dashboard

Single-binary local dashboard: live agent health, logs, audit trail, conversation transcripts, disk usage, and kill/cleanup controls. kapsis-dashboard --open

NEW

kapsis-ctl

Host-side container control via the libpod REST API: inspect, list, alive, stop, logs, cp. Built for scripts and orchestrators.

v2.32+

Self-Healing Reliability

Liveness monitoring kills hung agents, host-side watchdogs catch VM mount failures, and TTL cleanup with disk-pressure warnings keeps long-running fleets healthy.

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...

Fire and Forget — With Full Visibility

Launch agents, walk away, and still know exactly what happened. Kapsis ships a full observability and self-healing stack out of the box.

New

Local Web Dashboard

A single self-contained binary serves a live view of every agent: composite health, logs, the original task spec, an activity timeline, the audit trail, conversation transcripts, container stats, and disk usage — plus kill and cleanup controls.

Composite health — heartbeat, container state, mount probes, and liveness signals rolled into one verdict
Live updates — Server-Sent Events stream status, logs, and activity as they happen
Localhost-only + token auth — destructive actions need typed confirmation and are themselves audited
Maintenance built in — preview and execute cleanup per target, watch disk usage by category
$ kapsis-dashboard --open
Dashboard on http://127.0.0.1:7777 (token-protected)
KAPSIS DASHBOARD 3 agents
a3f2b1 ecommerce-api
healthy · 52%
c7e3f9 payment-svc
healthy · 81%
d9b0e2 legacy-monolith
degraded · idle 4m
Overview SpecLogsActivityAuditConversationContainer
disk: worktrees 4.2G · volumes 2.8G · snapshots 1.1G

Status JSON & CLI

Every agent writes structured progress to ~/.kapsis/status/. Watch live in the terminal or consume from scripts and bots.

$ kapsis-status --watch
a3f2b1 │ implementing │ 52%

Conversation Transcripts

The agent's full output is persisted per run — even on crashes and kills — so you can review what happened after the container is gone.

~/.kapsis/conversations/
  └─ a3f2b1/transcript.txt

Structured Recovery

Machine-readable exit codes (0–6) and an error_type field tell orchestrators whether to retry, retry the push only, restart the VM, or page a human.

$ kapsis-recovery-action proj 42
→ action: retry_push

Self-Healing for Unattended Runs

Liveness Monitor

Detects hung agents via status staleness, process I/O, and TCP activity. Captures diagnostics, then kills — no more zombie sessions.

Mount Watchdogs

virtio-fs drops on macOS are caught pre-launch, at startup, and mid-run (vfkit + exec-channel watchdogs) and reported as exit code 4.

Work Preservation

Commit failures preserve the staged worktree; crashed agents with committed work are flagged agent_partial so callers don't double-retry.

TTL Cleanup

Leaked snapshots and old transcripts expire automatically; disk-pressure warnings show the top consumers before space runs out.

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

JSON progress, error types, and recovery
Dashboard

Local web UI for agents, audit, and disk
K8s Backend

AgentRequest CRD and in-cluster operator
Audit System

Hash-chained logs and pattern detection
Plugins

Claude Code plugin hooks in containers
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.

Watch everything in the dashboard 

kapsis-dashboard --open

Live agent health, logs, transcripts, audit, and disk usage in your browser.

Audit what the agent did 

audit-report.sh --latest --verify

Timeline, statistics, security alerts, and hash-chain verification per run.

Troubleshooting & Ops

Debug Logs

View the launch sequence and container output.

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

Cleanup

Reclaim disk space, expire stale snapshots, and check Podman VM health.

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

Container Control (kapsis-ctl)

Query, stop, stream logs, or copy files out of agent containers via the libpod API.

kapsis-ctl logs -f kapsis-a3f2b1

Automated Recovery

Map an agent's error_type to retry / restart-VM / notify-human.

kapsis-recovery-action --json myproject 42

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.

How do I monitor agents while they run?

Three ways: kapsis-status --watch in the terminal, the local web dashboard (kapsis-dashboard --open) with live health, logs, audit, and disk views, or consume the JSON status files in ~/.kapsis/status/ from your own tooling. Full conversation transcripts are also saved per run for post-hoc review.

What happens if an agent hangs or the VM breaks mid-run?

Kapsis self-heals: a liveness monitor detects hung agents (status staleness + process I/O + TCP activity) and kills them after bounded grace periods, while host-side watchdogs catch macOS virtio-fs mount drops and wedged podman channels. Every outcome gets a structured exit code (0–6) and error_type, and kapsis-recovery-action tells your orchestrator whether to retry, restart the VM, or escalate. Committed work is never lost — partial completions are flagged so callers don't retry blindly.