Kilntainers

<p align="center"> <a href="https://kiln.tech"> <picture> <img width="380" alt="Kilntainers by Kiln AI Logo" src="https://github.com/user-attachments/assets/09009b2a-1310-432b-941d-54ebf1fb78a8" /> </picture> </a> </p> <h3 align="center"> Give Every Agent an Ephemeral Linux Sandbox — via MCP </h3>

<p align="center"> <a href="https://github.com/Kiln-AI/kilntainers/actions/workflows/build_and_test.yml"><img src="https://github.com/Kiln-AI/kilntainers/actions/workflows/build_and_test.yml/badge.svg" alt="Build and Test"></a> <a href="https://github.com/Kiln-AI/kilntainers/actions/workflows/test_count.yml"><img src="https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/scosman/9f8457cc9d44ab16ff8b9f1a977d25bb/raw/test_count_kiln.json" alt="Test Count Badge"></a> <a href="https://pypi.org/project/kilntainers/"><img src="https://img.shields.io/pypi/v/kilntainers.svg?logo=pypi&label=PyPI&logoColor=gold" alt="PyPi"></a> <a href="https://kiln.tech/discord"><img src="https://img.shields.io/badge/Discord-Kiln_AI-blue?logo=Discord&logoColor=white" alt="Discord"></a> <a href="https://kiln.tech/blog"><img src="https://img.shields.io/badge/Newsletter-subscribe-blue?logo=mailboxdotorg&logoColor=white" alt="Newsletter"></a> </p>

Kilntainers is an MCP server that gives LLM agents isolated Linux sandboxes for executing shell commands.

• 🧰 Multiple backends: Containers (Docker, Podman), cloud-hosted micro-VMs (Modal, E2B), and WebAssembly sandboxes (WASM BusyBox, or any WASM module).
• 🏝️ Isolated per agent: Every agent gets its own dedicated sandbox — no shared state, no cross-contamination.
• 🧹 Ephemeral: Sandboxes live for the duration of the MCP session, then are shut down and cleaned up automatically.
• 🔒 Secure by design: The agent communicates with the sandbox over MCP — it doesn’t run inside it. No agent API keys, code, or prompts are exposed to the sandbox.
• 🔌 Simple MCP interface: A single MCP tool, sandbox_exec, lets your agent run any Linux command.
• 📈 Scalable: Scale from a few agents on your laptop to thousands running in parallel in the cloud.

Why Kilntainers?

Agents are already excellent at using terminals, and can save thousands of tokens by leveraging common Linux utilities like grep, find, jq, awk, etc. However giving an agent access to the host OS is a security nightmare, and running thousands of parallel agents on a service is painful. Kilntainers gives every agent its own isolated, ephemeral sandbox.

Quick Start

Install and run from CLI:

# install
uv tool install kilntainers
# starts with defaults: stdio MCP server, Docker, and Debian-slim (see options below)
kilntainers

Add to your MCP client (Claude, Cursor, etc.):

{
  "mcpServers": {
    "kilntainers": {
      "command": "kilntainers"
    }
  }
}

How It Works

┌─────────────┐   MCP   ┌──────────────┐      ┌─────────────────────────┐
│  LLM Agent  │◄───────►│  Kilntainers │◄────►│  Sandboxes              │
│  (client)   │         │  MCP Server  │      │  - Docker/Podman        │
│             │         │              │      │  - Cloud VM (Modal,E2B) │
│             │         │              │      │  - WASM Sandbox         │
└─────────────┘         └──────────────┘      └─────────────────────────┘

1. An MCP client connects to Kilntainers
2. On the first sandbox_exec call, Kilntainers creates an isolated sandbox. Each connection gets its own independent sandbox.
3. Commands run inside the sandbox; stdout, stderr, and exit code are returned
4. When the session ends, the sandbox is destroyed and resources are cleaned up.

Security: The agent communicates with the sandbox over MCP — it doesn't run inside it. This is intentional: agents often need secrets (API keys, system prompts, code), and those should never be exposed inside a sandbox where a prompt injection could exfiltrate them.

Agent Isolation & Sandbox Lifecycle: Each MCP connection starts its own isolated sandbox. In streaming HTTP mode, a single MCP server can host many sandboxes in parallel, and exec calls are routed to the sandbox associated with that connection. In stdio mode, the server runs a single sandbox per process. When a connection closes, its sandbox is shut down and deleted.

Backend Examples

See the CLI Reference for all arguments.

Docker and Podman (default)

Local containers via Docker or Podman. Any OCI image works.

kilntainers                                     # Docker + debian-slim (defaults)
kilntainers --image alpine --engine podman      # Podman + Alpine
kilntainers --image node:22 --network           # Node.js with networking

Cloud Containers & VMs

Modal.com

Hosted containers with sub-second startup via Modal.com. Scales to thousands of parallel sandboxes. Supports GPUs.

kilntainers --backend modal
kilntainers --backend modal --gpu A10G --region us-east  # GPU-accelerated

Authenticate via modal setup CLI or --modal-token-id / --modal-token-secret flags.

