---
title: "Quickstart"
description: "Install k7, prepare your node, start the API, and run your first sandbox"
---

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.

<Note>
If you already installed k7 previously, consider running `make uninstall` before reinstalling to avoid stale cached files in a previous `.deb`.
</Note>

## 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):

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

- Python 3.10+ on the client for the SDK

<Info>
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): <a href="/tutorials/k7_hetzner_node_setup.pdf" target="_blank" rel="noopener noreferrer">k7_hetzner_node_setup.pdf</a>.
</Info>

## Install the CLI (APT)

Install the `k7` CLI on the node(s) that will host the VM sandboxes:

```bash
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:

```bash
k7 install
```

![Example output: k7 install](/images/ex-install.png)

<Check>
You should see "Installation completed successfully!" when done. Add `-v` for verbose output.
</Check>

## Start the API and manage keys

### Start the API

```bash
k7 start-api
```

![Example: k7 start-api](/images/ex-start-api.png)

### Check API status

```bash
k7 api-status
```

![Example: k7 api-status](/images/ex-api-status.png)

### Get the public endpoint

```bash
k7 get-api-endpoint
```

![Example: k7 get-api-endpoint](/images/ex-get-api-endpoint.png)

### Generate an API key

```bash
k7 generate-api-key mykey
```

![Example: k7 generate-api-key](/images/ex-generate-api-key.png)

### Stop the API

```bash
k7 stop-api
```

![Example: k7 stop-api](/images/ex-stop-api.png)

<Info>
- 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>`.
</Info>

## Create your first sandbox via CLI

Example `k7.yaml`:

```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

```bash
# Uses k7.yaml in the current directory by default
k7 create
```

![Example: k7 create](/images/ex-create.png)

### Shell into your sandbox

```bash
k7 shell demo
```

![Example: k7 shell](/images/ex-shell.png)

### List sandboxes

```bash
k7 list
```

![Example: k7 list](/images/ex-list.png)

### Delete a sandbox

```bash
k7 delete my-sandbox-123
```

### Delete all sandboxes

```bash
k7 delete-all
```

### Prerequisites for the SDK

```bash
# 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:

```bash
pip install katakate
```

Use the synchronous client:

```python
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:

```python
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`