⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

version unknown

cloudflare-os-operator

cloudflare@cloudflare⭐ 351 stars· last commit 26d ago· 0 open issues

Guides cloudflare/cloudflare-os-starter setup, Cloudflare Access, deployment.jsonc, storage, AI, observability, custom Gatekeepers, deployment, verification, troubleshooting, rollback, and pinned-submodule upgrades. Use only for deployments created from the Cloudflare OS Deployment Starter, not standalone Cloudflare OS checkouts.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐⭐ 351 on GitHubGitHub ↗

Popular

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

[!IMPORTANT] Cloudflare OS is early-access software. Pin upstream releases, review changes, and verify the trust boundary before every production upgrade.

Quick start

With Node.js 24.19 or newer and pnpm 11.17 installed:

npx cf-os init my-os

It clones this starter, installs it, offers to create a private GitHub repository and push there, then configures sign-in, Workers and AI Gateway, writes deployment.jsonc, and offers to deploy. Deploy covers each step and the manual route, and Customization what to change afterwards. Everything else on this page is optional reading.

Overview

This repository adds deployment controls around a pinned Cloudflare OS release without modifying the upstream source.

ControlWhat you own
BrandingSite name, logo, and accent color, changed in /admin without a deploy
IdentityThe sign-in method and administrator allowlist; this starter deploys Cloudflare Access mode
RoutingA production Custom Domain or a workers.dev evaluation route
DataExisting KV/R2 resources or automatic provisioning
IntegrationsWrapper-owned Gatekeepers and service bindings without patching upstream
AIA Workers AI model catalog through AI Gateway out of the box, with no API token; which providers and which gateway
OperationsStructured logs, traces, explicit error reports, validation, deployment order, and upgrades

Architecture

The deployment is up to seven Workers, plus any optional Gatekeepers you choose. A router owns the public route and serves the frontend, proxying /api to the Workshop backend and /gatekeeper/<name> to whichever Gatekeeper the binding name matches; the Workshop, the Context, Scheduler, Web Search and custom Gatekeepers, and the Error Reporter sit behind it with no route of their own, reachable only over service bindings.

The deploy command derives temporary Wrangler files from upstream base configs, builds the frontend in Cloudflare Access mode, deploys the private Error Reporter, the Gatekeepers and the Workshop before the router that binds them, and removes generated files even on failure. Secrets never enter tracked configuration.

If you only want branding

A hosted flow deploys the same upstream release to your Cloudflare account without this repository. It builds nothing locally, configures sign-in and your admin emails for you, and leaves the whole /admin surface intact: site name, logo, accent color, announcements, agent instructions, featured blueprints, and which connectors your users can reach. Built-in Gatekeepers such as GitHub and Google are still yours to connect with your own OAuth credentials.

Anything past that needs your own code or settings, which is what this repository is for: custom Gatekeepers, customized error reporting, your own Worker names, reusing storage you already have, choosing how much logging to keep, and a pinned version you upgrade when you decide. Hosted deployments also run on a workers.dev address, so deploy from here if you want the app on your own domain. Come back when branding stops being enough.

Deploy

1. Prepare the workspace

Install Node.js 24.19 or newer (the cf-os CLI is TypeScript run directly by node) and pnpm 11.17, then create the project:

npx cf-os init my-os

It clones this starter and its submodule, installs, offers to create a private GitHub repository for it, and starts pnpm cf-os init (step 2). To clone by hand instead, run git clone --recurse-submodules https://github.com/cloudflare/cloudflare-os-starter my-os, then pnpm install and pnpm cf-os init inside my-os. A fork of this public repository has to stay public; for a private one, push the clone to an empty private repository instead. Either way, deployment.jsonc belongs in your repository, and npx cf-os@latest update brings in starter updates.

pnpm install installs the submodule's own workspace too, from a postinstall hook. If you install with --ignore-scripts, run pnpm cf-os install afterwards; pnpm cf-os check says so if you forget.

pnpm cf-os init offers the Wrangler sign-in, which deploys, and the cf CLI's, which reads defaults from your account and sets up Access. packages/cf-os lists every command and flag.

