Quickstart

k7 lets you run secure VM sandboxes on Kubernetes — Firecracker, QEMU + Longhorn, or k7d (natively or under the Firecracker jailer). This Quickstart gets you from zero to a working sandbox via CLI and Python SDK.

Requirements#

• Ubuntu host with hardware virtualization (KVM)
  • Check: ls /dev/kvm should exist
  • kfd and kql: amd64 or arm64. k7d and k7d-fc are amd64 / x86_64 only.
  • Cloud guidance: AWS .metal, GCP (enable nested virtualization), Azure D/Ev series; typical VPS often lack KVM. Hetzner: Robot dedicated only (not Cloud VPS).
• For the kfd (Firecracker) backend: one raw, unformatted disk for the LVM thin-pool. kql, k7d, and k7d-fc do not need a spare disk.
• No Docker and no source checkout. 0.5.0 deploys the signed GHCR k7-api image by digest (images.lock.yaml, cosign-verified). Building k7-api:local from a checkout, which 0.4.0 did by default, is opt-in with k7 install --api-image local.
• Ansible for the installer (Ubuntu), on the machine that runs k7 install:

sudo add-apt-repository universe -ysudo apt updatesudo apt install -y ansible

• Python 3.10+ on the client for the SDK

Install the CLI#

The Launchpad PPA publishes 0.5.0 (k7 -V after install). PyPI k7-sdk is the same version.

sudo add-apt-repository ppa:katakate.org/k7sudo apt updatesudo apt install k7k7 -V   # 0.5.0

The same package is on the GitHub release if you prefer not to add the PPA:

curl -fsSL -O https://github.com/Katakate/k7/releases/download/v0.5.0/k7_0.5.0_amd64.debsudo apt install ./k7_0.5.0_amd64.deb

Install K7 on your node(s)#

k7 install runs from any directory — no clone, no Docker. It deploys the signed ghcr.io/katakate/k7-api image at the digest recorded in the release’s images.lock.yaml, and verifies the cosign signature before use.

k7 install --backend kfd,kql,k7d,k7d-fc --api-mode development

Two flags are required (no silent defaults):

• --backend: kfd needs a spare raw disk; kql uses Longhorn on the OS disk; k7d is the warm-fork daemon; k7d-fc adds jailed Firecracker v1.16.2; none is control-plane only. The playbook pins k7d 0.7.0.
• --api-mode: production (every API key belongs to a tenant, HTTPS only, metering mandatory) or development (unscoped keys keep working, remote install allowed). Documented in Hardening.

That installs and wires up Kubernetes (K3s v1.36.5+k3s1, override with --k3s-version), Cilium, Kata, Firecracker + Jailer + thin-pool (kfd), QEMU + Longhorn (kql), and the k7d daemon + RuntimeClass k7 / k7-fc (k7d, k7d-fc). It also deploys the k7-api (2 replicas) over HTTPS with a cluster CA, the non-privileged k7-agent DaemonSet, Prometheus metrics and the metering spool. Pass -v for verbose output. Two-node / HA inventories: Multi-node clusters; install-time knobs (--api-allow-cidr, --api-hostname, --oidc-*, --dns-upstream, --metering-*, --hubble): CLI reference. To install a k7d tarball you built yourself instead of GitHub v0.7.0, pass --k7d-artifact /path/to/k7d-v0.9.0-x86_64-linux.tar.gz.

Already running Kubernetes (RKE2, kubeadm, EKS)? The same stack ships as a Helm chart (deploy/helm/k7) that never installs Kubernetes, the CNI or the CSI driver: see Helm chart.

The API and managing keys#

k7 install deploys the K7 API automatically as a k7-api Deployment in kube-system. K3s keeps it running and reschedules it on failure — there’s no separate “start” step. If you want a CLI-only install with no API deployed, pass --no-api to k7 install.

Check API status#

On a cluster node (needs kubectl / k3s kubectl):

k7 api status

From a laptop after k7 config set, the same command probes GET /health on the configured URL instead of crashing. Replica counts still need kubectl on the node.

Get the endpoint#

k7 api endpoint          # https://<first-master-ip>:31007

On a node this is /etc/k7/api_endpoint. From a laptop it prints the URL you configured.

Trust the cluster CA from your laptop#

The default install serves the API over HTTPS with a certificate signed by a cluster CA the playbook minted (Let’s Encrypt cannot issue for a bare IP). Copy the CA off the node once and point the CLI at it:

scp root@<node>:/etc/k7/tls/ca.crt ./k7-ca.crtk7 config set api.url https://<node-ip>:31007k7 config set api.ca  ./k7-ca.crtk7 config set api.key <key>          # from the next step

If you installed with --api-hostname k7.example.com, the certificate is publicly trusted and api.ca is unnecessary. On the node itself the CLI finds /etc/k7/api_endpoint and /etc/k7/tls/ca.crt automatically; you still have to k7 config set api.key with the token generate-api-key printed.

Generate an API key#

