ServerClaw Platform

Forkable infrastructure-as-code for taking a bare Debian 13 server to a fully managed Proxmox VE platform with 77+ self-hosted services — deployed, monitored, and recoverable from a single repository.

Platform Status

Generated from canonical repository state by scripts/generate_status_docs.py. Do not edit this block by hand.

Current Values

Field	Value
Repository version	0.179.48
Platform version	0.178.225
Observed check date	2026-04-03
Observed OS	Debian 13
Observed Proxmox version	9.1.6
Observed kernel	6.17.13-2-pve

Topology Summary

Field	Value
Managed guest count	17
Running guest count	10
Template VM present	true
Declared services	71
Publicly published services	47

Service Exposure Summary

Exposure Model	Services
edge-published	38
edge-static	1
informational-only	4
private-only	28

Latest Live-Apply Evidence

Capability	Receipt
fork_services	2026-04-27-ws-0372-0fork-services-all-7-deployed
restic_config_backup	2026-04-21-adr-0373-service-registry-and-derived-defaults-mainline-live-apply
repo_intake	2026-04-21-adr-0373-service-registry-and-derived-defaults-mainline-live-apply
platform_ops	2026-04-21-adr-0391-cpu-only-operational-automation-live-apply
platform	2026-04-21-adr-0373-service-registry-and-derived-defaults-mainline-live-apply
directus	2026-04-15-adr-0372-data-driven-playbook-composition-mainline-live-apply
validation_toolkit	2026-04-14-adr-0369-python-validation-toolkit-mainline-live-apply
service_definition_catalog_assembly	2026-04-14-adr-0324-service-definition-catalog-assembly-mainline-live-apply
repowise	2026-04-14-adr-0371-parameterized-service-verification-tasks-mainline-live-apply
redpanda	2026-04-14-adr-0368-docker-compose-jinja2-macro-library-mainline-live-apply
minio	2026-04-14-adr-0368-docker-compose-jinja2-macro-library-mainline-live-apply
livekit	2026-04-14-adr-0370-service-lifecycle-task-includes-mainline-live-apply
litellm	2026-04-14-adr-0371-parameterized-service-verification-tasks-mainline-live-apply
librechat	2026-04-14-adr-0371-parameterized-service-verification-tasks-mainline-live-apply
gitea	2026-04-14-adr-0368-docker-compose-jinja2-macro-library-mainline-live-apply
postgres_vm	2026-04-13-adr-0359-declarative-postgresql-client-registry-live-apply
woodpecker	2026-04-12-ws-0025-compose-stack-lifecycle-mainline-live-apply
ops_portal	2026-04-12-adr-0381-login-service-contracts-mainline-live-apply
neko	2026-04-12-adr-0380-neko-exact-main-live-apply
mail_platform	2026-04-12-ws-0025-compose-stack-lifecycle-mainline-live-apply

Showing 20 of 183 capability receipts. Full history: live-apply evidence history

Version Summary

Generated from canonical repository state by scripts/generate_status_docs.py. Do not edit this block by hand.

Field	Value
Repository version	0.179.48
Platform version	0.178.225
Observed OS	Debian 13
Observed Proxmox installed	true
Observed PVE manager version	9.1.6
Declared services	71

Quick Start

Try it locally (Docker, no server needed)

git clone https://github.com/baditaflorin/ServerClaw.git
cd ServerClaw
make init-local              # Generate SSH keys and secrets
make docker-dev-up           # Start 4 containers (8 GB RAM, ARM Mac native)
make docker-dev-converge     # Deploy services via Ansible

See docker-dev/README.md for details.

Deploy to a real server

git clone https://github.com/baditaflorin/ServerClaw.git
cd ServerClaw
make init-local              # Generate SSH keys and secrets
make generate-inventory      # Generate inventory/hosts.yml from platform-host.yml
# Edit inventory/group_vars/all/identity.yml (domain, operator name/email)
make bootstrap               # Full staged bootstrap with validation gates

See docs/runbooks/bootstrap-from-scratch.md for the complete walkthrough.

AI-Native Infrastructure

This platform is built for AI-assisted operations. Every architectural decision, deployment procedure, and operational runbook is written so that AI coding assistants (Claude Code, GPT, Codex) can read, understand, and execute them.

