infrastructure

Everything Kai needs to stand up and operate kai-server. Systemd units, shell scripts, k3s cluster manifests, and a small set of ward verbs for cluster-side bootstrap.

Layout

.
├── .agents/skills/   # canonical operator and repository skill provider
├── ansible/          # host and workstation convergence - see ansible/README.md
├── clusters/         # per-cluster state, one directory each for kai-server and ser8
├── terraform/        # AWS IAM, KMS, inventory, public assets, and Tailscale
├── deploy/           # cluster-wide manifests, plus Flux, Forgejo runners, and observability
├── systemd/          # systemd unit files
├── scripts/          # unit ExecStart/ExecPre scripts and Python helpers for the just verbs
├── fail2ban/         # jail and filter config
├── sudoers/          # privileged-verb sudoers fragments
├── config/           # small shared config, currently the required-status-checks list
├── caddy/            # legacy, pre-traefik
├── docs/             # durable feature and convergence documentation
├── bootstrap.sh      # first-run host bootstrap
├── justfile          # dev verbs
└── .ward/ward.yaml   # catalog metadata

Eco server setup notes live in the eco-server-setup skill. Disk usage, rootfs pressure, Kubernetes DiskPressure, and Forgejo storage incidents route through the ops-investigation-disk-pressure skill. K3s workload startup, Forgejo runner, and cluster connectivity incidents route through the symptom-driven skills indexed in docs/k3s-deploy-notes-topology.md.

Operating the cluster

Cluster-bootstrap verbs are declared in the justfile and call their scripts/k8s/ helpers directly. Common verbs run via just <verb>:

just cert-manager                                                        # re-apply cert-manager + ClusterIssuers
just aws-secrets aws_access_key_id=<ID> aws_secret_access_key=<SECRET>   # bootstrap external-secrets + aws-credentials

Cluster passthroughs (SSM, kubectl, Forgejo, Tailscale) run through aosguard ops. K3s service ops go over Tailscale SSH: restart k3s with ssh kai-server -- sudo systemctl restart k3s.service. Game-server systemd ops still live in coily core (kai-server keeps coily until gaming is ported): tail or restart game servers with coily gaming <eco|core-keeper|icarus|factorio> ....

See docs/ for:

• architecture.md - top-down view of what runs on kai-server
• certificates.md - DNS-01 via Route 53 cert flow, replacing the HTTP-01 and hairpin-NAT workarounds
• windows.md - BrowserPicker opens complete Forgejo deep links in the installed Chrome app

Commands

Dev commands are declared in the justfile. Run them as just <verb>, and run just alone to list every one.

See also

• AGENTS.md - agent-facing operating rules.
• docs/FEATURES.md - inventory of what ships today.
• justfile - dev verbs. Agents route through just, not bare uv / python / npm / cargo / dotnet.

Cross-reference convention: features-release-tooling.md. Origin: coilysiren/agentic-os-kai#313.