cloudfact
cloudfact publishes local folders, single HTML files, or apps already running on a port (locally or over SSH) to public Cloudflare URLs, and manages those deploys.
Deploy static sites — publish a folder or
.htmlfile to a*.trycloudflare.comquick tunnel (no account) or a fixed*.workers.devURL (signed in).Expose running apps — publish anything listening on a port, including apps on another machine over SSH (HTTP + WebSocket proxied), with no remote install.
Private by default — every deploy is key-gated (
#key=…link with rate limiting and optional expiry); passpublicto open it up.Identity sign-in — restrict a workers deploy to specific emails via Cloudflare Access one-time email codes (
access=[emails]).List & catalog — list deploys, or build an account-wide catalog grouped by project, optionally published as a browsable page with thumbnails and one-click links.
Organize — file deploys under projects and store app-level logins/notes for the app behind a deploy.
Operate — check status with an HTTP reachability probe, rotate private keys, turn deploys off/on without losing the link, stop local processes, remove deploys (and their Workers), read logs, and run diagnostics.
Troubleshoot —
doctorchecks cloudflared, sign-in, default backend and active deploys.
Enables publishing local folders, single HTML files, and apps listening on a port to public Cloudflare URLs, using Cloudflare quick tunnels with optional private key-gated links and account-based deployments.
Allows deploying static site assets to Cloudflare Workers with fixed worker.dev URLs, including listing, status, rotation, removal, and log management for deployments.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@cloudfact deploy ./report.html to a public URL"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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@cloudfactEverything 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 | bashCodex — 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 --codexIt 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 gateApps 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 |
| no |
| local static server + |
| yes |
| Cloudflare Workers with static assets, the successor of Pages (Cloudflare no longer creates new Pages projects). |
Private links (the default)
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 lifetimerotate 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 requiredThe 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 itsRESEND_API_KEYsecret, through redeploys; it is not stored on this machine. The page then mails the code itself, fromCloudFact <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--accessemails 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'sonboarding@resend.devonly delivers to the Resend account's owner; to let other people in, verify a domain in Resend and set theCLOUDFACT_MAIL_FROMvar.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--accesslist). 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 itEach 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 againA 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 stdioState: ~/.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 manifestnpm 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.jsCI 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.--privateon 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 toolscatalogAccount 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 loginAIdempotent
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 siteAIdempotent
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.
doctorDiagnosticsBRead-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 appAIdempotent
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 deploysARead-only
List every cloudfact deploy with backend, status and URL.
Inputs: no named parameters.
logsDeploy logsARead-only
Last lines of the deploy logs: host (local server), cloudflared and wrangler.
Inputs: name (required), lines.
powerTurn off or onAIdempotent
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 projectAIdempotent
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 deployADestructive
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 statusARead-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
Scored across 13 tools
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.
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.
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.
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
Related MCP Connectors
Secure tunneling, reverse proxy and remote access for local applications.
Get share links, publish and manage websites, artifacts and agents. No account needed.
Agent-first hosting: create apps, push code, and deploy to HTTPS URLs from your coding agent.
Publish a single HTML file as a live HTTPS site in seconds. Versioned deploys, no delete tool.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables 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.28 npmMIT
- AlicenseBqualityDmaintenanceEnables 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.2MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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 npm1MIT
- AlicenseNot gradedqualityCmaintenanceExposes 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