Cloudhal

The open-source, agent-native site platform. Agents build, edit and operate websites through a governed interface: every change is a snapshot, every snapshot has a diff and a preview, every publish is approved and reversible.

Blogs and newsrooms first; documentation sites and research or data documentation next. They share the same governed layer, because the more an audience relies on what an agent wrote, the more each change needs an owner, an approval and a way back.

Status: alpha (0.x). The loop works end to end on the blog starter — Intent → Agent → Safe Change → Preview → Approve → Publish → Rollback — offline and on Cloudflare. Cloudhal's own newsroom and cloudhal.com run on it. Packages are on npm as @cloudhal/* and create-cloudhal; expect breaking changes between minor versions until 1.0.

What it is

• Site Graph — a site is a graph of typed nodes (Site, Page, Section, ContentEntry) with per-node revisions. Contracts are JSON Schema, generated into TypeScript and Rust (packages/core-contracts, crates/cloudhal-schema).
• Safe change loop — Intent → Agent → Snapshot → Diff → Preview → Approve → Publish → Rollback.
• Policy-first — humans and agents are the same kind of actor; the policy engine checks every tool call against scopes, not the skill's good intentions.
• MCP-native — the agent surface is a Model Context Protocol server (spec 2026-07-28), usable from Claude, Cursor, Codex or any MCP client.
• Self-hostable, Cloudflare-ready — runs offline on SQLite + filesystem; deploys to Cloudflare Workers/D1/R2 with the same storage interface.
• Analytics without cookies — page views, sources, countries, devices and Core Web Vitals from one first-party script, in Studio, in each article's editor and for agents (read-only MCP tools). No personal data by default; see the privacy guide for site owners.
• Reader comments, moderated — first-party comments on articles: a plain form that works without JavaScript, a cookie-less proof of work instead of a CAPTCHA (Cloudflare Turnstile optional), every guest comment held for a person, agents that label and hide but never approve, erasure and DSA reports built in. Comments live in your database, outside snapshots. Off for each site until you turn them on; see the guide for site owners.
• Schedules — publish later as releases that pin the exact versions a person approved; embargoes and expiries the site enforces on every request, with no scheduler needed; one every-minute tick on Cloudflare (cron, or a Durable Object alarm when no cron slot is free) and on Node; built-in checks and scheduled agent tasks with their own keys, run windows, budgets and a taint rule. No language model runs inside Cloudhal; see the schedules guide.

Five minutes: create → ask an agent → preview → publish → your domain

npm create cloudhal@latest my-site && cd my-site && npm install
npx cloudhal dev                                          # local site with drafts visible
claude mcp add cloudhal -- npx cloudhal mcp --mode edits  # connect your agent (any MCP client works)

Step by step, with pnpm, Yarn and Bun: the quickstart. Codex, Cursor, VS Code and other clients: connect an agent.

Or put a blog on your Cloudflare account in one click, with nothing installed:

The button copies cloudhal-template into your GitHub account and runs cloudhal deploy in Workers Builds. You get the site Worker, the admin Worker (Studio, API, MCP), one D1 database, one R2 bucket and a starter blog; every push redeploys. See the deploy button guide.

Ask your agent: "Write a launch post about our new product, show me a preview, then publish it." It writes through Cloudhal's MCP tools (over 100, full list). Every change is snapshotted. It previews, and the publish waits for your approval.

npx cloudhal deploy                         # Cloudflare Workers + D1 + R2 with your wrangler login
npx cloudhal domain set news.example.com    # your own domain (zone in the same account)
npx cloudhal deploy

