Skip to content
Capsem

Getting Started

Requirements

Section titled “Requirements”
macOSLinux
OSmacOS 14 (Sonoma) or laterDebian/Ubuntu (apt-based)
HardwareApple Silicon (M1 or newer)x86_64 or arm64, KVM capable
Disk~2 GB for binaries + VM assets~2 GB for binaries + VM assets

macOS uses Apple’s Virtualization.framework (Apple Silicon only). Linux uses KVM.

Install

Section titled “Install”
Section titled “One-liner (recommended)”
Terminal window
curl -fsSL https://capsem.org/install.sh | sh

The script auto-detects your OS and architecture, downloads the Capsem binaries, and runs capsem setup to complete installation.

Manual download

Section titled “Manual download”
  1. Go to the latest release on GitHub.
  2. Download the .pkg (macOS) or .deb (Linux) file for your architecture.
  3. macOS: open the package and follow the installer.
  4. Linux: sudo apt install ./capsem_*.deb

Building from source

Section titled “Building from source”

See the Development Guide for instructions on cloning the repo, installing toolchain dependencies, building VM assets, and running from source.

Setup

Section titled “Setup”

On first use, Capsem auto-runs the setup wizard. You can also run it explicitly:

Terminal window
capsem setup

The wizard walks through 6 steps:

  1. Corp config — enterprise provisioning (optional, skip for personal use)
  2. Asset download — downloads the Linux VM image (~200 MB) in the background
  3. Security preset — choose medium or high network restriction
  4. AI providers — auto-detects API keys from your environment
  5. Repository access — detects Git/SSH/GitHub configuration
  6. Service install — registers the background service (starts on login)

After setup, the Capsem service runs in the background (like Docker). It starts automatically on login.

First session

Section titled “First session”

Boot a sandboxed VM and get a shell:

Terminal window
capsem shell

This creates a temporary Linux session with an air-gapped network. You get a terminal inside the VM session with Python 3, Node.js, git, and 30+ packages pre-installed. The session is destroyed when you exit.

For a persistent session that survives suspend/resume cycles:

Terminal window
capsem create mybox
capsem shell mybox

Manage sessions with:

Terminal window
capsem list               # show all sessions
capsem info mybox         # detailed status + telemetry
capsem suspend mybox      # save state to disk
capsem resume mybox       # resume from where you left off
capsem delete mybox       # destroy permanently

See the CLI Reference for the full command list.

Desktop app

Section titled “Desktop app”

You can also use the Capsem desktop app for a graphical interface:

Terminal window
# macOS
open /Applications/Capsem.app


# Or launch from the system tray

The desktop app connects to the same background service — it’s a thin browser shell showing the same UI.

Using an AI agent

Section titled “Using an AI agent”

Capsem comes with Claude Code, Gemini CLI, and Codex pre-installed in the VM. To start a session with an agent:

Terminal window
# Inside the Capsem terminal
claude    # Claude Code
gemini    # Gemini CLI
codex     # Codex

API keys are configured in ~/.capsem/user.toml on the host (or auto-detected by the setup wizard):

[ai.anthropic]
api_key = "sk-ant-..."


[ai.google]
api_key = "AIza..."


[ai.openai]
api_key = "sk-..."

The keys are securely forwarded into the VM at boot time. They never touch the guest filesystem.

Network policy

Section titled “Network policy”

By default, the VM is air-gapped — all network traffic routes through the host’s MITM proxy. Only explicitly allowed domains can be reached. Add custom domains in ~/.capsem/user.toml:

[security.web]
custom_allow = [
  "api.anthropic.com",
  "generativelanguage.googleapis.com",
  "api.openai.com",
  "pypi.org",
  "files.pythonhosted.org",
  "registry.npmjs.org",
]

Every HTTPS request is logged to a per-session SQLite database with full method, path, headers, and body preview. The Capsem GUI shows this in real time in the Network tab.

MCP integration

Section titled “MCP integration”

AI agents can control sandboxes programmatically via the MCP server:

Terminal window
# Add to your Claude Code or Gemini CLI MCP config
capsem-mcp

This gives agents tools to create, exec, read/write files, and inspect sessions.

What’s next

Section titled “What’s next”