Guide on KubeClaw

Dev Container

Mon, 01 Jan 0001 00:00:00 +0000

The project uses an aibox-generated Dev Container (Debian Trixie) as a self-contained, reproducible environment. Nothing needs to be set up on the host machine beyond Docker and an IDE with Dev Container support.

What the Dev Container Provides

OpenTofu – infrastructure provisioning (Terraform-compatible)
Ansible – server management (runs inside the container, no host install needed)
cloudflared – SSH ProxyCommand via Cloudflare Tunnel
ssh-agent – start inside the container to use passphrase-protected keys with Ansible
AI CLI tools – Codex and the aibox toolchain
Hugo + Docsy – documentation site (./scripts/serve-docs.sh at port 1313)
Persistence – .aibox-home/.ssh/ is bind-mounted read-write by this project, so setup-ssh.sh output, SSH config, and exported keys survive container rebuilds

Step 1: Prepare Persistent Directories

Create the persistent directories before opening the Dev Container:

Infrastructure (OpenTofu)

Mon, 01 Jan 0001 00:00:00 +0000

KubeClaw uses OpenTofu (Terraform-compatible) to provision all infrastructure on Hetzner Cloud. This page walks through the provisioning workflow step by step. See Variables Reference for all configurable options.

Step 1: Configure terraform.tfvars

cp terraform.tfvars.example terraform.tfvars

Edit terraform.tfvars with your settings:

hcloud_token = "your-hcloud-api-token"
root_password = "a-strong-root-password"
cluster_name = "k8s-cluster"

# Optional: auto-configure Cloudflare Tunnel on the master control node
# cloudflare_tunnel_token = "eyJ..."

SSH key options

No configuration needed. OpenTofu generates ED25519 keys and stores them in the state file.

| Advantage | Disadvantage |
|-----------|--------------|
| No manual key creation | State file contains private keys |
| Works out of the box | Keys lost if state is lost |

Create your own keys and reference them in `terraform.tfvars`:

```bash
ssh-keygen -t ed25519 -f ~/.ssh/k8s-cluster_control-node_key -C "control-node"
ssh-keygen -t ed25519 -f ~/.ssh/k8s-cluster_worker-node_key -C "worker-node"
```

```hcl
control_node_public_key = "ssh-ed25519 AAAA... control-node"
worker_node_public_key = "ssh-ed25519 AAAA... worker-node"
```

| Advantage | Disadvantage |
|-----------|--------------|
| Full control over key storage | Manual key management |
| State has no private keys | Must create keys before provisioning |
| Easy password manager integration | |

Step 2: Provision Infrastructure

tofu init # First time only
tofu apply

This creates:

Cloudflare Tunnel Setup

Mon, 01 Jan 0001 00:00:00 +0000

This guide walks through creating and configuring a Cloudflare Tunnel that provides secure SSH access to your KubeClaw cluster. The tunnel replaces the temporary admin node as the permanent access path – no open ports, no public SSH, outbound-only connectivity.

Why Cloudflare Tunnel?

KubeClaw nodes have no public IPv4 and no inbound SSH ports. Access works through one of two paths:

Path	When to use	How it works
Admin node (temporary)	Initial setup, before tunnel is ready	Jump host with public IPv6; SSH via `ProxyJump`
Cloudflare Tunnel (permanent)	After tunnel is configured	`cloudflared` on the master node connects outbound to Cloudflare’s edge; SSH proxied via `ProxyCommand cloudflared access ssh` on your local machine

After the tunnel is working, you disable the admin node (enable_admin_node = false in terraform.tfvars) and all SSH flows through Cloudflare.

Server Management (Ansible)

Mon, 01 Jan 0001 00:00:00 +0000

Ansible handles ongoing server management: system updates, security hardening, NAT64 configuration, and Kubernetes prerequisites. All playbooks run from the Dev Container.

Step 1: Set Up Ansible

1.1 Generate inventory

./scripts/generate-ansible-inventory.sh

The inventory (ansible/inventory.ini) is auto-generated. It defines three groups:

control_nodes – all control plane nodes
worker_nodes – all worker nodes
k8s_cluster – union of control and worker nodes

