kap

Run AI agents in secure capsules. Built on devcontainers with network controls and remote access.

• Domain allowlist - only approved domains are reachable from the container
• MCP tool allowlist - only approved tools are callable on remote MCP servers
• CLI proxy - gh, aws, etc. are proxied with per-command allowlists
• Credential isolation - tokens and API keys live on the sidecar and never enter the app container
• Remote monitoring - monitor and steer agents from your phone over local WiFi

[!WARNING] This is experimental and may have bugs. Use at your own risk.

Quick start

Requires Docker (or Colima, OrbStack, etc.) and the devcontainer CLI.

cargo install kap

cd your-project
kap init                          # scaffold .devcontainer/ with kap.toml
$EDITOR .devcontainer/kap.toml    # review allowed domains, MCP servers, CLI tools
kap up                            # start the sandboxed devcontainer
kap exec                          # shell into it

From inside the container, install and run Claude Code, Codex, or any AI agent. All network access is gated by the sidecar.

SSH agent forwarding

The host SSH agent is forwarded into the container by default, enabling git clone over SSH, commit signing, etc. On macOS this uses Docker Desktop's built-in SSH forwarding; on Linux it bind-mounts $SSH_AUTH_SOCK directly.

ssh_agent = true   # set to false to disable

Domain allowlist

kap init generates a kap.toml with a domain allowlist. Defaults cover common package managers, registries, and AI providers.

[proxy.network]
allow = [
  "github.com",
  "*.github.com",
  "crates.io",
  "*.crates.io",
  "*.ubuntu.com",
]
# deny overrides allow:
deny = ["gist.github.com"]

Wildcards (*.github.com) match subdomains but not the bare domain. Deny rules always win. Changes to kap.toml are hot-reloaded — no container restart needed.

Global config

~/.kap/kap.toml applies to all projects. Same format as the project config — domains, CLI tools, and MCP servers are merged automatically. Project settings override global settings for same-name tools/servers.

# ~/.kap/kap.toml
[proxy.network]
allow = ["*.internal.corp.com", "artifactory.corp.com"]

[cli]
[[cli.tools]]
name = "aws"
env = ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY"]
allow = ["s3 *", "sts get-caller-identity"]

MCP proxy

The MCP proxy sits between the agent and remote MCP servers, injecting credentials when forwarding upstream. The app container never sees tokens or API keys.

Register servers on the host:

# OAuth (opens browser)
kap mcp add linear https://mcp.linear.app

# API key via headers
kap mcp add context7 https://mcp.context7.com/mcp --header "CONTEXT7_API_KEY=sk-..."

kap mcp list          # see registered servers
kap mcp get linear    # show details + tools list

Then add each server to kap.toml with an allow/deny list:

[mcp]

# Allow all tools
[[mcp.servers]]
name = "context7"
allow = ["*"]

# Allow only read/search operations
[[mcp.servers]]
name = "github"
allow = ["get_*", "list_*", "search_*"]

deny overrides allow, same as domain and CLI rules. Wildcards work the same as domain patterns (get_* matches get_issue, get_user, etc.).

CLI proxy

The CLI proxy lets the app container run tools like gh or aws without direct access to credentials. Two modes:

• Proxy mode (default): the sidecar executes the command and returns stdout/stderr. Credentials never enter the app container. Use allow/deny to restrict subcommands.
• Direct mode: the sidecar sends credentials to the app container, which runs the command locally. Needed for commands that write files (e.g. gh run download). The tool must be installed in the app container.

[cli]

# Proxy mode: sidecar executes, credentials stay isolated
[[cli.tools]]
name = "aws"
allow = ["s3 ls *", "s3 cp *", "sts get-caller-identity"]
env = ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY"]

# Direct mode: runs locally in the app container
[[cli.tools]]
name = "gh"
mode = "direct"

