KATAKATE Self-hosted secure VM sandboxes for AI compute at scale <a href="https://katakate.org"><img src="https://img.shields.io/badge/website-katakate.org-orange"></a> <a href="https://github.com/Katakate/k7/stargazers"><img src="https://img.shields.io/github/stars/Katakate/k7?style=social"></a> <a href="https://docs.katakate.org"> <img src="https://img.shields.io/badge/docs-docs.katakate.org-orange" /> </a> <a href="https://news.ycombinator.com/item?id=45656952"> <img src="https://img.shields.io/badge/Show%20HN-%231%20🔥-FF6600" alt="Show HN #1"> </a> <a href="assets/show-hn_nb1_post-id-45656952.png" title="Screenshot proof">📸</a> <a href="https://console.dev"> <img src="https://img.shields.io/badge/Featured-Console.dev-4F39F5" alt="Featured on Console.dev"> </a> <a href="assets/k7-console-dev.png" title="Screenshot proof">📸</a> <a href="https://changelog.com/news/169"> <img src="https://img.shields.io/badge/Featured-Changelog-59B287" alt="Featured on Changelog"> </a> <a href="https://www.youtube.com/watch?v=2tgqzZvmbak"> <img src="https://img.shields.io/badge/GitHub%20Trending-Oct%2023%2C%202025-black?logo=github" alt="GitHub Trending (Oct 23, 2025)"> </a> <img src="assets/k7-cover-upgrade.png" alt="Katakate Logo" width="3600" style="vertical-align: middle;"/> <a href="https://deepwiki.com/Katakate/k7"> <img src="https://deepwiki.com/badge.svg" /> </a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg"></a> <img src="https://img.shields.io/badge/install%20with-apt-blue?logo=debian"> <img src="https://img.shields.io/pypi/v/katakate"> <img src="assets/demo-k7.gif" alt="K7 Demo" width="900"/>

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: hi@katakate.org

<h3 align="left"> The Tech Stack </h3>

Katakate is built on:

Kubernetes for orchestration, with K3s which is prod-ready and a great choice for edge nodes,
Kata to encapsulate containers into light-weight virtual-machines,
Firecracker 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.

<h3 align="left"> Coming Soon </h3>

🛠️ Docker <code>build</code> / <code>run</code> / <code>compose</code> support inside the VM sandbox
🌐 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

📋 See ROADMAP.md for the complete feature roadmap and project priorities.

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
Client from where to send requests

We provide a:

CLI: to use on the node(s) directly --> apt install k7
API: deployed on the (master) node(s) --> k7 start-api
Python SDK: Python client sync/async talking to API --> pip install katakate

Current requirements

For the node(s)

Ubuntu (amd64 or arm64) 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 (Intel/AMD x86) or Dpdsv5, Dpldsv5, Epsv5 (ARM64).
  - DigitalOcean: Premium Intel and AMD droplets with nested virtualization enabled.
  - 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 or ARM64 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.

It will also tell you which raw disk was auto-selected for the LVM thin-pool. If you prefer, specify the disk explicitly:
k7 install --disk /dev/nvme2n1

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.

k7.yaml example:

name: my-sandbox-123
image: alpine:latest
namespace: default

# Optional: restrict egress (safe pattern: whitelist only your own egress proxy IP)
egress_whitelist:
  - "10.0.0.5/32"     # Your private egress proxy/gateway

# 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://<your-endpoint>', 
  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://<your-endpoint>', 
      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:

K7

Install / Use

README