Warning

Never hand-edit `inventory.ini`. Regenerate after infrastructure changes with `./scripts/generate-ansible-inventory.sh`.

1.2 Load SSH keys

source ./scripts/ssh-agent-setup.sh

Important

The ssh-agent must be running with the cluster keys loaded before Ansible can connect. Run `source ./scripts/ssh-agent-setup.sh` in every new terminal session.

1.3 Test connectivity

cd ansible
ansible all -m ping

Step 2: Apply System Updates

ansible-playbook playbooks/update-system.yml

Target specific node groups or enable automatic reboots:

Kubernetes (kubeadm)

Mon, 01 Jan 0001 00:00:00 +0000

After provisioning the infrastructure with OpenTofu and configuring SSH access, deploy a standard Kubernetes cluster using kubeadm with Cilium as the CNI.

Why kubeadm + Cilium?

kubeadm: The official Kubernetes bootstrapper. Produces a standard, upstream cluster – exactly what the CKA exam expects. Full control over every component (etcd, kube-apiserver, kube-scheduler, kube-controller-manager).
Cilium: eBPF-based CNI providing advanced network policies with FQDN-based egress filtering – critical for restricting outbound traffic per namespace.

Step 1: Initialize the Control Plane (Dual-Stack)

SSH into the master control node. Prerequisites (containerd, kubeadm, kubelet, kubectl) are already installed via cloud-init when enable_k8s_prereqs = true (default).

OpenClaw Deployment

Mon, 01 Jan 0001 00:00:00 +0000

A step-by-step guide to deploying OpenClaw as an isolated AI assistant on the KubeClaw cluster, accessible via Telegram, WhatsApp, or Signal, with a web-based Control UI exposed through Cloudflare Tunnel.

Architecture Overview

┌─────────────────────────────────────────────────────────────────────┐
│ Hetzner Private Network │
│ (10.0.0.0/24) │
│ │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ Kubernetes Cluster (kubeadm) + Cilium │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ │ │
│ │ │ control-01 │ │ worker-01 │ │ │
│ │ │ (control plane)│◄─────►│ (worker node) │ │ │
│ │ │ 10.0.0.2 │ │ 10.0.0.3 │ │ │
│ │ │ │ │ │ │ │
│ │ │ ┌───────────┐ │ │ ┌───────────┐ │ │ │
│ │ │ │Block Vol │ │ │ │Block Vol │ │ │ │
│ │ │ │ 10 GB │ │ │ │ 10 GB │ │ │ │
│ │ │ └───────────┘ │ │ └───────────┘ │ │ │
│ │ └────────┬────────┘ └─────────────────┘ │ │
│ │ │ │ │
│ │ system-unrestricted namespace: │ │
│ │ └─ cloudflared (egress: ANY) │ │
│ │ │ │
│ │ apps-restricted namespace: │ │
│ │ └─ OpenClaw (Cilium FQDN egress whitelist) │ │
│ │ ├─ Telegram / WhatsApp / Signal │ │
│ │ └─ Control UI (:18789) │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ cloudflared │
│ (outbound only) │
└──────────────────────────────┼──────────────────────────────────────┘
 │
 ▼
 ┌───────────────────┐
 │ Cloudflare │
 │ Edge + Access │
 └─────────┬─────────┘
 │
 ┌─────────┼─────────┐
 │ │ │
 ▼ ▼ ▼
 [Telegram] [WhatsApp] [Signal]
 │
 ▼
 [Control UI]
 (browser dashboard)

Prerequisites

A running KubeClaw cluster (see Kubernetes guide)
Anthropic API key (console.anthropic.com)
At least one messaging channel:

Channel	What You Need
Telegram	Bot Token from @BotFather, your Telegram User ID
WhatsApp	A phone number with WhatsApp, access to scan a QR code
Signal	A dedicated phone number, `signal-cli` installed in the container

Start with Telegram

Telegram is the simplest channel to set up — it only requires a bot token and user ID, with no interactive pairing or additional dependencies.

Step 1: Infrastructure Setup

If you haven’t already set up the Hetzner Cloud infrastructure, follow the Quick Start and Kubernetes guide.