• CLAUDE.md — Claude Code session protocol with checklists and context
• AGENTS.md — Multi-agent coordination rules and handoff protocol
• 515+ ADRs — Every architectural decision documented and indexed
• 278+ runbooks — Step-by-step procedures an AI agent can follow
• Workstream tracking — Parallel agent sessions coordinate via YAML manifests

Point Claude Code at this repo and it knows how to deploy, debug, and extend every service.

Control Plane Lanes

Generated from canonical repository state by scripts/generate_status_docs.py. Do not edit this block by hand.

Lane Summary

Lane	Title	Transport	Surfaces	Primary Rule
command	Command Lane	ssh	2	Use SSH only for command-lane access.
api	API Lane	https	14	Default new APIs to internal-only or operator-only publication.
message	Message Lane	authenticated_submission	2	Submit platform mail through the internal mail platform rather than arbitrary external SMTP relays.
event	Event Lane	mixed	16	Event sinks must be documented and intentionally reachable.

API Publication Tiers

Tier	Title	Surfaces	Summary
internal-only	Internal-Only	20	Reachable only from LV3 private networks, loopback paths, or explicitly trusted control-plane hosts.
operator-only	Operator-Only	7	Reachable only from approved operator devices over private access such as Tailscale.
public-edge	Public Edge	3	Intentionally published on a public domain through the named edge model.

What This Is

A single Git repository that contains everything needed to operate a self-hosted platform:

Layer	What	Count
Architecture decisions	docs/adr/	515+ ADRs
Ansible roles	collections/ansible_collections/lv3/platform/roles/	169 roles
Playbooks	collections/ansible_collections/lv3/platform/playbooks/	66 playbooks
Operational runbooks	docs/runbooks/	278+ runbooks
Automation scripts	scripts/	373+ scripts
Validation tests	tests/	Automated regression suite

Services included

SSO (Authentik), secrets (OpenBao), databases (PostgreSQL), reverse proxy (Nginx), monitoring (Grafana + Prometheus), CI/CD (Woodpecker, Semaphore), Git hosting (Gitea), object storage (MinIO), container registry (Harbor), AI/LLM (Ollama, Dify, LiteLLM, LibreChat, Open WebUI), project management (Plane, Vikunja), communication (Mattermost, Matrix), wiki (Outline), analytics (Plausible, Superset), workflow automation (n8n, Windmill, Temporal), and many more.

Forking This Repo

The platform is designed to be forked. One file controls your identity:

# inventory/group_vars/all/identity.yml — the ONLY file you must edit to rebrand
platform_domain: yourdomain.com
platform_operator_email: you@yourdomain.com
platform_operator_name: "Your Name"

Everything else derives from these values via Ansible templating.

Fork checklist

1. Edit inventory/group_vars/all/identity.yml (domain, name, email)
2. Run make generate-inventory — generates inventory/hosts.yml from inventory/host_vars/platform-host.yml
3. Run make init-local to generate secrets
4. Choose a provider profile (cloud, generic Debian, homelab)
5. Run make bootstrap or make docker-dev-up

See docs/runbooks/bootstrap-from-scratch.md.

Development Environment

Three tiers, all using Docker containers as VM stand-ins:

Tier	Containers	RAM	ARM Mac	What works
Minimal	4 (PG, control, nginx, monitoring)	8 GB	native	SSO, secrets, DB, proxy
Full	7 (all VMs)	16 GB	native	All services
Proxmox	1 QEMU host	32 GB	x86 only	Full PVE bootstrap

make docker-dev-up           # Tier 1
make docker-dev-up-full      # Tier 2
make docker-dev-converge     # Run Ansible against containers
make docker-dev-down         # Cleanup

Architecture

Proxmox VE Host (Debian 13, bare metal)
  |
  +-- nginx-edge        (edge VM)      Reverse proxy, TLS termination
  +-- docker-runtime    (runtime VM)   Primary application runtime
  +-- docker-build      (build VM)     CI/CD build server
  +-- monitoring        (monitoring)   Grafana, Prometheus, Alertmanager
  +-- postgres          (database VM)  Shared PostgreSQL 16
  +-- backup            (backup VM)    Proxmox Backup Server
  +-- runtime-control   (control VM)   API gateway, agent tools
  +-- runtime-ai        (AI runtime)   GPU workloads (Ollama, inference)
  +-- [additional VMs per topology]

