☁️ CFShare

Securely share local files and services to the public internet via Cloudflare Tunnel

简体中文  |  English

---

📖 What Is This?

CFShare is a community plugin for OpenClaw that enables your AI assistant to:

• 🔗 Expose a local port as a temporary public HTTPS link (https://*.trycloudflare.com) with one command
• 📁 Share files/directories — automatically spins up a local static server + tunnel so recipients can browse/download/preview via a link (encryption supported)
• 🔒 Built-in security — Token/Basic auth, rate limiting, port blacklist, exclusion rules
• ⏱️ Auto-expiry cleanup — tunnels are automatically closed and temp files deleted when the TTL expires

Note

No Cloudflare account required. CFShare uses Cloudflare Quick Tunnel (trycloudflare.com), which is completely free and works out of the box.

---

🏗️ How It Works

flowchart LR
    subgraph LOCAL["Your Machine"]
        A["Local Service / Files"]
        B["[Optional] Reverse Proxy<br/>(Auth + Rate Limit)"]
        C["cloudflared tunnel"]

        A --> B
        B --> C
    end

    C ==>|Cloudflare Quick Tunnel| D["https://xxx.trycloudflare.com"]
    E["Recipient's Browser"] --> D

Loading

Internally, CFShare handles: path validation → copy files to a temp directory → start a read-only static server → mount auth/rate-limit reverse proxy → launch cloudflared tunnel → schedule expiry cleanup. All you need to do is tell the AI "what you want to share" and it takes care of the rest.

---

🚀 Installation

Step 1: Make Sure OpenClaw Is Installed

If you haven't installed OpenClaw yet, do so first:

# Install OpenClaw (requires Node.js ≥ 22)
npm install -g openclaw@latest

# Run the onboarding wizard
openclaw onboard --install-daemon

Tip

Not sure about your Node.js version? Run node -v to check. nvm is recommended for managing versions.

---

Step 2: Install cloudflared

CFShare relies on Cloudflare's cloudflared CLI to create tunnels.

🍎 macOS

brew install cloudflare/cloudflare/cloudflared

🐧 Linux (Debian / Ubuntu)

curl -fsSL https://pkg.cloudflare.com/cloudflare-main.gpg | sudo tee /usr/share/keyrings/cloudflare-main.gpg >/dev/null
echo "deb [signed-by=/usr/share/keyrings/cloudflare-main.gpg] https://pkg.cloudflare.com/cloudflared $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/cloudflared.list
sudo apt-get update && sudo apt-get install cloudflared

🪟 Windows (inside WSL2)

# Inside WSL2:
curl -fsSL https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o /usr/local/bin/cloudflared
chmod +x /usr/local/bin/cloudflared

Or install natively via PowerShell / CMD with winget:

winget install --id Cloudflare.cloudflared

Or simply ask the Agent to install it for you.

Verify the installation:

cloudflared --version
# Output should be similar to: cloudflared version 2025.x.x

Important

You only need to install cloudflared — there is no need to run cloudflared tunnel login. Quick Tunnel requires no account authentication.

---

Step 3: Install the CFShare Plugin

Option A — Install from npm (recommended):

openclaw plugins install @ystemsrx/cfshare
# After installation, restart the Gateway:
openclaw gateway restart

Option B — Install from a local directory (for development):

If you've already cloned the repository:

# Install dependencies first
cd /path/to/cfshare
npm install

# Link to OpenClaw (dev mode, no file copying)
openclaw plugins install -l .

---

Step 4: Enable the Plugin and Restart the Gateway

# Enable the plugin
openclaw plugins enable cfshare

# Restart the Gateway to load the plugin
openclaw gateway restart

Note

If you're running in daemon mode (--install-daemon), you can also restart via openclaw restart.

---

⚙️ Configuration (Optional)

CFShare works out of the box. The defaults below suit most use cases. To customize, edit ~/.openclaw/openclaw.json:

{
  plugins: {
    entries: {
      cfshare: {
        enabled: true,
        config: {
          // Custom configuration (all fields are optional)
        },
      },
    },
  },
}

Configuration Reference

Option	Default	Description
cloudflaredPath	"cloudflared"	Path or command name for cloudflared
stateDir	~/.openclaw/cfshare	Directory for state file storage
defaultTtlSeconds	3600 (1 hour)	Default tunnel time-to-live
maxTtlSeconds	86400 (24 hours)	Maximum TTL cap
defaultExposePortAccess	"token"	Default auth mode for port exposure
defaultExposeFilesAccess	"none"	Default auth mode for file sharing
blockedPorts	[22, 2375, 2376]	Ports blocked from exposure (SSH/Docker)
rateLimit.enabled	true	Whether rate limiting is enabled
rateLimit.maxRequests	240	Max requests per window
rateLimit.windowMs	60000 (1 minute)	Rate limit window in milliseconds

Tip

Auth mode reference:

• "token" — A token is required to access the link (suitable for port exposure)
• "basic" — HTTP Basic authentication (username/password)
• "none" — No authentication, anyone can access (suitable for temporary file sharing)

---

💬 Usage Examples

Once installed, just speak naturally to your AI assistant — it will automatically invoke the appropriate CFShare tools:

Get AI-Processed Files

"Rename all files under /mnt/data/students/ to {index}_{name}.{ext} format, then bundle them up and give me a download link."

The Agent will automatically call expose_files and return a public link along with its expiration time.

Share Your Creations

"Build a 3D interactive solar system model with Vue 3 + Vite, then share it with my friend via a link."

"Run this project for me and send me the link to access it."

The Agent will create and run the project, then use expose_port to create a tunnel so anyone can access it through a link.

Share a Directory (with File Browser) — preview images/videos/text in-browser, or download (encryption supported)

"Share the directory ~/Pictures/vacation with encryption."

The Agent will use expose_files in preview mode to create a share page with a file browser. A valid token is required to access it.

View Active Shares

"What links do I have active right now?"

Stop Sharing

"Shut down all active share links."

---

🧰 Tool Overview

CFShare registers the following tools for the AI:

Tool	Purpose
env_check	Check if cloudflared is available & view policy
expose_port	Expose a local port to the public internet
expose_files	Share files/directories (auto static server)
exposure_list	List all active sessions
exposure_get	Get details for a specific session
exposure_stop	Stop and clean up specific or all sessions
exposure_logs	View session logs
maintenance	TTL guardian / garbage collection / policy refresh
audit_query	Query audit logs
audit_export	Export audit logs to a file

---

🔐 Security Design

🛡️	Secure by Default	Port exposure defaults to token auth + reverse proxy protection
🚫	Port Blacklist	SSH (22) and Docker Daemon (2375/2376) are blocked by default
⏳	Auto Expiry	Sessions automatically close tunnels and delete temp files upon expiration
📊	Rate Limiting	Per-IP sliding window rate limiting (default: 240 req/min)
📝	Audit Logging	All operations are logged to a local JSONL file
🙈	File Exclusion	Automatically excludes .git/, .openclaw/, and respects .gitignore rules

---

❓ FAQ

Q: Do I need a paid Cloudflare account?

No. CFShare uses Cloudflare Quick Tunnel (trycloudflare.com), which is completely free and requires no account registration.

Q: How long do links last?

By default, 1 hour. This can be adjusted via configuration or specified per share (up to 7 days). Links are automatically destroyed upon expiry.

Q: What if cloudflared is not found?

1. Confirm cloudflared is installed: cloudflared --version
2. If it's installed in a location not in your PATH, specify the full path in the config:

{
  plugins: {
    entries: {
      cfshare: {
        config: { cloudflaredPath: "/usr/local/bin/cloudflared" },
      },
    },
  },
}

Q: Can I use it directly on Windows?

OpenClaw officially strongly recommends using WSL2 on Windows. CFShare follows the same guidance — please use it within a WSL2 environment.

Q: How do I verify the plugin installed correctly?

openclaw plugins list
# You should see cfshare listed as enabled

Then tell the AI "Run the cfshare environment check" — it will call env_check and return detailed status information.

---

📄 License

MIT © ystemsrx