Gadget 00：クイックスタート

Cloudflare OS を macOS または QNAP NAS で「今日中に」起動するための最短手順

クイックスタート

Cloudflare OS を自分のデバイスで初めて起動するための最短ルートです。 「開発して試す」なら macOS、「常時稼働させたい」なら QNAP NAS を選んでください。

目的

  • 最短手順で Cloudflare OS を起動し、ブラウザで UI を表示する
  • どちらの環境を選ぶべきか迷わないための判断材料を提供する

前提条件

技術/項目 macOS (TypeA) QNAP (TypeB)
Node.js 20.19+ / 22.12+（22 LTS 推奨） コンテナ内に導入
pnpm 11.x（corepack で揃える） コンテナ内に導入
Docker 不要 Container Station
Cloudflare アカウント 不要（run-local の場合） 外部公開時のみ
CPU x86_64 x86_64 前提（ARM は未検証）
WarningCloudflare アカウントは不要（ただし例外あり）

pnpm run-local は通常 Cloudflare アカウント不要で動きます。 ただし --use-workers-ai-binding を使う場合のみ wrangler login が必要です （詳細は Gadget 01）。

手順

TypeA：macOS で起動する（最短 ver）

# 1) 前提ツールを確認
node --version   # 20.19+ / 22.12+
pnpm --version   # 11.x が望ましい

# 2) corepack で pnpm のバージョンをリポジトリ指定に合わせる
corepack enable
corepack prepare pnpm@11.17.0 --activate

# 3) 本体を取得してインストール
git clone https://github.com/cloudflare/cloudflare-os.git
cd cloudflare-os
pnpm install

# 4) 起動
pnpm run-local

最後に Starting: wrangler dev [...] が出れば成功。 ブラウザで http://localhost:8787 を開くと UI が表示されます。

TypeB：QNAP NAS で常時起動する（ショートカット）

QNAP の Container Station で Node 22 コンテナを作り、中で常駐させるのが最短です。

# コンテナ内
apt-get update && apt-get install -y git
corepack enable
git clone https://github.com/cloudflare/cloudflare-os.git
cd cloudflare-os && pnpm install --frozen-lockfile
pnpm run-local &
  • コンテナのポート 8787 を LAN に公開 → http://<NAS-IP>:8787
  • Container Station の「再起動時に自動開始」を ON にすれば再起動後も復帰
TipTypeB は詳しい前提がある

QNAP の場合はストレージ設計や永続化（.wrangler/ の退避）も重要です。 先に Gadget 02 を読んでください。

よくある失敗

症状 原因 対処
pnpm install が失敗 Node が古い（Vite7 は 20.19+/22.12+ 必要） nvm use 22 等で 22 LTS に
ポート使用中 EADDRINUSE 8787 を他プロセスが使用 lsof -i :8787 で特定し kill
ブラウザが真っ白 初回ビルドが未完了 / dist が無い cd packages/workshop-frontend && pnpm run build 後に再起動
ARM（arm64）の NAS で失敗 ネイティブバイナリ非サポート x86_64 機を前提に（本サイトの前提）

確認

次に読む