Prototype KubeClaw is a learning project exploring what a secure, scalable Kubernetes environment for AI agents looks like. It is not production ready and not beta. Expect breaking changes and unreviewed assumptions. Read the project status.

Development Setup

Local development workflow for infrastructure changes and the documentation site.

Getting started

Follow the Dev Container guide to set up your development environment. The aibox Dev Container includes OpenTofu, Ansible, cloudflared, Hugo, Node.js, Kubernetes clients, and AI assistants.

Documentation development

Preview the documentation site locally:

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

When using a remote Dev Container environment, forward port 1313 from your editor to view the preview.

Build the site:

./scripts/build-docs.sh

The build uses Hugo’s strict template and content validation. The first run installs the pinned Docsy asset dependencies locally and initializes the pinned Docsy theme submodule when needed.

Infrastructure development

If you have a Hetzner Cloud account and want to test infrastructure changes:

cp terraform.tfvars.example terraform.tfvars
# Edit terraform.tfvars with your API token

tofu init
tofu plan    # Preview changes
tofu apply   # Apply changes

Project conventions

See How to Contribute for code conventions and the contribution workflow.

Deploy documentation

To deploy the documentation to GitHub Pages:

./scripts/deploy-docs.sh

This is the standard documentation deployment. It builds the Hugo site locally and pushes the generated public/ directory to the root of the gh-pages branch. GitHub Pages must be configured to serve gh-pages from /; no GitHub Actions workflow is required or used.

The build and deployment scripts create an empty .nojekyll marker in the generated site and at the branch root, so GitHub Pages always serves the prebuilt output directly instead of processing it with Jekyll.

The same script can publish an archived documentation snapshot under a version path. For example:

DOCS_VERSION=v0.1 ./scripts/deploy-docs.sh

Add the corresponding entry to params.versions in hugo.yaml when a release is ready. The versioned build is published below the matching version path and uses that path as its canonical base URL.