roomkit-sandbox

Container-based sandbox executor for RoomKit — gives AI agents sandboxed command execution via RTK.

What it does

roomkit-sandbox provides a ready-made SandboxExecutor implementation that runs commands inside lightweight containers or VMs. Any AI agent (Anthropic, OpenAI, Ollama, vLLM) connected to RoomKit gets access to:

Installation

# Docker backend (development)
pip install roomkit-sandbox[docker]

# Kubernetes backend (production)
pip install roomkit-sandbox[kubernetes]

# SmolBSD backend (local VM isolation)
pip install roomkit-sandbox

Backends

Three backends for different deployment profiles:

See docs/backends.md for detailed setup instructions.

Quick Start

Docker

from roomkit import Agent
from roomkit_sandbox import ContainerSandboxExecutor
from roomkit_sandbox.docker_backend import DockerSandboxBackend

sandbox = ContainerSandboxExecutor(
    backend=DockerSandboxBackend(image="ghcr.io/roomkit-live/sandbox:latest"),
    session_id="my-sandbox",
)

agent = Agent("reviewer", provider=..., sandbox=sandbox)

Kubernetes

from roomkit_sandbox import ContainerSandboxExecutor
from roomkit_sandbox.k8s_backend import KubernetesSandboxBackend

sandbox = ContainerSandboxExecutor(
    backend=KubernetesSandboxBackend(
        image="ghcr.io/roomkit-live/sandbox:latest",
        namespace="production",
    ),
)

SmolBSD

from roomkit_sandbox import ContainerSandboxExecutor, NativeCommandBuilder
from roomkit_sandbox.smolbsd_backend import SmolBSDSandboxBackend

sandbox = ContainerSandboxExecutor(
    backend=SmolBSDSandboxBackend(smolbsd_dir="/path/to/smolBSD"),
    command_builder=NativeCommandBuilder(),
)

The guest image is built from smolbsd/ (see docs/backends.md).

Command Builders

The CommandBuilder ABC controls how tool calls become shell commands:

• RtkCommandBuilder (default) — uses RTK for 60-90% token reduction
• NativeCommandBuilder — uses standard Unix commands (cat, grep, find, git)
• Custom — subclass CommandBuilder for your own tools

See docs/commands.md for details and examples.

Container Image

docker pull ghcr.io/roomkit-live/sandbox:latest

Alpine 3.21 + RTK 0.42.4 + git + bash + curl + jq + gh + uv — 37MB (amd64; arm64 uses a Debian Trixie base).

Architecture

Agent (any provider) ──tool call──> RoomKit AIChannel
                                        │
                                   SandboxExecutor
                                        │
                              ContainerSandboxExecutor
                                        │
                    ┌───────────────────┼───────────────────┐
                    │                   │                   │
              DockerBackend      K8sBackend        SmolBSDBackend
                    │                   │                   │
              Container (37MB)     Pod (37MB)         VM (1GB)
                    │                   │                   │
              RtkCommandBuilder  RtkCommandBuilder  NativeCommandBuilder
                    │                   │                   │
              Token-optimized    Token-optimized    Standard output

Documentation

• Backends — Docker, Kubernetes, SmolBSD setup and comparison
• Command Builders — RTK vs Native, creating custom builders

License

MIT