Cloudfall

Your servers, run by an agent. With a record that answers why.

Website · Getting started · Migrate from Render · Roadmap · Manifesto

Cloudfall is the operator's record for self-hosted servers run by an AI agent. The agent decides; Ansible executes; Cloudfall says what the agent may do, checks every result, and keeps the evidence. Every operation has a verify step and every decision an audit entry: what the fleet looked like, what was proposed, who approved, what verify reported. Cloudfall never reports success it cannot prove. Open source, plain Debian, no Kubernetes.

flowchart LR
    A["AI agent<br/>(Claude Code, Codex, MCP)"] -->|proposes| G{"Cloudfall<br/>policy gate"}
    H["Human"] -.->|approves what<br/>can't be undone| G
    G -->|allowed| X["Ansible"]
    X --> S["Your Debian servers"]
    S -->|observed state| V["Verify"]
    V --> R[("Receipt:<br/>evidence, proposal,<br/>approval, outcome")]
    R -.->|earned autonomy| G

Who it is for

Teams with one to twenty servers and no platform hire: founders leaving a PaaS whose bill crossed $1,000 a month, and anyone whose servers are already run by Claude Code, Codex or another agent. Today Cloudfall moves your applications and databases onto one or two Hetzner-class servers you own (hardened baseline, monitoring, PostgreSQL and Redis with backups that provably restore, health-gated deploys with rollback, a real DNS cutover), and an always-on operator runs them there with a receipt for every action.

Proven live, not promised. Everything implemented has run on disposable Hetzner Cloud Debian 13 servers: an application actually hosted on Render was cut over with its data and a real TTL-lowered DNS flip, a bad release was rolled back automatically, an induced failure was remediated first with one human approval and then autonomously under declared policy, a timer-driven drill proved a real backup restorable, and an alert crossed the public network to a second machine. The entire migration was driven by an AI agent through the MCP server alone. Full reports: proving-runs

Why Cloudfall

• A record that answers "why did the agent do that". Every deploy, remediation and drill leaves a receipt; every operator decision records the evidence, the proposal, the approval and the outcome. An agent's own log says a tool was called. This says what the fleet looked like when it was
• Verified, not just ran. Status is derived from validated observations, cloudfall audit reports drift with distinct exit codes, and deploys are gated on health and rolled back when it fails
• Autonomy earned from the record. The operator remediates what its receipt history proves reversible under declared policy, and asks you only about what can't be undone
• AI-agent native. A stable CLI and Python API with structured JSON results, and cloudfall mcp serve for agents. Read-only evidence tools are free; a deploy, rollback, restart or migration returns its plan until called again with yes
• The bill buys computers, not margins. On servers you own, the margin on commodity compute and managed databases becomes runway
• Good-enough databases, with proof. Loopback PostgreSQL and Redis with receipted backups and restore drills that prove a backup restorable
• Boring on purpose. Native systemd services, artifact releases with symlink rollback, nginx, stock Debian. Any Linux admin can take over the server without Cloudfall installed

Quickstart

The only prerequisite is uv; it provisions Python 3.14 and every dependency.

uv tool install cloudfall
cloudfall --help

Start a project (a directory of its own, kept private), declare your SSH key and first server, then validate and audit:

uvx cloudfall init my-project
cd my-project
uv sync
uv run cloudfall add ssh-key ~/.ssh/id_ed25519.pub --owner you
uv run cloudfall add server h1 --address 203.0.113.10
uv run cloudfall config validate

cloudfall init also writes an AGENTS.md: the contract an agent started in the project reads first, with every command sorted by effect and the gate each server-changing command demands. The full walkthrough, from inspection and drift audit to the live dashboard, is in Getting started.

Migrate from Render

uv run cloudfall import render render.yaml --application acme --server h1
uv run cloudfall migrate --build acme-api=main          # show the plan
uv run cloudfall migrate --build acme-api=main --yes    # run it

The importer never guesses silently: IMPORT-REPORT.md records what was not imported, every assumption and every step required before cutover. The migration runs baseline, services, builds, health-gated deploys, routes, a DNS-verification pause, TLS and a final evidence pass, and resumes exactly where it stopped. Databases move with cloudfall data copy, which verifies per-table row counts and writes a receipt. See the Render migration guide and the Neon migration guide.

Documentation

Architecture

Three modules with strict boundaries:

• config/: declarative YAML resources and their JSON Schemas
• sdk/: the cloudfall CLI and Python API used by agents and tooling
• engine/: internal execution machinery (Ansible-based)

The config contains no execution logic, the CLI validates config without Ansible internals, the engine never silently rewrites the config, and mutating operations go through the engine's command-line and playbook contracts. See ARCHITECTURE.md.

Status

Cloudfall is pre-1.0 and honestly labeled. Implemented and proven live on disposable Debian targets:

• Typed YAML config with JSON Schemas, deterministic Ansible inventory, read-only inspection and config-versus-observed drift audit
• Hardened Debian baseline, nftables firewall, and a Loki/Grafana/Alloy logging stack with declared alert rules over mTLS
• Loopback PostgreSQL, Redis and Nginx/TLS sites with sops/age secrets, receipted backups and a timer-driven restore drill
• Health-gated deploys with symlink rollback and an evidence-derived dashboard
• Render importers, guided data migration and the resumable cloudfall migrate
• cloudfall mcp serve and the always-on operator with receipted proposals and policy-bounded autonomy

Not yet validated live: bare-metal RAID/storage provisioning. Next up: the fleet-density track (resource sharing, node drain, PostgreSQL point-in-time recovery). See the roadmap.

Direction: your Ansible, not ours

Most teams that would use Cloudfall already run Ansible. The next step reads their inventory as the only config and exposes each of their playbooks to the agent as a declared operation with a risk level, a verify step and an audit entry. Ansible is the hand, the agent is the brain, Cloudfall is the conscience. Designed, not yet built: docs/brownfield-design.md.

Community

• Questions and ideas: Discussions
• Bugs and feature requests: Issues
• Want help moving off a PaaS? Request a pilot
• Contributing: CONTRIBUTING.md · Conduct: CODE_OF_CONDUCT.md · Security: SECURITY.md · Changes: CHANGELOG.md

License

Everything in this repository is free under the GNU AGPL-3.0-or-later and sufficient on its own. The hosted always-on operator and commercial licensing are how the project sustains itself; neither holds back the open core. Commercial licensing exceptions are available from the copyright holder.