---
title: "Installation"
description: "Create a Cloudhal project with your package manager. The project is an Astro site with a local Cloudhal store; it runs offline and deploys to Cloudflare when you are ready."
url: https://cloudhal.dev/docs/start/installation
source: https://github.com/cloudhal-dev/cloudhal/blob/main/docs/start/installation.md
---
# Installation

Create a Cloudhal project with your package manager. The project is an Astro site with a local Cloudhal store; it runs offline and deploys to Cloudflare when you are ready.

## Requirements

- **Node.js 24 or later.** Cloudhal's CLI runs TypeScript with Node's built-in type stripping, so older versions refuse to start. Check with `node --version`.
- **A package manager:** npm (comes with Node), pnpm, Yarn or Bun.
- Optional:
  - **Google Chrome or Chromium**, for `cloudhal render` and the agent's `render_page` checks (screenshots and accessibility checks of a page). Without it, those tools say they are unavailable and everything else works.
  - **A Cloudflare account and `wrangler login`**, only to deploy. Wrangler is installed with the project.

## Create a project

Pick your package manager. Each command creates `my-site/` with the blog starter and a seeded local site.

```sh
# npm
npm create cloudhal@latest my-site

# pnpm
pnpm create cloudhal@latest my-site

# Yarn
yarn create cloudhal my-site

# Bun
bun create cloudhal my-site
```

Name the site at the same time with `--name`. npm needs `--` before the scaffolder's own flags:

```sh
npm create cloudhal@latest my-site -- --name "Field Notes"
pnpm create cloudhal@latest my-site --name "Field Notes"
```

Then install the project's dependencies:

```sh
cd my-site
npm install        # or: pnpm install · yarn · bun install
```

The scaffolder prints these steps with the package manager it was run with.

## What you get

| Path | What it is |
|---|---|
| `cloudhal.json` | The project's Cloudhal settings: site id, deployment name, analytics, comments, schedules |
| `src/` | The Astro theme: routes, layouts and `theme.ts`. Edit it like any Astro project |
| `.cloudhal/` | The local store (SQLite and media). Not committed; `cloudhal push` and `pull` move content between it and a deployment |
| `package.json` | Scripts: `dev`, `studio`, `mcp`, `deploy`, `build`, `snapshot` |

The site's content (pages, articles, menus, settings) lives in the store, not in files. Agents and Studio change it; every change is a snapshot you can diff and roll back.

## Running the CLI

The `cloudhal` CLI is a dependency of the project (`@cloudhal/cli`), so you never install it globally. Inside the project, any of these runs it:

| Package manager | Run a command | Run a script |
|---|---|---|
| npm | `npx cloudhal dev` | `npm run dev` |
| pnpm | `pnpm exec cloudhal dev` | `pnpm dev` |
| Yarn | `yarn cloudhal dev` | `yarn dev` |
| Bun | `bunx cloudhal dev` | `bun run dev` |

Outside a project, `npx @cloudhal/cli@latest --help` (or `pnpm dlx @cloudhal/cli@latest --help`) runs the latest CLI without installing it. Most commands need a project, so `cd` into one first.

## pnpm notes

pnpm blocks dependency build scripts and releases younger than a day by default. A new project's `pnpm-workspace.yaml` already allows what Cloudhal needs (projects created before 0.3.4 lack the `minimumReleaseAgeExclude` lines; add them). In an existing pnpm workspace, add:

```yaml
allowBuilds:
  esbuild: true
  better-sqlite3: true
  workerd: true
minimumReleaseAgeExclude:
  - '@cloudhal/*'
  - 'create-cloudhal'
```

`better-sqlite3` is the local store's database driver and needs its build script; `workerd` runs Cloudflare's runtime locally.

## Upgrading

All `@cloudhal/*` packages share one version. Upgrade them together:

```sh
npm install @cloudhal/cli@latest @cloudhal/core-ts@latest @cloudhal/astro-renderer@latest @cloudhal/cloudflare@latest
```

Then run `npx cloudhal deploy` to update a deployment. Release notes are in each package's changelog on npm and GitHub.

## Next

