Hermetically Isolated AI Agent Sandbox for Parallel Development
Kapsis enables running multiple AI coding agents in parallel on the same Maven project with complete isolation. Each agent runs in a Podman container with Copy-on-Write filesystem, ensuring Agent A's work cannot affect Agent B.
- Agent Agnostic - Works with Claude Code, Codex CLI, Aider, Gemini CLI, or any CLI-based agent
- Agent Profiles - Pre-built agent configurations with automatic container installation
- Config-Driven - Single YAML file defines agent command and filesystem whitelist
- Copy-on-Write Filesystem - Project files use overlay mounts (reads from host, writes isolated)
- Network Isolation - DNS-based allowlist filtering (default), blocks unauthorized network access
- Maven Isolation - Per-agent
.m2/repository, blocked remote SNAPSHOTs, blocked deploy - Build Cache Isolation - Gradle Enterprise remote cache disabled, per-agent local cache
- Git Workflow - Optional branch-based workflow with PR review feedback loop
- SSH Security - Automatic SSH host key verification for GitHub/GitLab/Bitbucket (enterprise servers supported)
- Keychain Integration - Automatic secret retrieval from macOS Keychain / Linux secret-tool
- Status Reporting - JSON-based progress tracking for external monitoring
- Rootless Containers - Security-hardened Podman rootless mode
| Method | Command |
|---|---|
| Homebrew (recommended) | brew tap aviadshiber/kapsis && brew install kapsis |
| Debian/Ubuntu | sudo dpkg -i kapsis_*.deb && sudo apt-get install -f |
| Fedora/RHEL | sudo dnf install kapsis-*.rpm |
| Universal script | curl -fsSL https://raw.githubusercontent.com/aviadshiber/kapsis/main/scripts/install.sh | bash |
Download
.deb/.rpmpackages from the releases page.
See docs/INSTALL.md for detailed instructions.
# Check current version
kapsis --version
# Check if upgrade is available
kapsis --check-upgrade
# Upgrade to latest version
kapsis --upgrade
# Upgrade to specific version
kapsis --upgrade 0.15.0
# Downgrade to previous version
kapsis --downgrade
# Downgrade to specific version
kapsis --downgrade 0.14.0
# Preview upgrade/downgrade without executing
kapsis --upgrade --dry-run
kapsis --downgrade --dry-run# 1. Install Kapsis (using any method above, or clone directly)
git clone https://github.com/aviadshiber/kapsis.git && cd kapsis
# 2. Run setup (checks dependencies, optionally installs Podman)
./setup.sh # Check dependencies only
./setup.sh --install # Auto-install missing dependencies (Podman, etc.)
# 3. Build the container image
kapsis-build # or ./scripts/build-image.sh
# 4. Copy and customize config
cp agent-sandbox.yaml.template agent-sandbox.yaml
# Edit agent-sandbox.yaml with your settings
# 5. Run an agent
kapsis 1 ~/project --task "fix failing tests"
# or: ./scripts/launch-agent.sh ~/project --task "fix failing tests"Kapsis includes pre-built agent profiles that install the agent directly into the container image. This solves cross-platform compatibility issues (e.g., macOS binaries won't run in Linux containers).
# Build Claude CLI agent image
./scripts/build-agent-image.sh claude-cli
# Build Aider agent image
./scripts/build-agent-image.sh aider
# List available profiles
./scripts/build-agent-image.sh --help# Use the pre-built agent image
./scripts/launch-agent.sh ~/project \
--image kapsis-claude-cli:latest \
--task "implement rate limiting"
# Or specify in config
# image:
# name: kapsis-claude-cli
# tag: latest| Profile | Agent | Installation |
|---|---|---|
claude-cli |
Claude Code CLI | npm install -g @anthropic-ai/claude-code |
claude-api |
Anthropic Python SDK | pip install anthropic |
aider |
Aider AI Pair Programmer | pip install aider-chat |
Profiles are defined in configs/agents/. Create custom profiles by copying an existing one.
# Simple inline task
./scripts/launch-agent.sh ~/project --task "fix failing tests in UserService"
# Complex task with spec file
./scripts/launch-agent.sh ~/project --spec ./specs/feature.md
# Interactive mode (manual exploration)
./scripts/launch-agent.sh ~/project --interactive# Create new branch and work on task
./scripts/launch-agent.sh ~/project \
--branch feature/DEV-123 \
--spec ./specs/task.md
# Agent works, commits, pushes → PR created
# Review PR, request changes
# Update spec with feedback, re-run:
./scripts/launch-agent.sh ~/project \
--branch feature/DEV-123 \
--spec ./specs/task-v2.md
# Agent CONTINUES from remote branch state!# Run multiple agents on same project, different branches
./scripts/launch-agent.sh ~/project \
--config configs/claude.yaml \
--branch feature/DEV-123-api \
--spec ./specs/api.md &
./scripts/launch-agent.sh ~/project \
--config configs/codex.yaml \
--branch feature/DEV-123-ui \
--spec ./specs/ui.md &
./scripts/launch-agent.sh ~/project \
--config configs/aider.yaml \
--branch feature/DEV-123-tests \
--spec ./specs/tests.md &
waitKapsis supports two isolation modes for the project filesystem:
| Mode | Flag | When Used | Best For |
|---|---|---|---|
| Worktree | --worktree-mode |
Auto when --branch + git repo |
Git-based projects, PR workflows |
| Overlay | --overlay-mode |
Auto when no branch specified | Non-git projects, quick tasks |
# Worktree mode (recommended for git projects)
# Creates isolated git worktree, real commits, pushable branches
./scripts/launch-agent.sh ~/project --branch feature/task --task "..."
# Overlay mode (legacy)
# Uses fuse-overlayfs, writes go to ephemeral upper layer
./scripts/launch-agent.sh ~/project --task "quick exploration"
# Force specific mode
./scripts/launch-agent.sh ~/project --worktree-mode --branch feature/x --task "..."
./scripts/launch-agent.sh ~/project --overlay-mode --task "..."See docs/GIT-WORKFLOW.md for detailed comparison.
# List all running agents
./scripts/kapsis-status.sh
# Get specific agent status
./scripts/kapsis-status.sh products 1
# Watch mode (live updates)
./scripts/kapsis-status.sh --watch
# JSON output for scripting
./scripts/kapsis-status.sh --jsonStatus files are written to ~/.kapsis/status/ in JSON format, enabling external tools to monitor agent progress.
Create agent-sandbox.yaml from the template:
agent:
# Command to launch the agent
command: "claude --dangerously-skip-permissions -p \"$(cat /task-spec.md)\""
workdir: /workspace
filesystem:
include:
- ~/.gitconfig
- ~/.ssh
- ~/.claude
environment:
# Secrets from system keychain (macOS Keychain / Linux secret-tool)
# No manual 'export' needed - retrieved automatically at launch!
keychain:
ANTHROPIC_API_KEY:
service: "Claude Code-credentials" # As stored by 'claude login'
# Non-secret variables from host environment
passthrough:
- HOME
- USER
resources:
memory: 8g
cpus: 4
maven:
mirror_url: "https://your-artifactory.com/maven"
block_remote_snapshots: true
block_deploy: true
git:
auto_push:
enabled: trueSee docs/CONFIG-REFERENCE.md for full configuration options.
| Agent | Command Example |
|---|---|
| Claude Code | claude --dangerously-skip-permissions -p "$(cat /task-spec.md)" |
| Codex CLI | codex --approval-mode full-auto "$(cat /task-spec.md)" |
| Aider | aider --yes-always --message-file /task-spec.md |
| Gemini CLI | gemini -s docker "$(cat /task-spec.md)" |
| Custom | Any CLI command |
Pre-built configs available in configs/ directory.
| Resource | Isolation Method |
|---|---|
| Project files | Overlay mount (:O) - reads from host, writes to isolated upper layer |
| Maven repository | Per-agent container volume |
| Remote SNAPSHOTs | Blocked in isolated-settings.xml |
| Deploy operations | Blocked in isolated-settings.xml |
| GE/Develocity cache | Remote cache disabled |
| Host system | Podman rootless container |
| Network access | DNS-based allowlist filtering (default) |
Kapsis provides DNS-based network filtering by default, allowing agents to access only whitelisted domains:
# Default: filtered mode (DNS allowlist)
kapsis ~/project --task "implement feature"
# Maximum isolation (no network)
kapsis ~/project --network-mode none --task "refactor code"
# Unrestricted network (use sparingly)
kapsis ~/project --network-mode open --task "test"See docs/NETWORK-ISOLATION.md for customizing the allowlist.
Kapsis provides security profiles with increasing levels of container hardening:
# Default: standard profile + seccomp (capability dropping, syscall filtering)
kapsis ~/project --task "implement feature"
# Strict mode for untrusted execution (adds noexec /tmp, lower PID limit)
kapsis ~/project --security-profile strict --task "review external PR"
# Trusted execution (no restrictions, isolated network)
kapsis ~/project --security-profile minimal --network-mode none --task "run trusted task"| Profile | Protection Level | Use Case |
|---|---|---|
minimal |
None | Trusted execution |
standard |
Capabilities, privilege escalation | Base profile |
strict |
+ Seccomp filtering, noexec /tmp | Untrusted execution |
paranoid |
+ Read-only root, LSM required | Maximum security |
See docs/SECURITY-HARDENING.md for detailed configuration.
Reclaim disk space after agent work:
./scripts/kapsis-cleanup.sh --dry-run # Preview
./scripts/kapsis-cleanup.sh --all # Clean everythingSee docs/CLEANUP.md for full options and troubleshooting.
# Enable debug output
KAPSIS_DEBUG=1 ./scripts/launch-agent.sh ~/project --task "test"
# View logs
tail -f ~/.kapsis/logs/kapsis-launch-agent.log./tests/run-all-tests.sh --quick # Fast validation (~10s)
./tests/run-all-tests.sh -q # All tests, quiet outputSee CONTRIBUTING.md for the full logging configuration and test framework documentation.
| Document | Description |
|---|---|
| ARCHITECTURE.md | System design, data flows, and component interactions |
| CONFIG-REFERENCE.md | Complete configuration options for agent-sandbox.yaml |
| GIT-WORKFLOW.md | Branch-based workflow, worktree vs overlay modes |
| STATUS-TRACKING.md | Real-time progress monitoring and hook system |
| INSTALL.md | Detailed installation instructions |
| SETUP.md | Initial setup and dependency configuration |
| CLEANUP.md | Disk space management and cleanup operations |
| SECURITY-HARDENING.md | Container security design and hardening options |
| NETWORK-ISOLATION.md | Network security and isolation configuration |
| GITHUB-SETUP.md | GitHub integration and authentication |
| CONTRIBUTING.md | Development guide, testing, and logging |
kapsis/
├── agent-sandbox.yaml.template # Config template
├── CONTRIBUTING.md # Testing & logging guide
├── Containerfile # Container image definition
├── setup.sh # System setup and validation
├── quick-start.sh # Simplified agent launcher
├── configs/
│ ├── agents/ # Agent profile definitions
│ │ ├── claude-cli.yaml # Claude Code CLI via npm
│ │ ├── claude-api.yaml # Anthropic Python SDK
│ │ └── aider.yaml # Aider AI pair programmer
│ ├── claude.yaml # User configs (reference profiles)
│ ├── codex.yaml
│ ├── aider.yaml
│ └── interactive.yaml
├── scripts/
│ ├── launch-agent.sh # Main launch script
│ ├── kapsis-status.sh # Status query CLI tool
│ ├── kapsis-cleanup.sh # Cleanup and reclaim disk space
│ ├── build-image.sh # Build base container image
│ ├── build-agent-image.sh # Build agent-specific images
│ ├── worktree-manager.sh # Git worktree management
│ ├── post-container-git.sh # Post-container git operations
│ ├── merge-changes.sh # Manual merge workflow
│ ├── entrypoint.sh # Container entrypoint
│ ├── init-git-branch.sh # Git branch initialization
│ ├── post-exit-git.sh # Post-exit commit/push
│ ├── switch-java.sh # Java version switcher
│ └── lib/
│ ├── logging.sh # Shared logging library
│ ├── status.sh # Status reporting library
│ └── json-utils.sh # JSON parsing utilities
├── maven/
│ └── isolated-settings.xml # Maven isolation settings
├── docs/
│ ├── ARCHITECTURE.md
│ ├── CONFIG-REFERENCE.md
│ ├── GIT-WORKFLOW.md
│ └── designs/ # Architecture design documents
│ └── agent-profiles-architecture.md
└── tests/ # Validation tests
- Podman 4.0+ (5.0+ recommended) — automatically installed by
./setup.sh --install - macOS with Apple Silicon (tested) or Linux
- Git 2.0+
- yq 4.0+ — required for YAML config parsing, agent image builds, and status hooks
MIT