In proxy mode, deny overrides allow. In direct mode, allow/deny are not enforced (the command runs locally). For direct mode, env is optional — kap auto-detects env vars for known tools (e.g. gh → GH_TOKEN).

Remote access

Monitor and steer AI agents running in devcontainers from your phone over local WiFi.

kap remote start    # starts HTTP daemon on :19420, shows QR code

Scan the QR code on your phone to open the web UI. It auto-pairs and gives you:

• Status -container state, proxy health, denied request count
• Logs -live streaming proxy events, filterable by denied-only
• Agent -Claude Code session timelines, tool calls, cancel button, follow-up prompts

The daemon runs on the host. All API endpoints require a bearer token issued during QR pairing.

How it works

kap up starts two containers on an internal Docker network: your app container (isolated, no internet) and a kap sidecar (controls all outbound access). The sidecar pulls from ghcr.io/6/kap:latest by default, or set [compose] build in kap.toml to build from source.

graph LR
    subgraph internal ["Internal Docker network"]
        subgraph app ["App container"]
            Agent["AI agent<br/>(Claude Code, Codex, etc.)"]
        end
        subgraph sidecar ["kap sidecar"]
            DP["Domain proxy :3128"]
            DNS["DNS forwarder :53"]
            MCP["MCP proxy :3129"]
            CLI["CLI proxy :3130"]
        end
    end

    Agent -- "HTTP_PROXY" --> DP --> Internet
    Agent -- "DNS" --> DNS --> Upstream_DNS["Upstream DNS"]
    Agent -- "MCP" --> MCP --> MCP_Servers["MCP servers"]
    Agent -- "gh, aws, ..." --> CLI --> APIs

    style internal fill:#f5f5f5,stroke:#bbb,color:#333
    style app fill:#fff0f0,stroke:#e94560,color:#333
    style sidecar fill:#f0f4ff,stroke:#4a7fd4,color:#333
    style Agent fill:#ffdede,stroke:#e94560,color:#333
    style DP fill:#dce6f7,stroke:#4a7fd4,color:#333
    style DNS fill:#dce6f7,stroke:#4a7fd4,color:#333
    style MCP fill:#dce6f7,stroke:#4a7fd4,color:#333
    style CLI fill:#dce6f7,stroke:#4a7fd4,color:#333

• The app container has no external network route. All traffic goes through the sidecar.
• DNS queries only resolve allowed domains. Disallowed domains get NXDOMAIN.
• Blocked requests get a 403 (domains) or JSON-RPC error (MCP tools).
• Credentials never enter the app container (in proxy mode). Direct mode CLI tools receive credentials at exec time, but the domain proxy still controls what the container can reach.

Security model

Network isolation is kernel-enforced, not proxy-based. The Docker internal: true network has no default gateway, so the app container has no IP route to the outside world. Unsetting HTTP_PROXY or making direct TCP connections doesn't bypass it. The only reachable host is the sidecar.

MCP server domains are intentionally not in the domain allowlist. The agent can only reach them through the MCP proxy, which enforces tool filtering.

Known limitations:

• Domain fronting (partial): kap validates that the TLS SNI in the tunnel matches the CONNECT domain, blocking SNI-mismatch attacks. Classic domain fronting (where SNI matches but the encrypted HTTP Host header differs) is not detected because it requires TLS interception, which kap intentionally avoids. Most major CDNs have disabled domain fronting.
• Container escape: a kernel exploit that breaks out of the container bypasses all isolation. Not specific to kap. Running Docker inside a VM (e.g., Docker Desktop, Firecracker) adds defense-in-depth.
• No TLS inspection: kap controls which domains are reachable, not what happens on them. It does not MITM HTTPS traffic. Once a domain is allowed, the agent has full access to that domain's API.

Commands

Development

cargo check          # fast compile check
cargo build          # full build
cargo test           # run all tests
cargo clippy         # lint

This repo dogfoods kap via its own .devcontainer/. Open in VS Code or run:

kap up
kap exec .devcontainer/smoke-test.sh