New projects count visits from the first deploy: cookie-less, first-party, read by Studio through Cloudflare bindings without an API token. Switch it off per site in Studio or for the deployment with "analytics": { "enabled": false } in cloudhal.json; existing deployments are asked once on their next deploy. Requirements (wrangler ≥ 4.145; the admin Worker's every-minute cron trigger, or the Durable Object alarm cloudhal deploy falls back to), Workers Free and Paid limits and the cloudhal analytics commands are in the CLI README; what is collected is in the privacy guide.

Reader comments are available on every deployment and off for every site until you turn them on in Studio. The first deploy in a terminal asks where the database should live; --jurisdiction eu keeps it in the EU (also in CI), and that choice cannot be changed later. Setup, moderation, agents, spam protection, privacy and a ready-made privacy paragraph are in the comments guide.

Scheduled publishing, embargoes and automations need nothing to set up: cloudhal deploy gives the admin Worker an every-minute cron trigger, or a Durable Object alarm when the account has no free cron slot (Workers Free allows 5), and cloudhal schedules status shows whether the scheduler is running. Releases, time gates, time zones, automations, recipes for scheduled agents and the Free-plan notes are in the schedules guide.

The first deploy prints a one-time link for the owner account. In Studio you create keys for remote agents and choose each key's mode. Approvals wait in Studio, and every agent call is in the activity log.

Mode	What the agent does on its own
Plan	read and preview only
Manual	nothing; every change waits for you
Edits	content edits; publish, rollback and delete wait (default)
Auto	also small article-only publishes

An agent can ask for a more autonomous mode for a while. You grant it in Studio, possibly shorter, and it ends by itself.

Contributors (today)

git clone https://github.com/cloudhal-dev/cloudhal && cd cloudhal
pnpm install
pnpm check                      # biome lint, size check, generated-file checks, typecheck, vitest (incl. an init→dev→build e2e)
cargo test --workspace          # Rust contract tests
node packages/cli/bin/cloudhal.ts init examples/my-site --name "My Site"
cd examples/my-site && pnpm install && node ../../packages/cli/bin/cloudhal.ts dev      # site preview
node ../../packages/cli/bin/cloudhal.ts studio                                           # Studio + API on :8787

No Cloudflare account is needed for anything in this repo. See CONTRIBUTING.md.

Repository layout

packages/core-contracts   JSON Schema source of truth, generated TypeScript + precompiled validators
packages/storage          SqlDriver/BlobStore interfaces; better-sqlite3, D1, fs, R2 adapters; migrations
packages/core-ts          Site Graph store: CAS, snapshots, diff, publish, rollback
packages/astro-renderer   Astro 7 integration, live/snapshot data sources, section components
packages/analytics        cookie-less site analytics: beacon handler, WAE and SQLite stores, rollups
packages/comments         reader comments (RFC-0007): rules, proof of work, submission pipeline, SQLite/D1 store
packages/schedules        schedules (RFC-0008): time model, RRULE subset, releases, automations, taint, budgets, runDue, SQLite/D1 store
packages/cli              the cloudhal CLI: init, dev, studio, mcp, deploy, push, pull, export, import, … (all commands: cloudhal --help, https://cloudhal.dev/docs/reference/cli)
packages/api              Hono HTTP API + Better Auth + /mcp endpoint + agent API keys (Node and Workers)
packages/agent-runtime    policy engine, skill loader, audit log (SDK-free)
packages/mcp-server       MCP server: over 100 tools (README tool reference), approval gate, agent modes, skills as resources; stdio + HTTP
packages/cloudflare       admin Worker (Studio + API + auth + MCP on D1/R2); site Worker entry lives in astro-renderer
packages/ui               Kumo re-export + Cloudhal blocks
apps/studio               Studio admin UI (Vite + React SPA, 19 languages)
starters/blog             the first starter: routes, layout, theme map
skills/official           Agent Skills shipped with Cloudhal (site-bootstrap, safe-edit, publish-article, …; one folder each)
crates/cloudhal-schema    generated Rust types + fixture tests
docs/adr                  architecture decision records
docs/design               DESIGN.md — the binding admin design system (Kumo)
docs/guides               guides for site owners and operators (analytics, comments, schedules, search, deploy, …)
docs/rfcs                 design proposals (RFC-0001: Site Graph)
docs/security             threat model
.agents/skills            skills for coding agents working on this repo
apps/demo-newsroom        Cloudhal's own newsroom, published by an agent through Cloudhal (dogfooding)
packages/create-cloudhal  npm create cloudhal

Every CLI command is in the CLI reference (cloudhal --help), the official skills in skills/official and the guides in docs/guides.

Planned: packages/sdk-js, capabilities/.

Open-core boundary

Open (Apache-2.0, this repo): core, graph, policy, CLI, Studio, Astro renderer, Cloudflare adapter, SDK, starters, official skills and capabilities. Closed (Cloudhal Cloud): billing, multi-tenant control plane, managed registry service.

This boundary is a commitment, not a plan: code that is open stays open.

License

Apache-2.0. "Cloudhal" is a trademark; see TRADEMARK.md.