E2B

Cloud hosted micro-VM sandboxes from E2B.

kilntainers --backend e2b # Default Debian image
kilntainers --backend e2b --e2b-api-key ABCD --e2b-template my-custom-alpine # Custom image 

Authenticate with --e2b-api-key CLI arg, or E2B_API_KEY environment variable.

WASM Go BusyBox (Experimental)

Runs go-busybox in a WebAssembly sandbox. Not a full Linux environment, but provides common utilities (grep, awk, sed, ls, wc, sort, etc.) in a very lightweight and secure sandbox.

uv tool install kilntainers[wasm]  # WASM support is an optional dependency (+15MB)
kilntainers --backend go_busybox

WASM Runner

Run a custom WASM module as the sandbox backend. Provides agents a set tools compiled to WebAssembly, and an isolated filesystem.

uv tool install kilntainers[wasm]  # WASM support is an optional dependency (+15MB)
kilntainers --backend wasm --wasm-path ./my_tool.wasm

Installation

uv tool install kilntainers        # recommended
uv tool install kilntainers[wasm]  # optional, include WASM backends (+15MB)
pip install kilntainers            # also works with pip

Requires Python 3.13+. Docker backend requires Docker or Podman. The Modal and E2B backends require accounts to those services.

CLI Reference

usage: kilntainers [-h] [--backend {docker,go_busybox,modal,wasm}] [--transport {stdio,http}] [...]

MCP server providing isolated Linux sandboxes for LLM agent shell execution.

options:
  -h, --help            show this help message and exit

core options:
  --backend {docker,e2b,go_busybox,modal,wasm}
                        Backend to use (default: docker). Available: docker, e2b, go_busybox, modal, wasm
  --transport {stdio,http}
                        MCP transport (default: stdio)
  --host HOST           HTTP bind address (default: 127.0.0.1, HTTP mode only)
  --port PORT           HTTP listen port (default: 8435, HTTP mode only)
  --timeout TIMEOUT     Default exec timeout in seconds (default: 120)
  --output-limit OUTPUT_LIMIT
                        Max combined stdout+stderr bytes per exec (default: 2097152 = 2 MiB)
  --session-timeout SESSION_TIMEOUT
                        Idle session timeout in seconds (default: 300, HTTP mode only)
  --shell SHELL         Shell binary for command mode (e.g., /bin/bash, ash). Default: /bin/bash.
  --network             Enable network access in sandboxes (default: disabled)

tool description:
  --tool-instruction-override TOOL_INSTRUCTION_OVERRIDE
                        Replace the entire sandbox_exec tool description
  --extended-tool-instruction EXTENDED_TOOL_INSTRUCTION
                        Append to the backend's default tool description

docker backend options:
  --engine ENGINE       Container CLI binary (default: docker). Supports podman.
  --docker-host DOCKER_HOST
                        Docker daemon socket/address, passed as -H to the Docker CLI (e.g., "ssh://user@remote-host", "tcp://host:2375")
  --image IMAGE         Docker image (default: debian:bookworm-slim)
  --cpu CPU             Docker CPU limit (e.g., "1.5")
  --memory MEMORY       Docker memory limit (e.g., "512m")
  --docker-run-flag DOCKER_RUN_FLAGS
                        Additional flag passed to docker run. Repeatable. (e.g., --docker-run-flag "--pids-limit=256")

e2b backend options:
  --e2b-api-key E2B_API_KEY
                        E2B API key (overrides E2B_API_KEY environment variable)
  --e2b-template E2B_TEMPLATE
                        E2B template name or ID (default: base)
  --e2b-sandbox-timeout E2B_SANDBOX_TIMEOUT
                        Sandbox lifetime timeout in seconds (default: 3600)
  --e2b-metadata E2B_METADATA
                        Metadata key=value pairs (can be used multiple times)
  --e2b-env E2B_ENV     Environment variable key=value pairs (can be used multiple times)

modal backend options:
  --modal-token-id MODAL_TOKEN_ID
                        Modal token ID (overrides environment/default auth)
  --modal-token-secret MODAL_TOKEN_SECRET
                        Modal token secret (overrides environment/default auth)
  --modal-app-name MODAL_APP_NAME
                        Modal app name (default: kilntainers)
  --modal-cpu MODAL_CPU
                        CPU cores (fractional, default: 1.0)
  --modal-memory MODAL_MEMORY
                        Memory in MiB (default: 512)
  --gpu GPU             GPU type (e.g., "A10G", "H100")
  --region REGION       Geographic region (e.g., "us-east")
  --sandbox-timeout SANDBOX_TIMEOUT
                        Sandbox lifetime timeout in seconds (default: 3600, max 86400)

wasm backend options:
  --wasm-path WASM_PATH
                        Path to the .wasm file to execute (required for wasm backend)
  --wasm-max-memory WASM_MAX_MEMORY
                        Max WASM memory in MiB (default: 256)
  --wasm-fuel WASM_FUEL
                        WASM instruction fuel limit (default: unlimited)