Your account needs Workers, KV, R2, Browser Rendering, and Dynamic Worker Loaders. It also needs Workers AI and AI Gateway, which the default model catalog runs on. Web Search needs them too, through the account's default gateway when the catalog is off, so they are dispensable only with the catalog off and Web Search disabled in /admin. Artifacts is optional.

2. Configure sign-in

Cloudflare OS supports several sign-in methods. This starter deploys Cloudflare Access mode, which verifies identity before a request reaches the Worker. See Sign-in methods for the al

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • .agents/skills/cloudflare-os-operator/SKILL.md7.8 KBupstream ↗
    ---
    name: cloudflare-os-operator
    description: Guides cloudflare/cloudflare-os-starter setup, Cloudflare Access, deployment.jsonc, storage, AI, observability, custom Gatekeepers, deployment, verification, troubleshooting, rollback, and pinned-submodule upgrades. Use only for deployments created from the Cloudflare OS Deployment Starter, not standalone Cloudflare OS checkouts.
    compatibility: Requires Git, the checkout-declared Node.js and pnpm versions, project-pinned Wrangler, and a Cloudflare account with the products used by the deployment.
    ---
    
    # Cloudflare OS Operator
    
    Own the outcome, not just the next command. Guide the operator from an unprepared checkout to a verified deployment, or from a failure to a diagnosed and safe recovery. A provider outage, unavailable product, or incorrect external policy can never be ruled out in advance, so do not promise an issue-free deployment. Prevent avoidable failures and do not call the work complete without evidence.
    
    This skill operates the deployment wrapper, not Cloudflare OS in isolation. The wrapper pins Cloudflare OS as a submodule, derives temporary Wrangler configs, and coordinates several Workers.
    
    ## Locate The Starter
    
    Find the repository root containing all of these markers:
    
    - `deployment.jsonc`
    - `scripts/deploy.ts`
    - `cloudflare-os/`
    - `packages/custom-gatekeeper/`
    
    Do not assume the current working directory or this skill's directory is the starter root. If the markers are absent, stop and ask for the starter checkout. Do not apply this workflow directly to a standalone Cloudflare OS checkout.
    
    Once the submodule is initialized, confirm `cloudflare-os/packages/router/` exists as well. The deploy binds and deploys it, so a pinned commit without it cannot be deployed by this wrapper; treat its absence as a provenance problem, not a missing build step.
    
    ## Read Current Sources First
    
    Before any mutation, always read the current checkout's:
    
    1. `README.md`
    2. `deployment.jsonc`
    3. `scripts/deploy.ts`
    4. `package.json`
    5. `.gitmodules`
    6. Available relevant upstream files under `cloudflare-os/`
    
    Load `docs/customization.md`, `docs/observability.md`, package guides, and reference files from this skill only when their subject is relevant. If the submodule is unavailable, inspect all available wrapper sources and defer upstream-dependent advice until provenance is resolved.
    
    Inspect the deploy script rather than assuming its validation, generated paths, build steps, or deployment order. Consult current Cloudflare documentation before relying on product behavior, permissions, CLI syntax, limits, or rollback support. Repository code is authoritative for what this checkout does; current Cloudflare documentation is authoritative for the platform it calls. Surface conflicts instead of silently choosing one.
    
    Expected baseline commands are:
    
    ```sh
    git submodule update --init
    pnpm install
    pnpm --dir cloudflare-os install
    pnpm exec wrangler login
    pnpm check
    pnpm deploy
    ```
    
    Confirm them against the checkout before running them. Always use `pnpm`, never `npm` or `yarn`.
    
    ## Operating Rules
    
    - Start read-only. Inventory before mutation.
    - Ask for all missing operator decisions in one concise batch.
    - Explain why each requested value is needed and where to find it.
    - Never guess an account ID, resource ID, hostname, Access issuer, audience, administrator, Worker name, provider, or existing-resource ownership.
    - Never expose a token, cookie, JWT, secret, prompt, request body, response body, or private log content in chat, tracked files, command arguments, or reports. For local development only, use Wrangler's supported local-secret mechanism after proving the file is ignored and the credential is non-production.
    - Use the project-pinned Wrangler through `pnpm exec wrangler`.
    - Run only one `pnpm check` or `pnpm deploy` per checkout at a time. Use separate worktrees for concurrency.
    - Change one root cause at a time. Re-run the narrow check, then the complete check.
    - Do not broaden permissions, disable security controls, recreate resources, or retry deployments blindly to make an error disappear.
    - Keep a sanitized operation record: root commit, submodule commit, target account, intended route, Worker names, resource identities, deployment/version IDs, decisions, verification, and rollback limits.
    
    ## Classify The Operation
    
    Choose one mode before acting:
    
    - **Research:** read-only explanation or design.
    - **Evaluation:** a non-production deployment, usually on an explicitly protected `workers.dev` hostname.
    - **Production:** a custom domain and production data or users.
    - **Incident:** restore safety and service while preserving evidence.
    - **Upgrade:** move the pinned `cloudflare-os` gitlink to a reviewed commit.
    
    Also classify the deployment as a first deploy, continuation of an existing deployment, or replacement. If this is unclear, remain read-only.
    
    ## Hard Stops
    
    ### Secrets
    
    Never ask the operator to paste a secret. Never read or print a secret to confirm it. Never put production secrets in `deployment.jsonc`, Wrangler vars, repository-local environment files, tracked files, shell history, or chat.
    
    When AI is enabled, a human enters `CF_AI_GATEWAY_API_TOKEN` interactively for the exact Workshop Worker:
    
    ```sh
    CLOUDFLARE_ACCOUNT_ID=<account-id> pnpm exec wrangler secret put CF_AI_GATEWAY_API_TOKEN --name <workshop-worker>
    ```
    
    Confirm this account selector against current Wrangler documentation. Confirm the account, existing Worker ownership, and Worker name immediately before presenting or running the interactive command. `secret put` immediately deploys a new Worker version; require production approval, record its version ID, and verify it like any other deployment. Verify only that the secret name exists, never its value. If exposure is suspected, stop deployment and rotate or revoke the credential first.
    
    ### Trust Boundary
    
    Require explicit operator approval before changing any of these:
    
    - Cloudflare account, Worker identity, route, DNS, or Access application.
    - Access issuer, audience, sign-in method, policy, administrator list, or allowed population.
    - Existing KV/R2 bindings, `publicBaseUrl`, `context.sharingDomain`, data ownership, or service bindings. The public origin is a data boundary as well as an address: `context.sharingDomain: null` derives from it, so moving the hostname moves the Context isolation boundary with it.
    - AI provider, billing, token scope, model logging, retention, or external observability export.
    - Gatekeeper authority, OAuth scopes, writes, observer policy, auto-provisioning, or ambience.
    - Reporter visibility, browser reporting, retention, or destination.
    - Durable Object migrations or storage schema.
    
    Show the authority before and after, affected users/data, cost and privacy implications, verification plan, and rollback limitations.
    
    ### Production Mutation
    
    Do not run `pnpm deploy`, install or delete secrets, modify Access/DNS, adopt resources, or roll back production until the operator approves a mutation summary containing:
    
    - Exact account ID and hostname.
    - Root and submodule commits.
    - Every Worker to create or update.
    - Every resource to provision or adopt.
    - Access application and administrator policy.
    - AI, observability, Reporter, and Gatekeeper modes.
    - Last-known-good deployment IDs and rollback limitations.
    - Evidence that `pnpm check` passed.
    
    Never delete Workers, routes, Access applications, KV namespaces, R2 buckets, secrets, or user data as automatic cleanup or troubleshooting.
    
    ## End-To-End Workflow
    
    ### 1. Establish Provenance And State
    
    Record, without leaking credentials:
    
    ```text
    operation mode and first/continuation/replacement:
    root commit and branch:
    root worktree changes:
    configured submodule URL:
    expected submodule gitlink:
    checked-out submodule commit and status:
    Node, pnpm, and Wrangler versions:
    Wrangler authentication source and target account:
    route, hostname, and resolved public origin:
    Worker names and whether each is new, owned
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/cloudflare-cloudflare-os-starter-agents-skills-cloudflare-os-operator.md

// REPO STATS

351 stars
0 open issues
Last commit: 26d ago