Skip to main content
Glama

cloudfact

Publish a folder, a single HTML file, or an app that is already listening on a port (locally or on a machine reachable over SSH) to a public Cloudflare URL with one command. Ships as a CLI, an MCP server (works with Claude Code, Codex, Cursor, Claude Desktop, Windsurf…) and a /cloudfact skill.

cloudfact deploy ./report.html                       # → https://xxxx.trycloudflare.com/#key=…   (private link, no account needed)
cloudfact login --device && cloudfact deploy ./site  # → https://site.<your-sub>.workers.dev/#key=… (fixed URL, your account)
cloudfact deploy ./site --public                     # open to anyone with the URL
cloudfact expose 3000 --ssh ubuntu@my-vm             # app on another machine, over SSH (private link)

Install

Claude Code — two commands, no clone, no npm install (skill /cloudfact + MCP server):

claude plugin marketplace add gabrielchaves6/cloudfact
claude plugin install cloudfact@cloudfact

Everything at once (CLI on PATH, Claude Code plugin, Codex skill + MCP). Requires Node 20+ and git:

curl -fsSL https://raw.githubusercontent.com/gabrielchaves6/cloudfact/main/install.sh | bash

Codex — register the server and the skill from cloudfact itself (works on Windows too, unlike the shell installer):

cloudfact setup --codex     # or: npx/node <path>/dist/bin.js setup --codex

It writes [mcp_servers.cloudfact] into Codex's config (through codex mcp add when the CLI is around, by editing config.toml otherwise, leaving your other servers alone) and copies the skill into $CODEX_HOME/skills/cloudfact, minus the frontmatter keys Codex refuses. Restart Codex afterwards. Run it again after an update: it replaces its own entry instead of piling up copies.

Any other MCP client (Cursor, Windsurf, Claude Desktop…): clone and point at the bundled, dependency-free server:

{ "mcpServers": { "cloudfact": { "command": "node", "args": ["/path/to/cloudfact/dist/server.js"] } } }

It works without any login through the quick tunnel. cloudflared is downloaded automatically on the first deploy (Linux/macOS, x64/arm64) into ~/.cloudfact/bin; if you already have it on PATH, yours is used.

Related MCP server: EdgeOne Pages MCP

Apps with a server (expose)

Anything that already listens on a port can be published the same way, with HTTP and WebSocket proxied and the same optional --private gate:

cloudfact expose 3000                          # app running on this machine (private link by default)
cloudfact expose 3000 --ssh ubuntu@10.0.0.5    # app running on another machine, reached over SSH
cloudfact expose 8080 --ssh myvm --public      # `myvm` = Host alias from ~/.ssh/config; no key gate

Apps are private by default (key-gated link, see below), like every other deploy; pass --public to opt out. With --ssh, cloudfact opens an ssh -N -L port-forward to the remote app and publishes through the local tunnel. Nothing is installed on the remote machine; it only needs key-based SSH access (--ssh-port, --identity, --strict-host-key available). The forward and the tunnel are supervised and reconnect if they drop. MCP tool: expose.

Sign in to your Cloudflare account (optional, for a fixed URL)

Two options. The first works even when you only reach the machine through an agent (Claude Code, Codex…): the agent runs the command, relays the link and the code, and you approve in a browser on any device.

cloudfact login --device        # browser OAuth (wrangler login --device); no token ever goes through the chat
cloudfact login --token <tok>   # or an API token: https://dash.cloudflare.com/profile/api-tokens ("Edit Cloudflare Workers" template)

Tokens are stored in ~/.cloudfact/config.json (0600); OAuth credentials live where wrangler keeps them (~/.config/.wrangler). CLOUDFLARE_API_TOKEN / CLOUDFLARE_ACCOUNT_ID also work. cloudfact logout forgets.

After signing in the default backend becomes workers; --backend tunnel remains available.

Backends

backend

account?

URL

how

tunnel (default, signed out)

no

https://<random>.trycloudflare.com

local static server + cloudflared quick tunnel in a detached process that outlives the agent session and reconnects if the tunnel drops

workers (default, signed in)

yes

https://<name>.<sub>.workers.dev

Cloudflare Workers with static assets, the successor of Pages (Cloudflare no longer creates new Pages projects). wrangler deploy --assets, fetched via npx on first use. Uploads a copy without dotfiles/symlinks/node_modules. remove deletes the worker

Every deploy is private unless you pass --public: cloudfact generates a 256-bit key; the returned URL carries it in #key=…, which browsers never send to servers. Without the cookie every route returns only a gate page, which exchanges the fragment for an HttpOnly, Secure cookie via POST /api/session. That endpoint is rate-limited per visitor IP (10 attempts/minute) and failures are logged to the deploy's host.log.