All guest VMs are managed declaratively. inventory/host_vars/platform-host.yml is the single source of truth for VM topology (VMID, IP, RAM, cores). Running make generate-inventory derives inventory/hosts.yml and all Ansible host variables from it — no manual IP editing.

Key Concepts

• Identity isolation: All operator-specific values live in one file (identity.yml). Zero hardcoded domains or hostnames in role code.
• Secret management: Secrets documented in config/controller-local-secrets.json. .local/ directory holds runtime secrets (never committed). make init-local generates everything from the manifest.
• Derive, don't declare: derive_service_defaults computes 15-25 variables per service from a registry — roles don't repeat boilerplate.
• Generated inventory: inventory/hosts.yml is machine-generated from proxmox_guests in platform-host.yml. Edit the source, not the output.
• ADR governance: Every architectural decision is recorded and indexed. Pre-commit hooks enforce status transitions.
• Verification gates: make verify-bootstrap-proxmox, make verify-bootstrap-guests, make verify-platform validate state between stages.
• Static analysis gate: Three blocking checks run without Docker on every push — cross-catalog referential integrity (validate_cross_catalog_integrity.py), Python type-safety + bandit SAST (make validate-types), and Z3 formal proofs of the waiver escalation state machine (verify_waiver_escalation.py). See docs/runbooks/validation-gate.md for details.

Repository Structure

.
├── collections/ansible_collections/lv3/platform/
│   ├── roles/           # 169 Ansible roles
│   ├── playbooks/       # 66 playbooks
│   └── plugins/         # Custom filters and callbacks
├── inventory/
│   ├── hosts.yml        # GENERATED — see scripts/generate_inventory.py
│   ├── hosts-docker.yml # Docker dev inventory
│   └── group_vars/      # Platform configuration
├── config/
│   ├── provider-profiles/  # Bootstrap profiles per hosting provider
│   └── controller-local-secrets.json  # Secret manifest
├── docker-dev/          # Docker development environment
│   ├── images/vm-base/  # Container-as-VM base image
│   ├── minimal/         # Tier 1 compose (4 containers)
│   └── full/            # Tier 2 compose (7 containers)
├── docs/
│   ├── adr/             # 515+ architecture decision records
│   ├── runbooks/        # 278+ operational runbooks
│   └── templates/       # Jinja2 templates for generated docs (incl. this README)
├── scripts/             # 373+ automation scripts
├── local-overlay-template/  # Scaffold for .local/ secrets directory
└── Makefile             # 35+ automation targets

Full layout: .repo-structure.yaml

Make Targets

Target	Description
make init-local	Initialize .local/ overlay with SSH keys and secrets
make generate-inventory	Regenerate inventory/hosts.yml from proxmox_guests in host_vars/platform-host.yml
make validate-generated-inventory	Exit 1 if inventory/hosts.yml is out of sync with proxmox_guests
make bootstrap	Full platform bootstrap from bare Debian 13 (ADR 0386)
make bootstrap-minimal	Bootstrap critical path only (PG + Authentik + Nginx + OpenBao)
make docker-dev-up	Start minimal Docker dev environment (Tier 1)
make docker-dev-converge	Run Ansible convergence against Docker dev containers
make converge-<service>	Deploy a specific service
make verify-platform	Verify critical platform services are healthy
make validate	Run full validation suite (YAML, syntax, lint, cross-catalog, types)
make validate-types	Pyright type-check + bandit SAST on Python scripts and Ansible plugins
make validate-cross-catalog	Cross-catalog referential integrity check
make generate-readme	Regenerate README.md from docs/templates/README.md.j2
make validate-generated-readme	Exit 1 if README.md is out of sync with template
make publish-serverclaw	Dry-run: sanitize repo and check for leaks (no push)

Documentation

Resource	Location
Bootstrap guide	docs/runbooks/bootstrap-from-scratch.md
ADR index	docs/adr/.index.yaml
Runbooks	docs/runbooks/
Docker dev guide	docker-dev/README.md
Contributing	CONTRIBUTING.md
Agent guide	AGENTS.md
Release notes	docs/release-notes/README.md
Changelog	changelog.md

