Quickstart

sudo add-apt-repository universe -y
sudo apt update
sudo apt install -y ansible

sudo add-apt-repository ppa:katakate.org/k7
sudo apt update
sudo apt install k7
k7 -V   # 0.4.0

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

git clone --branch v0.4.0 https://github.com/Katakate/k7.git
cd k7
k7 install --backend kfd,kql,k7d,k7d-fc

k7 api status

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

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

k7 generate-api-key mykey                 # unrestricted (all namespaces)
k7 generate-api-key tenant-a -n team-a    # scoped to one namespace (repeat -n)

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

k7 api disable        # scale k7-api to 0 (temporary off)
k7 api enable         # scale back to 1

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

# Uses k7.yaml in the current directory by default
k7 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

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

k7 list

k7 delete my-sandbox-123

k7 delete-all

# `k7 install` already deployed the API; just grab the endpoint and a key
k7 api endpoint
k7 generate-api-key my-key

pip install k7-sdk==0.4.0

from k7_sdk import Client
import 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() + 120
while 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
    break

result = sb.exec('echo "Hello World"')
print(result["stdout"])

print(k7.list())
sb.delete()

import asyncio
from k7_sdk import AsyncClient

async 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())