kilntainers 0.1.3

Meta

• License: MIT License
• Author: Steve Cosman, Chesterfield Laboratories Inc
• Requires: Python >=3.13
• Provides-Extra: wasm , all

Classifiers

• Intended Audience
  • Developers
• License
  • OSI Approved :: MIT License

Give Agents Isolated Linux Sandboxes — via MCP

👁 Build and Test
👁 Test Count Badge
👁 PyPi
👁 Discord
👁 Newsletter

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:

uvtoolinstallkilntainers
kilntainers# starts with defaults: stdio MCP server, Docker, and Debian-slim

Add to your MCP client (Claude Desktop, 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: Each MCP connection starts its own isolated sandbox. In streaming HTTP mode, a single MCP server can host many sandboxes in parallel; in stdio mode, it runs a single sandbox per server process.

Backend Examples

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 

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.

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

kilntainers--backend=wasm--wasm-path=./my_tool.wasm

Installation

uvtoolinstallkilntainers# recommended
uvtoolinstallkilntainers[wasm]# optional, include WASM backends (+15MB)
pipinstallkilntainers# 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}] [--host HOST] [--port PORT] [--timeout TIMEOUT]
 [--output-limit OUTPUT_LIMIT] [--session-timeout SESSION_TIMEOUT] [--shell SHELL] [--network]
 [--tool-instruction-override TOOL_INSTRUCTION_OVERRIDE] [--extended-tool-instruction EXTENDED_TOOL_INSTRUCTION] [--engine ENGINE]
 [--docker-host DOCKER_HOST] [--image IMAGE] [--cpu CPU] [--memory MEMORY] [--docker-run-flag DOCKER_RUN_FLAGS] [--modal-token-id MODAL_TOKEN_ID]
 [--modal-token-secret MODAL_TOKEN_SECRET] [--modal-app-name MODAL_APP_NAME] [--modal-cpu MODAL_CPU] [--modal-memory MODAL_MEMORY] [--gpu GPU]
 [--region REGION] [--sandbox-timeout SANDBOX_TIMEOUT] [--wasm-path WASM_PATH] [--wasm-max-memory WASM_MAX_MEMORY] [--wasm-fuel WASM_FUEL]

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

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

core options:
 --backend {docker,go_busybox,modal,wasm}
 Backend to use (default: docker). Available: docker, 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")

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)

Verified details

These details have been verified by PyPI

Maintainers

👁 Avatar for scosman from gravatar.com
scosman

Unverified details

These details have not been verified by PyPI

Project links

• Homepage
• Issues
• Repository

• Download URL: kilntainers-0.1.3.tar.gz
• Upload date: Feb 17, 2026
• Size: 781.4 kB
• Tags: Source
• Uploaded using Trusted Publishing? No
• Uploaded via: uv/0.8.3

Hashes for kilntainers-0.1.3.tar.gz

Algorithm	Hash digest
SHA256	c62cfd376e2acb827018aae28c41679d836d9b0a770404756037845750a5d00d
MD5	b5b03bd9825e4937cb7777773a10cb93
BLAKE2b-256	374db059cbe7c7d43a162929eb707372983e517971e261fc77caf9012c08fefd

See more details on using hashes here.

• Download URL: kilntainers-0.1.3-py3-none-any.whl
• Upload date: Feb 17, 2026
• Size: 801.4 kB
• Tags: Python 3
• Uploaded using Trusted Publishing? No
• Uploaded via: uv/0.8.3

Hashes for kilntainers-0.1.3-py3-none-any.whl

Algorithm	Hash digest
SHA256	eb4a6dde8bf84c8ecc764af2c880b7f78402165007a02b27f1a1c706bf6bfbca
MD5	c8a1fcfe4824472324f6d0ece5cfb138
BLAKE2b-256	f943366356462024355aceafea0997d46190411718db51f4cd29941fe607bdc4

See more details on using hashes here.