cloudfact deploy ./report --private --expires 24h   # link stops working after 24h
cloudfact rotate report                             # new key now; old link and all sessions die
cloudfact rotate report --expires 2h                # new key with a lifetime

rotate works on a live deploy without restarting it (on the tunnel backend it also turns a public deploy private). On the workers backend the gate is a tiny generated Worker running in front of the files (run_worker_first), the key is a Worker secret, and rate limiting uses Cloudflare's rate-limit binding.

Identity sign-in with Cloudflare Access (no domain needed)

A private link is still a bearer link. For real identity, put Cloudflare Access in front of a workers deploy: visitors get a Cloudflare sign-in page, enter a one-time code sent to their email, and only the emails you list get in. Works on *.workers.dev, so you do not need to own a domain.

cloudfact login --token <api-token>                        # once; the browser login has no Access scopes
cloudfact deploy ./site --access you@example.com,ana@x.com  # → https://site.<sub>.workers.dev, sign-in required

The API token needs the "Edit Cloudflare Workers" template plus Access: Apps and Policies — Edit and Access: Organizations, Identity Providers, and Groups — Edit. cloudfact creates the Zero Trust team (<team>.cloudflareaccess.com) and the one-time PIN provider on first use, then one self-hosted Access application per deploy, updated in place on redeploy and deleted by remove. Its own sign-in page. Visitors never see Cloudflare's screens: the generated Worker serves one page in the CloudFacts look (in Portuguese for a Portuguese browser): the email, with a Remember me box ticked by default, then the 6-digit code from the email. The request stays in the browser for the code's lifetime, so a phone that reloads the page on the way to the inbox and back keeps its place.

  • Codes by email (recommended). Pipe a Resend API key in once: <command that prints the key> | cloudfact mail-key (every deploy behind Access, or the names given). Each Worker keeps it as its RESEND_API_KEY secret, through redeploys; it is not stored on this machine. The page then mails the code itself, from CloudFact <onboarding@resend.dev>, and checks it in its own Durable Object (LOGIN, SQLite-backed, on the Workers Free plan). Cloudflare Access is not involved. The rules: a code lasts 1 hour and takes 5 tries, and a used code is gone; an address may ask 5 times per 15 minutes and 30 times a day, everyone together 60 times per 15 minutes; only the --access emails get a code, and any other address gets the same answer and an unguessable code, so the page never tells which address has access. Resend's onboarding@resend.dev only delivers to the Resend account's owner; to let other people in, verify a domain in Resend and set the CLOUDFACT_MAIL_FROM var.

  • Codes from Cloudflare Access (until a key is set). Access mails and checks the code: the Worker fills in Access's one-time PIN forms behind the page (/cdn-cgi/access/verify-code, then /cdn-cgi/access/callback) and verifies the Access JWT a right code yields (RS256 against the team's public keys, audience pinned to this app, email on the --access list). Those forms are not a documented API, so anything unexpected offers the official way in: /.cloudfact/login, the one path Access guards, Cloudflare's own page.

Either way, a right code becomes an HttpOnly cookie signed with a per-deploy key:

  • remembered: kept for 400 days (the most a browser keeps a cookie) and pushed forward once a day while in use, so that browser stays signed in;

  • not remembered: gone when the browser closes, and after a day at most.

The cookie stops working when its email leaves the --access list (redeploy), and /.cloudfact/logout signs out. A redeploy keeps the key, so nobody is signed out by one. Anything without a valid cookie gets the sign-in page (page loads) or a 401 and never reaches the site, so a misconfigured policy fails closed instead of open. expose --access (an app on this machine behind a fixed *.workers.dev URL) uses the same sign-in.

Verified end-to-end on a real Cloudflare account (2026-09-15): the team, the one-time PIN provider and the application were created through the API alone, no Zero Trust checkout or payment method was required, the *.workers.dev URL redirects to the <team>.cloudflareaccess.com sign-in page, and after the email code the site is served.

Plan limit: cloudfact uses the Zero Trust Free plan, which allows 50 seats per Cloudflare account. A seat is one person who signs in, counted across every --access deploy in the account, so keep the sum of distinct emails you allow under 50 (Cloudflare blocks the 51st user until you upgrade). Seats of people who stop signing in can be released automatically from Zero Trust → Settings → "Remove inactive users from seats".

Local server safety: serves only what is inside the published folder, never dotfiles, no path traversal. A single .html is served alone (relative assets are not included; publish the folder in that case).

Catalog: every cloudfact in your account, by project

