Dev Container

Set up the aibox Dev Container that carries every tool this project needs.

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:

git clone <repo-url>
cd kubeclaw

# Create the persistent SSH directory mounted at /home/aibox/.ssh.
mkdir -p .aibox-home/.ssh
chmod 700 .aibox-home/.ssh

The .aibox-home/ directory is gitignored. Its .ssh/ subdirectory holds your private keys, SSH configuration, and known_hosts without risking a commit of secrets.

Step 2: Open in Dev Container

1. Install the [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension
2. Open the project folder in VS Code
3. Click **"Reopen in Container"** when prompted, or press ++cmd+shift+p++ and select **Dev Containers: Reopen in Container**

The generated setup uses Docker Compose. Use your editor’s Dev Container command rather than docker build directly so the generated Compose mounts, including the persistent aibox home directory, are applied.

Step 3: Start SSH Agent

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

Note

No SSH keys exist yet at this point -- they are created later during [Infrastructure provisioning](/kubeclaw/docs/guide/infrastructure/). This step starts the ssh-agent and fixes SSH directory permissions, preparing the environment for later steps.

Important

The `source` command is required -- running the script without `source` starts the agent in a subprocess that terminates immediately.

SSH persistence

Docker bind mounts from macOS may not preserve Unix permissions. The `ssh-agent-setup.sh` script automatically fixes SSH directory permissions on every run. The `.aibox-home/.ssh/` directory stores SSH private keys, SSH config, and `known_hosts` -- all exported or generated by `setup-ssh.sh`. Everything survives container rebuilds.

Step 4: Verify Setup

Confirm that the essential tools are available:

tofu --version
ansible --version
hugo version
npm --version

Preview the documentation:

./scripts/serve-docs.sh
# Open http://localhost:1313 in your browser