KATAKATE
Self-hosted secure VM sandboxes for AI compute at scale
Katakate aims to make it easy to create, manage and orchestrate lightweight safe VM sandboxes for executing untrusted code, at scale. It is built on battle-tested VM isolation with Kata, Firecracker and Kubernetes. It is orignally motivated by AI agents that need to run arbitrary code at scale but it is also great for:
Custom serverless (like AWS Fargate, but yours)
Hardened CI/CD runners (no Docker-in-Docker risks)
Blockchain execution layers for AI dApps
100% open‑source (Apache‑2.0). For technical support, write us at: [email protected]
The Tech Stack
Katakate is built on:
Kubernetes for orchestration, with K3s which is prod-ready and a great choice for edge nodes,
for orchestration, with K3s which is prod-ready and a great choice for edge nodes, Kata to encapsulate containers into light-weight virtual-machines,
to encapsulate containers into light-weight virtual-machines, Firecracker as the chosen VM, for super-fast boots, light footprints and minimal attack surface,
as the chosen VM, for super-fast boots, light footprints and minimal attack surface, Devmapper Snapshotter with thin-pool provisioning of logical volumes for efficient use of disk space shared by dozens of VMs per node.
Coming Soon
🛠️ Docker build / run / compose support inside the VM sandbox
/ / support 🌐 Multi-node cluster capabilities for distributed workloads
🔍 Cilium FQDN-based DNS resolution to safely whitelist domains, not just IP blocks
⚙️ Support other VMM such as Qemu for GPU workloads
Note: Katakate is currently in beta and under security review. Use with caution for highly sensitive workloads.
Usage
For usage you need:
Node(s) that will host the VM sandboxes
that will host the VM sandboxes Client from where to send requests
We provide a:
CLI : to use on the node(s) directly --> apt install k7
: to use on the node(s) directly --> API : deployed on the (master) node(s) --> k7 start-api
: deployed on the (master) node(s) --> Python SDK: Python client sync/async talking to API --> pip install katakate
Current requirements
For the node(s)
Ubuntu (amd64) host.
Hardware virtualization (KVM) available and accessible Check: ls /dev/kvm should exist. This is typically available on your own Linux machine. On cloud providers, it varies. Hetzner (the only one I tested so far) yes for their Robot instances only, i.e. "dedicated": robot.hetzner.com. AWS: only .metal EC2 instances. GCP: virtualization friendly, most instances, with --enable-nested-virtualization flag. Azure: Dv3, Ev3, Dv4, Ev4, Dv5, Ev5. Must be Intel/AMD x86, not ARM. Others: in general, hardware virtualization is not exposed on cloud VPS, so you'll likely want a dedicated / bare metal.
One raw disk (unformatted, unpartitioned) for the thin-pool that k7 will provision for efficient disk usage of sandboxes. Use ./utils/wipe-disk.sh /your/disk to wipe a disk clean before provisioning. DANGER: destructive - it will remove data/partitions/formatting/SWRAID.
Ansible (for installer): sudo add-apt-repository universe -y sudo apt update sudo apt install -y ansible
Docker and Docker Compose (for the API): curl -fsSL https://get.docker.com | sh
Already tested setups:
Hetzner Robot instance with Ubuntu 24.04, x86_64 arch, booked with 1 extra empty disk nvme2n1 for the thin-pool provisioning. See the setup guide (PDF): tutorials/k7_hetzner_node_setup.pdf.
For the client
Just recent Python.
Quick Start
Get your node(s) ready
First install k7 on your Linux server that will host the VMs:
sudo add-apt-repository ppa:katakate.org/k7 sudo apt update sudo apt install k7
Then let k7 get your node ready with everything:
$ k7 install Current task: Reminder about logging out and back in for group changes Installing K7 on 1 host(s)... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:01:41 ✅ Installation completed successfully!
Optionally pass -v for a verbose output.
This will install and most importantly connect together the following components:
Kubernetes (K3s prod-ready distribution)
Kata (for container virtualization)
Firecracker (as Virtual Machine Manager)
Jailer (to secure Firecracker VMs further into a chroot)
devmapper snapshotter with thin-pool provisioning of logical volumes for VM efficient disk memory usage
Careful design: config updates will not touch your existing Docker or containerd setups. We chose to use K3s' own containerd for minimal disruption. Installation may however overwrite existing installations of K3s, Kata, Firecracker, Jailer.
CLI Usage
You can run workloads directly from the node(s) using the CLI. To create a sandbox, just create a yaml config for it.
name : my-sandbox-123 image : alpine:latest namespace : default # Optional: restrict egress egress_whitelist : - " 1.1.1.1/32 " # Cloudflare DNS - " 8.8.8.8/32 " # Google DNS # Optional: resource limits limits : cpu : " 1 " memory : " 1Gi " ephemeral-storage : " 2Gi " # Optional: run before_script inside the container once at start. Network restrictions apply after the before-script, so you can install packages here, pull git repos, etc before_script : | apk add --no-cache git curl # Optional: load environment variables from a file. These will be available both during the before-script, and in the sandbox env_file : path/to/your/secrets/.env
Running commands
# Create a sandbox (uses k7.yaml in the current directory by default, but you can also pass: -f myfile.yaml) k7 create # List sandboxes k7 list # Delete a sandbox k7 delete my-sandbox-123 # Delete all sandboxes. You can also pass a namespace k7 delete-all
API usage
If you'd like to manage workloads remotely, just use the API:
# Start API server (containerized and SSL support with Cloudflared) k7 start-api # Generate API key k7 generate-api-key my-key1
Make sure your user is in the Docker group to be allowed to start or stop the API.
As for generating / listing / revoking keys, you might need sudo or root .
Python SDK Usage
After your k7 API is up, usage is very simple.
Install the Python SDK via:
pip install katakate
Or if you want async support:
pip install " katakate[async-sdk] "
Then use with:
from katakate import Client k7 = Client ( endpoint = 'https://' , api_key = 'your-key' ) # Create sandbox sb = k7 . create ({ "name" : "my-sandbox" , "image" : "alpine:latest" }) # Execute code result = sb . exec ( 'echo "Hello World"' ) print ( result [ 'stdout' ]) # List all sandboxes sandboxes = k7 . list () # Delete sandbox sb . delete ()
Async variant
import asyncio from katakate import AsyncClient async def main (): k7 = AsyncClient ( endpoint = 'https://' , api_key = 'your-key' ) print ( await k7 . list ()) await k7 . aclose () asyncio . run ( main ())
Tutorials
LangChain ReAct agent with a K7 sandbox tool Path: tutorials/langchain-react-agent Setup: copy .env.example to .env and fill K7_ENDPOINT/K7_API_KEY/OPENAI_API_KEY Run: python agent.py Try asking it anything! e.g. "List files from '/'"
Build from source
First install make if not already available:
sudo add-apt-repository universe -y sudo apt update sudo apt install make
To build the k7 CLI and API into .deb package:
make build
You can then install it with:
sudo make install
To uninstall later:
sudo make uninstall
Note: we recommend running make uninstall before reinstalling if it is not your first install, to avoid stale copies of cached files in the .deb package.
Build and run the API container
Local dev image:
# Build the API image locally make api-build-local # Run API using local image (no pull) make api-run-local
Build the katakate Python SDK from source
Preferred (uv):
# create env uv venv .venv-build . .venv-build/bin/activate # install directly from source in editable mode uv pip install -e .
Security
K7 sandboxes are hardened by default with multiple layers of security:
VM isolation : Kata Containers provide hardware-level isolation via lightweight VMs with Firecracker VMs are further restricted into a chroot using Jailer Kata's Seccomp restrictions are enabled
Linux capabilities : All capabilities are dropped by default ( drop: ALL ) for defense-in-depth Only explicitly add back capabilities you need via cap_add parameter allow_privilege_escalation is always set to false Seccomp profile: RuntimeDefault
Non-root execution : Optionally run containers and pods as non-root user (UID 65532): container_non_root : Run the main container as non-root and disable privilege escalation pod_non_root : Run the entire pod as non-root with consistent filesystem ownership (UID/GID/FSGroup 65532)
API security : API keys stored as SHA256 hashes with timing-attack-resistant comparison Expiry enforced; last-used timestamp recorded File-based storage with 600 permissions ( /etc/k7/api_keys.json by default)
Network policies : Complete network isolation for VM sandboxes Ingress isolation : All inter-VM communication is blocked by default to prevent sandbox-to-sandbox access Egress lockdown : Control outbound traffic with CIDR-based restrictions using Kubernetes NetworkPolicies DNS to CoreDNS always allowed when egress is locked down Administrative access via kubectl exec and k7 shell is preserved (uses Kubernetes API, not pod networking) Soon to come: Cilium integration for domain name whitelisting
More security features are currently on the roadmap, including integrating AppArmor.
Packaging & Releases
Layout uses src/ : CLI, API, core live under src/k7/ SDK under src/katakate/
: Root packaging targets the katakate SDK only; assets under src/k7/ are not part of the PyPI distribution.
SDK only; assets under are not part of the PyPI distribution. MANIFEST.in (for the katakate SDK) should include essentials like LICENSE and README.md only; deploy assets from src/k7/deploy/* belong to the Debian/CLI packaging flow, not to the PyPI package.
(for the SDK) should include essentials like and only; deploy assets from belong to the Debian/CLI packaging flow, not to the PyPI package. setup.py for katakate lives at repo root; packages from src/ .
for lives at repo root; packages from . The CLI Debian package is built via src/k7/cli/build.sh and produces dist/k7__amd64.deb .
and produces . CI (tags v* ) can publish the PyPI SDK and upload the .deb artifact.
Known issues