The Cloudflare account is the source of truth. cloudfact tags each Worker it creates (cloudfact, plus the project, the visibility and the kind), so one listing rebuilds the whole picture from any machine, even after a reinstall.

cloudfact deploy ./painel --project migracao        # file it under a project
cloudfact catalog                                   # everything in the account, grouped by project
cloudfact catalog --project migracao --json         # one project, machine readable
cloudfact project painel financeiro                 # move it, no redeploy
cloudfact catalog --publish                         # publish the page; later deploys refresh it

Each entry says what the deploy is and who can open it: Public, Private link (key-gated), Sign-in (Cloudflare Access) or App login (the app behind it asks for its own username and password, which cloudfact cannot supply: record it with cloudfact creds and the card keeps it), and Static (files served by Cloudflare) or Server app (an app with its own server behind the proxy). Quick tunnels have no account-side resource, so they are found on the machine itself: cloudfact asks the running cloudflared processes for their public hostname, which also surfaces pages still serving from here that this machine has no record of (flagged no local record: published by an older cloudfact, from another folder, or by another tool), next to the ones it does know (local tunnel). --publish deploys the catalog as a page with a card per deploy, search, a list view and a filter per project. Each card shows a real thumbnail, captured when the catalog is published from whatever this machine can already read: the published folder, the app's own port, or the URL with its private key. Thumbnails render with scripts off in a sandboxed frame, and a deploy this machine cannot see falls back to a monogram. The page never points a frame at a live site: doing so lets that site challenge the visitor for credentials.

Because the page is behind sign-in, it can also be the one place that opens everything: each card links to the deploy with its private key already in the link, so a page you are allowed to see opens in one click. cloudfact creds <name> --user u --password p --note n records the login of the app itself (a terminal, a dashboard) next to the deploy; it stays on this machine and is shown, behind a click, only on a catalog page that is itself gated. A catalog published with --public carries neither keys nor logins. The page is an index of everything you host, so it asks for Cloudflare Access sign-in by default, for the email that owns the account; pass --access to choose who else gets in, or --public to opt out. MCP tools: catalog, project.

Turn a cloudfact off (and back on)

Off means the link answers nothing, and that is all it means: the files, the address, the key and the sign-in stay where they are, so turning it back on brings the very same link back.

cloudfact off painel      # the link stops answering
cloudfact on painel       # the same link works again

A Workers deploy loses its workers.dev address while off (its preview URLs too), and carries a cloudfact:off tag so the catalog can tell from any machine. A tunnel keeps its hostname and answers every request with a short "this page is off" page, WebSockets included, so its random trycloudflare.com address survives the pause. Deploying it again also turns it on. stop and rm are still there when you want the local process ended or the deploy gone. MCP tool: power.