Document Index

Generated from canonical repository state by scripts/generate_status_docs.py. Do not edit this block by hand.

Core Documents

• Changelog
• Release notes
• Repository map
• Assistant operator guide
• Release process
• Workstreams registry
• Workstreams guide

Discovery Indexes

• ADR index
• Runbooks directory
• Workstreams directory
• Release notes index
• Generated docs directory

Recently Merged Workstreams

Generated from canonical repository state by scripts/generate_status_docs.py. Do not edit this block by hand.

Showing 25 of 343 merged or live-applied workstreams. Full history: merged workstream history

ADR	Title	Status	Doc
0470	Per-deployment fixture inventory + matrix CI	merged	0470-deployment-fixture-matrix.md
0448	Per-deployment connection registry + run_with_deployment wrapper + topology role auto-fill	merged	0448-deployment-connection-registry-and-wrapper.md
0409	Accept clean ignored HTTPS alert outputs while rejecting present drift	merged	ws-0500-https-alert-runtime-output-gate.md
0407	Keep the ServerClaw host template aligned with the edge route catalog	merged	ws-0511-serverclaw-public-route-template.md
0407	Ops Portal Sibling-Link IaC Substitution	merged	0407-generic-by-default-local-overlay-architecture.md
0374	Resolve generic subdomain catalog entries for selected DNS checks	merged	ws-0497-dns-catalog-selection.md
0374	Repair ADR 0374 status artifacts on latest origin/main	merged	ws-0374-status-repair.md
0369	Shared Python validation toolkit for catalog and registry scripts	merged	adr-0369-python-validation-toolkit.md
0368	DRY Centralization — ADRs 0368–0374	merged	0368-docker-compose-jinja2-macro-library.md
0364	Outline agent tools: list/search/get/create documents (ADR 0362 + 0364)	merged	0362-agent-service-api-gateway-pattern.md
0360	Restore the governed Plane API access path for workstream sync	merged	ws-0518-plane-api-access.md
0336	Verify ADR 0336 public entrypoint leakage validation on the latest origin/main	merged	ws-0336-live-apply.md
0309	Live apply task-oriented information architecture across the platform workbench from latest origin/main	live_applied	ws-0309-live-apply.md
0297	Resolve Gitea release bundle retention and Renovate PR validation checkout drift	live_applied	ws-0315-gitea-followups.md
0296	Allow Builder metrics scraping over the private tailnet	live_applied	ws-0513-builder-metrics-tailnet-firewall.md
0296	Deliver the cache-only GHCR proxy configuration through a one-shot reader bridge	merged	ws-0504-cache-ghcr-secret-renderer.md
0295	Live apply the shared artifact cache plane from latest origin/main	live_applied	ws-0295-live-apply.md
0293	Integrate ADR 0293 exact-main LiveKit replay onto main	merged	ws-0293-main-integration.md
0259	Integrate ADR 0259 exact-main replay onto current origin/main	merged	ws-0259-main-merge.md
0252	Integrate ADR 0252 exact-main replay onto current origin/main	merged	ws-0252-main-merge.md
0238	Integrate ADR 0238 operator grid into origin/main	merged	ws-0238-main-integration.md
0237	Live apply schema-first human forms via React Hook Form and Zod	live_applied	ws-0237-live-apply.md
0236	Live apply TanStack Query server-state conventions on the Windmill operator admin app	live_applied	ws-0236-live-apply.md
0232	Integrate ADR 0232 live apply into origin/main	merged	ws-0232-main-merge.md
0206	Integrate ADR 0206 live apply into origin/main	merged	ws-0206-main-merge.md

Requirements

For Docker development (Tier 1):

• Docker Desktop or Docker Engine
• 8 GB free RAM
• macOS (ARM or Intel), Linux, or WSL2

For production deployment:

• Dedicated x86_64 server with Debian 13
• 32 GB RAM, 500 GB disk
• Python 3.12+, Ansible, uv (Python package manager)

License

This project is licensed under the MIT License. See LICENSE.

Contributing

See CONTRIBUTING.md for development workflow, ADR governance, and merge procedures.

---

Generated 2026-10-01 by scripts/generate_readme.py from docs/templates/README.md.j2. Run make generate-readme to refresh.