Every key has a role (--role is required): read-only and user belong to a tenant, operator and admin are cluster-wide. In --api-mode development a user key without --tenant keeps the pre-0.5 “unscoped” behaviour; in production every read-only/user key needs a tenant.

k7 generate-api-key mykey --role admin                       # cluster-wide, manages keys/tenants/nodesk7 tenant create acme -n acme-dev -n acme-prod               # a tenant owns namespaces (and quotas, defaults)k7 generate-api-key acme-ci --role user --tenant acme        # reaches every namespace of acmek7 generate-api-key acme-ro --role read-only --tenant acme -n acme-dev   # narrowed further to one namespace

A tenant key cannot list or mutate another tenant’s namespaces and cannot run all-namespaces operations. Details and quotas: Tenants, roles and OIDC.

Save the printed key. k7 generate-api-key stores only a hash in the kube-system/k7-api-keys Secret — the raw token is shown once and is not auto-loaded on the node. Key commands edit that Secret through kubectl, so run them on a server node (or add --api to go through k7-api with an admin credential). Point the CLI at it (laptop or node):

k7 config set api.url https://<node-ip>:31007   # laptop; on the node this is auto-read from /etc/k7/api_endpointk7 config set api.ca  ./k7-ca.crt                # laptop; on the node /etc/k7/tls/ca.crt is used automaticallyk7 config set api.key <the-printed-key>k7 list

Humans can skip keys altogether: with k7 install --oidc-issuer … --oidc-client-id …, k7 login signs in through the IdP (device flow by default, --browser for Authorization Code + PKCE) and stores a short-lived token; k7 whoami shows the resolved role.

Temporarily disable / re-enable the API#

k7 api disable        # scale k7-api to 0 (temporary off; records the replica count)k7 api enable         # scale back to the recorded count (default 2)

Create your first sandbox via CLI#

Example k7.yaml:

name: demoimage: alpine:3.20namespace: defaultbackend: k7d# env_file: /root/secrets.env   # optional; omit unless that file exists on the nodelimits:  cpu: "1"  memory: "1Gi"before_script: |  # Installing curl. Egress is open during before_script, then restricted (empty whitelist) afterwards.  apk add curlegress_whitelist: []

Do not use cpu: 100m / memory: 128Mi. Kata Firecracker refuses hypervisor memory below 256Mi (io.katacontainers.config.hypervisor.default_memory) and the pod stays ContainerCreating until create times out. Use at least 1Gi (or omit limits).

Create a sandbox#

# Uses k7.yaml in the current directory by defaultk7 create# Or pick a backend (kfd | kql | k7d | k7d-fc)k7 create -f k7.yaml --backend k7d# Need docker build / docker run inside the sandbox? (see the Docker guide)k7 create --docker --backend k7d --egress-open builder ubuntu:24.04

Shell into your sandbox#

k7 exec demo -- echo hello          # works from a laptop via the APIk7 shell demo                      # interactive; node-local (needs kubectl)

List sandboxes#

k7 list

Delete a sandbox#

k7 delete my-sandbox-123

Delete all sandboxes#

k7 delete-all

Prerequisites for the SDK#

# `k7 install` already deployed the API; just grab the endpoint and a keyk7 api endpointk7 generate-api-key my-key --role user      # add --tenant <name> in production mode

Create your first sandbox via Python SDK#

Install the SDK on your client (laptop), not necessarily on the cluster node:

pip install k7-sdk==0.5.0

A freshly installed Ubuntu node does not include python3-venv. If you run the SDK on the node: sudo apt install -y python3-venv python3-pip, then python3 -m venv ~/k7sdk && ~/k7sdk/bin/pip install k7-sdk==0.5.0. pip install --break-system-packages k7-sdk==0.5.0 also works on Ubuntu 24.04.

Use the synchronous client:

from k7_sdk import Clientimport time# verify_ssl takes the CA bundle path on the default (cluster-CA) install;# leave it at True for a Let's Encrypt (--api-hostname) cluster.k7 = Client(endpoint="https://<node-ip>:31007", api_key="<your-key>", verify_ssl="./k7-ca.crt")sb = k7.create({    "name": "my-sandbox",    "image": "alpine:latest"})# POST returns once objects exist; poll until Ready before exec.deadline = time.time() + 120while time.time() < deadline:    for s in k7.list():        if s["name"] == "my-sandbox" and s.get("ready") in (True, "True"):            break    else:        time.sleep(2)        continue    breakresult = sb.exec('echo "Hello World"')print(result["stdout"])print(k7.list())sb.delete()

Async variant:

import asynciofrom k7_sdk import AsyncClientasync def main():    k7 = AsyncClient(endpoint="https://<node-ip>:31007", api_key="<your-key>", verify_ssl="./k7-ca.crt")    print(await k7.list())    await k7.aclose()asyncio.run(main())

Next steps#

• Explore the CLI guide
• Explore the Python SDK guide
• Run Docker inside a sandbox
• Integrate with the REST API