From the catalog page. On a catalog behind sign-in, every card that can be switched has a ✕ in its corner: one click and a confirmation turn it off, and an off card shows Off and a Turn on button. The page reads the live position of every switch when it opens, so it stays right after a change made elsewhere. For that, the catalog's Worker holds your API token as an encrypted Worker secret, together with the list of what it may switch; it does nothing else with it:

  • It switches only the deploys on that list: the Workers in the account, and the tunnels this machine serves (through their host, with a control key of their own, which is not the private key: whoever holds a shared link can open a page, not turn it off). Never the catalog itself, never anything else.

  • It answers only behind Cloudflare Access, and only to a request from the page itself (a custom header and the page's own origin), so another site cannot use your sign-in to switch anything.

  • A catalog published with --public, or behind a key link, gets neither the switch nor the token; republishing a catalog without the switch removes both from its Worker.

Tunnels started by a cloudfact older than this feature have no switch until they are started again (--restart); their cards simply have no ✕.

Look

The pages cloudfact generates carry the CloudFacts identity: the mark, CloudFacts Sans and an off-white #F4F4F1 on a dark surface. The catalog page is published with the font files beside it and the private gate carries the mark inline, so neither fetches anything from the network when someone opens it. The font ships in weights 400 and 500 only, which is why nothing asks for a bolder one: the browser would fake it. Assets and their licence live in brand/. Your own pages are never restyled; cloudfact only dresses the pages it makes.

MCP

Stdio server. Tools: deploy, expose, list, catalog, project, credentials, status, rotate, power, stop, remove, logs, doctor — see docs/tools.md (generated from the code). Prompt: cloudfact. Sign-in is deliberately outside the MCP: run cloudfact login in a terminal so the token never enters the agent context.

Skill /cloudfact <path> [--private] [--name x] [--tunnel|--workers] lives in skills/cloudfact/SKILL.md; the Claude Code plugin ships it, and install.sh links it into ~/.codex/skills.

CLI

cloudfact deploy [path] [--name n] [--public] [--expires 24h] [--backend auto|tunnel|workers] [--restart] [--json]
cloudfact expose <port> [--name n] [--public] [--expires 24h] [--ssh user@host] [--ssh-port 22] [--identity key] [--strict-host-key] [--restart] [--json]
cloudfact rotate <name> [--expires 24h]
cloudfact off <name> | on <name>
cloudfact list | status <name> | stop <name>|--all | rm <name> | logs <name> [-n 40]
cloudfact doctor | setup | login --device | login --token T [--account-id ID] | logout
cloudfact config get | set <key> <value>
cloudfact mcp                     # MCP server over stdio

State: ~/.cloudfact/deploys/<name>/ (state.json, host.log, tunnel.log, wrangler.log). Different directory: CLOUDFACT_HOME=/x.

Development

TypeScript. Runtime dependencies (MCP SDK and zod) are bundled into dist/.

src/
  bin.ts                 CLI entry              → dist/bin.js
  server.ts              MCP entry (stdio)      → dist/server.js
  index.ts               public API (library)   → dist/index.js + .d.ts
  cloudfact.ts           use cases: deploy, stop, remove, status, doctor
  config.ts  types.ts  logger.ts
  mcp/
    server.ts            createServer(): registers tools and prompt
    define-tool.ts       typed defineTool() with annotations (readOnlyHint, destructiveHint)
    tools/               tool definitions
  backends/
    tunnel/              static-server.ts · proxy.ts (expose: HTTP + WebSocket) · gate.ts (private mode) · host.ts (detached process → dist/host.js) · index.ts
    workers/             wrangler deploy --assets
  services/              state (atomic on disk) · cloudflared (lookup/download) · wrangler · auth (token / device)
tests/                   vitest: static server, state, MCP in-memory, workers with a fake wrangler, CLI
scripts/                 generate-docs (docs/tools.md from the tool definitions) · verify-versions
skills/cloudfact/        the /cloudfact skill
.claude-plugin/          plugin and marketplace manifests
server.json              MCP registry manifest
npm run check      # typecheck + lint + test + build + docs + version sync (what CI runs)
npm test           # vitest
npm run build      # tsup → dist/ (committed on purpose: the plugin works straight from git, no npm install)
npm run docs       # regenerate docs/tools.md
npm run inspect    # MCP Inspector against dist/server.js

CI fails if dist/ or docs/tools.md are stale, or if the version differs across package.json, server.json and the plugin manifests. Every push to main is released automatically (patch bump by the workflow; npm run bump for minor/major). See CONTRIBUTING.md and SECURITY.md.

Roadmap

  • Cloudflare Access on the tunnel backend (needs a domain of your own + named tunnel).

  • Other identity providers (Google, GitHub) for Access besides the one-time PIN.

  • cloudfact run: rsync a project to an SSH host, start it there, and expose it in one step.

  • --private on the workers backend (minimal worker checking the cookie).

  • Named tunnel (fixed URL on your own domain).

  • npm publish (npx cloudfact).

  • HTTP transport for remote MCP connectors (claude.ai web).

License

MIT

Available Tools

13 tools
catalogAccount catalogA

Every cloudfact in the user's Cloudflare account, grouped by project, as the account itself sees them (so deploys made from another machine show up too). Each entry says whether it is public, a private key link or behind Cloudflare Access sign-in, and whether it serves static files or an app with its own server. Quick tunnels have no account-side resource and appear only when this machine still has their record (inAccount=false). publish=true turns the catalog into a browsable page and returns its URL; that page asks for Cloudflare Access sign-in by default, for the email that owns the account.

Inputs: access, project, publish.

credentialsSet app loginA
Idempotent

Record how to get into the app behind a deploy (its own username/password/note, not cloudfact's). Stored with the deploy on this machine and shown only on a catalog page that is itself behind Cloudflare Access sign-in. Pass creds=null to clear. Never put the user's secrets in your reply.

Inputs: name (required), note, user, clear, +1 more.

deployPublish static siteA
Idempotent

Publish a folder (or a single .html file) from this machine to a public Cloudflare URL. "tunnel" backend (default when signed out): local static server + cloudflared quick tunnel, *.trycloudflare.com URL; the process runs in the background and outlives the session. "workers" backend (default when signed in): Cloudflare Workers with static assets, fixed URL https://..workers.dev; redeploying updates the same address. Idempotent on tunnel: if the same path is already live, returns the existing URL (reused=true). Deploys are PRIVATE by default on both backends (key-gated link; on workers a gate Worker runs in front of the files); pass public=true to publish openly. access=[emails] (workers backend, API-token login) puts Cloudflare Access in front instead: visitors sign in with a one-time email code and only listed emails get in. Returns JSON with url and, when private, privateUrl (already includes #key=...).

Inputs: path (required), name, access, public, +3 more.

doctorDiagnosticsB
Read-only

Diagnostics: cloudflared, Cloudflare sign-in, default backend and active deploys. Run it before deploy when something fails.

Inputs: no named parameters.

exposeExpose a running appA
Idempotent

Publish an app that is already listening on a port to a public *.trycloudflare.com URL (tunnel backend). Without ssh, the port is on this machine. With ssh (user@host), the app runs on another machine: cloudfact opens an SSH port-forward to it and publishes through here — nothing to install remotely (key-based SSH access required). HTTP and WebSocket traffic is proxied. Apps are PRIVATE by default (same #key gate as static deploys, with rate limiting and optional expiry); pass public=true to publish without the gate. Idempotent: the same port/host already live returns the existing URL (reused=true).

Inputs: port (required), ssh, name, access, +6 more.

listList deploysA
Read-only

List every cloudfact deploy with backend, status and URL.

Inputs: no named parameters.

logsDeploy logsA
Read-only

Last lines of the deploy logs: host (local server), cloudflared and wrangler.

Inputs: name (required), lines.

powerTurn off or onA
Idempotent

Turn a cloudfact off, or back on. Off: its link stops answering (a Workers deploy loses its workers.dev address; a tunnel answers with a "this page is off" page) but nothing is deleted, so on=true brings the very same link back, with the same key and sign-in. Deploying it again also turns it on. Prefer this over remove when the user wants something "off" or "down" rather than gone. The catalog page behind sign-in has the same switch on every card.

Inputs: on (required), name (required).

projectSet projectA
Idempotent

File a deploy under a project in the account catalog (or pass project=null to clear it). Takes effect without redeploying.

Inputs: name (required), project (required).

removeRemove deployA
Destructive

Stop (if running) and delete the deploy record and logs. On the workers backend, also deletes the worker on Cloudflare.

Inputs: name (required).

rotateRotate private keyA

Issue a new private key for a live tunnel deploy without restarting it: the previous link and all sessions stop working at once. Optionally set an expiry. On a public deploy this turns it private. Returns the new privateUrl.

Inputs: name (required), expires.

statusDeploy statusA
Read-only

State of one deploy, including an HTTP check of its public URL (reachable/httpStatus).

Inputs: name (required).

stopStop deployA

Stop the local server and tunnel of one deploy (or all of them with all=true). The record is kept for inspection. Not applicable to the workers backend.

Inputs: all, name.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 13 tools

    Disambiguation3/5

    Several tools have overlapping-ish territory: list vs catalog (local records vs account-wide), stop vs power vs remove (three ways to make a deploy 'not running'), and deploy vs expose (two publish paths). The detailed descriptions do clarify the boundaries (e.g. 'prefer power over remove'), but an agent must read carefully to avoid misselection.

    Naming Consistency3/5

    All names are single lowercase words, which is at least uniformly styled, but there's no predictable verb/noun convention: some are verbs (list, stop, expose, deploy, rotate) and some are nouns (catalog, project, credentials, status, logs, doctor). Readable but no coherent pattern to infer intent from name alone.

    Tool Count4/5

    13 tools is a reasonable scope for a deploy/tunnel/workers management server, and most map to distinct lifecycle operations. Slightly heavy with some closely related operations (stop/power/remove), but each earns its place.

    Completeness4/5

    Strong lifecycle coverage: deploy, expose, status, logs, stop, remove, power off/on, rotate keys, project filing, credentials, account catalog, and diagnostics. Minor gaps like a bulk redeploy/update-content primitive, but core create-inspect-modify-teardown workflows are all present.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables deployment of HTML content, folders, and full-stack projects to EdgeOne Pages to generate publicly accessible URLs. It utilizes EdgeOne Pages Functions and KV storage for high-performance edge delivery of web applications.
      2
      8 npm
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Enables the deployment of HTML content, folders, and full-stack projects to EdgeOne Pages to generate publicly accessible URLs. It integrates with edge functions and KV storage to provide fast content delivery and supports custom domain configuration.
      2
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables remote MCP clients to access local filesystem and shell commands by deploying a Cloudflare Worker relay and a local daemon, providing tools like read/write files, exec commands, git status, etc.
      379 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Exposes a local development project as a secure MCP server over a stable HTTPS URL via Cloudflare tunnel, with configurable access permissions and 33 development tools for file, command, Git, and process operations.
      MIT