- [Quickstart](https://cloudhal.dev/docs/start/quickstart): run the site, open Studio, connect an agent, publish.
- [Connect an agent](https://cloudhal.dev/docs/agents): Claude Code, Codex, Cursor, VS Code and other MCP clients.
- [Deploy to Cloudflare with one click](https://cloudhal.dev/docs/guides/deploy-button), with nothing installed.


---
title: "Quickstart"
description: "From an empty folder to a published site with an agent, in about ten minutes. You need Node.js 24 or later; see Installation for pnpm, Yarn and Bun."
url: https://cloudhal.dev/docs/start/quickstart
source: https://github.com/cloudhal-dev/cloudhal/blob/main/docs/start/quickstart.md
---
# Quickstart

From an empty folder to a published site with an agent, in about ten minutes. You need Node.js 24 or later; see [Installation](https://cloudhal.dev/docs/start/installation) for pnpm, Yarn and Bun.

## 1. Create the project

```sh
npm create cloudhal@latest my-site
cd my-site
npm install
```

You get the blog starter with a seeded local site: a home page, an about page, a few articles and a menu.

## 2. Preview the site

```sh
npm run dev
```

Open <http://localhost:4321>. This is the live preview: drafts are visible, and it updates as content changes. Everything runs offline on the project's local store in `.cloudhal/`.

## 3. Open Studio

In a second terminal:

```sh
npm run studio
```

Open <http://localhost:8787>. The first account you create becomes the Owner, and sign-up then closes. Studio is where people edit content, review what agents changed, approve publishes and roll back.

## 4. Connect an agent

Cloudhal's MCP server gives agents semantic tools (`create_entry`, `update_page`, `preview_page`, `publish`, …) behind a policy engine. With Claude Code, from the project folder:

```sh
claude mcp add cloudhal -- npx cloudhal mcp --mode edits
```

With Codex:

```sh
codex mcp add cloudhal -- npx cloudhal mcp --mode edits
```

Cursor, VS Code, Claude Desktop, Windsurf, Zed and Gemini CLI are in [Connect an agent](https://cloudhal.dev/docs/agents/clients). Start the client in the project folder: `cloudhal mcp` serves the project it runs in.

`--mode edits` lets the agent change content on its own while publishing, rollback and deletes wait for you. The other [modes](https://cloudhal.dev/docs/agents#modes) range from read-only (`plan`) to `auto`.

## 5. Ask for something

Try:

> Write a launch post about our new product, show me a preview, then publish it.

The agent creates a draft, calls `preview_page` and gives you a preview link. Every change it makes is a snapshot. When it calls `publish`, your client asks you to approve it, with a summary of what changes. Nothing goes live until you accept.

Watch it happen in Studio: **Activity** shows every call, **Snapshots** shows the history, and any snapshot can be diffed or rolled back.

## 6. Deploy to Cloudflare

```sh
npx wrangler login
npm run deploy
```

`cloudhal deploy` creates two Workers (the site, and the admin Worker with Studio, the API and the remote MCP endpoint), a D1 database and an R2 bucket, pushes your local site, and prints a one-time link to create the deployment's Owner account. To use your own domain:

```sh
npx cloudhal domain set news.example.com
npm run deploy
```

The zone must be in the same Cloudflare account. No Node project? [Deploy with one click](https://cloudhal.dev/docs/guides/deploy-button) from the template instead.

## 7. Connect agents to the deployment

On a deployment, agents use the remote MCP endpoint at `https://<studio-host>/mcp` with a key you create in Studio under **Agents**. Each key has a mode and scopes. See [remote agents](https://cloudhal.dev/docs/agents#remote-agents-on-a-deployment).

## Next

- [How agents work with Cloudhal](https://cloudhal.dev/docs/agents): modes, approvals, skills and the tool list.
- [CLI reference](https://cloudhal.dev/docs/reference/cli).
- Guides: [search](https://cloudhal.dev/docs/guides/search), [schedules](https://cloudhal.dev/docs/guides/schedules), [comments](https://cloudhal.dev/docs/guides/comments), [several sites](https://cloudhal.dev/docs/guides/multi-site).