Katakate (k7) lets you run secure, lightweight VM sandboxes backed by Kata Containers and Firecracker, orchestrated with Kubernetes. This Quickstart gets you from zero to a working sandbox via CLI and Python SDK.
If you already installed k7 previously, consider running make uninstall before reinstalling to avoid stale cached files in a previous .deb.

​
Requirements

  • Linux (amd64) host with hardware virtualization (KVM)
    • Check: ls /dev/kvm should exist
    • Cloud guidance: AWS .metal, GCP (enable nested virtualization), Azure D/Ev series; typical VPS often lack KVM
  • One raw, unformatted disk for thin‑pool provisioning (recommended for many sandboxes)
  • Docker with Compose plugin (for the API)
    • Install Docker: curl -fsSL https://get.docker.com | sh
  • Ansible for the installer (Ubuntu):
sudo add-apt-repository universe -y
sudo apt update
sudo apt install -y ansible
  • Python 3.10+ on the client for the SDK
Tested setup example: Hetzner Robot instance, Ubuntu 24.04 (x86_64), with an extra empty NVMe disk (for the thin‑pool). See the detailed setup guide (PDF): k7_hetzner_node_setup.pdf.

​
Install the CLI (APT)

Install the k7 CLI on the node(s) that will host the VM sandboxes: 
sudo add-apt-repository ppa:katakate.org/k7
sudo apt update
sudo apt install k7

​
Install K7 on your node(s)

This installs and wires up Kubernetes (K3s), Kata, Firecracker, Jailer, and the devmapper snapshotter with thin‑pool provisioning: 
k7 install
Example output: k7 install
You should see “Installation completed successfully!” when done. Add -v for verbose output.

​
Start the API and manage keys

​
Start the API

k7 start-api
Example: k7 start-api

​
Check API status

k7 api-status
Example: k7 api-status

​
Get the public endpoint

k7 get-api-endpoint
Example: k7 get-api-endpoint

​
Generate an API key

k7 generate-api-key mykey
Example: k7 generate-api-key

​
Stop the API

k7 stop-api
Example: k7 stop-api
  • Ensure your user is in the docker group to manage the API containers.
  • API keys are stored at /etc/k7/api_keys.json by default. Authentication accepts X-API-Key header or Authorization: Bearer <token>.

​
Create your first sandbox via CLI

Example k7.yaml: 
name: demo
image: alpine:3.20
namespace: default
env_file: /root/secrets.env
limits:
  cpu: "100m"
  memory: "128Mi"
before_script: |
  # Installing curl. Egress open during before_script, then restricted (empty whitelist) afterwards
  apk add curl
  echo $ENV_VAR_1
egress_whitelist: []

​
Create a sandbox

# Uses k7.yaml in the current directory by default
k7 create
Example: k7 create

​
Shell into your sandbox

k7 shell demo
Example: k7 shell

​
List sandboxes

k7 list
Example: k7 list

​
Delete a sandbox

k7 delete my-sandbox-123

​
Delete all sandboxes

k7 delete-all

​
Prerequisites for the SDK

# Ensure the API is running and you have an endpoint and API key
k7 start-api
k7 get-api-endpoint
k7 generate-api-key my-key

​
Create your first sandbox via Python SDK

Install the SDK on your client machine: 
pip install katakate
Use the synchronous client: 
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"])  # or just print(sb.exec("echo hi"))

# List and cleanup
print(k7.list())
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())

​
Next steps

  • Explore the CLI guide: /guides/cli
  • Explore the Python SDK guide: /guides/python-sdk
  • Integrate with the REST API: /api/introduction