Skip to content

Instantly share code, notes, and snippets.

@decagondev

decagondev/MOLT-WORKER-SETUP.md

Created February 12, 2026 03:56
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save decagondev/3e7ea87558b4462ad0ad0b5169e67a25 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save decagondev/3e7ea87558b4462ad0ad0b5169e67a25 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
MOLT-WORKER-SETUP.md

Step-by-Step Guide to Setting Up Moltworker on Cloudflare

This guide is based on the official Cloudflare Moltworker repository (https://github.com/cloudflare/moltworker), which allows you to run OpenClaw (formerly Moltbot/Clawdbot) as a self-hosted personal AI agent on Cloudflare Workers. The setup uses Cloudflare's Sandbox containers for execution, with optional persistence via R2 storage. I've adapted the instructions to use the Cloudflare dashboard UI exclusively for setting secrets and configurations (no Wrangler CLI). Note that as of February 2026, some Cloudflare dashboard navigation paths have been updated for better integration with Zero Trust (formerly Cloudflare Access), and I've incorporated the latest from the repo's README and related documentation. The process involves prerequisites, deployment, security setup, storage configuration, and testing. Expect the full setup to take 30-60 minutes, with some waiting time for deployments and container startups.

Step 1: Prepare Prerequisites

Before starting, ensure you have everything ready. These are required for deployment and operation.

  1. Create or Log In to a Cloudflare Account:

  2. Upgrade to a Workers Paid Plan:

    • In the Cloudflare dashboard (https://dash.cloudflare.com), navigate to Workers & Pages > Overview.
    • If you're on the free plan, click Upgrade plan or go to Account > Subscriptions > Workers Paid (costs $5 USD/month minimum, plus usage-based fees for Sandbox containers—estimate ~$34.50/month for 24/7 operation on a standard-1 instance, or less with sleep settings).
    • Enter payment details and confirm. This enables Sandbox containers, which are essential for running the AI agent.

  3. Add an R2 Subscription:

    • From the dashboard, go to R2 > Overview.
    • If not subscribed, click Add R2 Subscription (it's free with a generous tier: 10 GB storage, 1 million read/write operations per month).
    • Confirm the addition (no cost unless you exceed free limits). This is required even if you skip persistence initially, as the deploy button may prompt for it.

  4. Obtain an Anthropic API Key:

    • Log in to the Anthropic dashboard at https://console.anthropic.com/.
    • Navigate to API Keys > Generate New Key.
    • Name it something like "Moltworker" and copy the key (it starts with sk-ant-). Save it securely—you won't see it again.
    • Note: Top up your Anthropic account with credits if needed (e.g., $10-20 to start), as the AI model (Claude) requires them. Alternatively, you can use Cloudflare's AI Gateway for unified billing (free tier available), but this guide assumes direct Anthropic access for simplicity.

  5. Generate a Gateway Token:

    • This is a secure password for accessing the control UI.
    • Use a secure method to generate a 32-byte hex string. For example:
      • On macOS/Linux: Open a terminal and run openssl rand -hex 32.
      • On Windows: Use PowerShell with [guid]::NewGuid().ToString("N") or an online generator like https://www.grc.com/passwords.htm (ensure it's secure).
    • Copy the generated token (e.g., a long string like a1b2c3d4...) and save it securely. You'll need it during deployment and for UI access.

  6. Set Up a GitHub Account:

    • If you don't have one, sign up at https://github.com/signup.
    • You'll need this to fork or connect the repository during deployment.

Step 2: Deploy Moltworker from GitHub

Use the one-click deploy button on the repo for initial setup. This creates the Worker, connects GitHub, sets up an R2 bucket, and injects initial secrets.

  1. Go to the Moltworker GitHub Repository:

  2. Click the Deploy to Cloudflare Button:

    • Look for the Deploy to Cloudflare or Deploy with Workers button (it's typically a purple button near the top of the README).
    • Click it to start the deployment wizard.

  3. Log In and Authorize:

    • Log in to Cloudflare if prompted (use the same account from Step 1).
    • Verify as human (CAPTCHA) and confirm 2FA.
    • Connect your GitHub account: Click Connect GitHub > Install & Authorize on your personal GitHub account or organization.
    • Authorize Cloudflare to access repositories (enable 2FA on GitHub if prompted).

  4. Configure Deployment Options:

    • Repository: Create a new private repository (recommended for security—name it something like "moltworker-sandbox").
    • R2 Bucket: Check Create new R2 bucket (default name like "moltbot-data" is fine).
    • Location Hint: Optional—select your region (e.g., Asia-Pacific) for better performance.
    • Anthropic API Key: Paste the key from Step 1.4.
    • Gateway Token: Paste the token from Step 1.5.
    • Advanced settings: Leave defaults unless you want to customize (e.g., enable AI Gateway instead of direct Anthropic).
    • Click Create and Deploy.

  5. Wait for Deployment:

    • This may take 1-5 minutes. If you see errors about R2 or paid plans, refresh the page or ensure Steps 1.2-1.3 are complete, then retry.
    • Once done, note your Worker URL (e.g., https://moltworker-sandbox..workers.dev). You'll use this for access.

Step 3: Set Up Cloudflare Access (Authentication)

This secures the admin UI with Zero Trust. As of 2026, Cloudflare Access is integrated into Zero Trust—enable the free plan if not already active.

  1. Enable Zero Trust (if Needed):

    • Go to https://dash.teams.cloudflare.com (Zero Trust dashboard).
    • If prompted, select the Zero Trust Free Plan > Review and Purchase (cost: $0).
    • Confirm and return to the main dashboard.

  2. Enable Cloudflare Access on Your Worker:

    • In the Cloudflare dashboard, go to Workers & Pages > Overview > Select your Worker (e.g., "moltworker-sandbox").
    • Navigate to Settings > Domains & Routes.
    • Find your route (e.g., *.workers.dev) and click the three-dot menu (meatballs icon) > Enable Cloudflare Access.
    • In the popup, click Manage > Add your email to the allow list (e.g., your login email).
    • Configure identity providers if needed (default: One-time PIN via email).
    • Copy the Application Audience (AUD) Tag (a string like "abc123...") and JWKs URL (though you may not need the latter).
    • Dismiss the popup.

  3. Find Your Team Domain:

    • In the Zero Trust dashboard (https://dash.teams.cloudflare.com), go to Settings > Custom Pages.
    • Look for your team domain (e.g., https://.cloudflareaccess.com). If not visible, attempt a login to your Worker URL in an incognito window—it will show the domain in the login popup.

  4. Add Access Secrets via UI:

    • Back in your Worker settings: Settings > Variables & Secrets > Secrets tab > Add a secret.
    • Add CF_ACCESS_AUD: Paste the AUD tag from Step 3.2.
    • Add CF_ACCESS_TEAM_DOMAIN: Paste the team domain from Step 3.3 (e.g., "https://your-team.cloudflareaccess.com").
    • Click Deploy at the top to apply changes (takes ~30 seconds).

Step 4: Configure R2 Storage for Persistence (Recommended)

Without this, data (e.g., chat history) is lost on restarts. This is optional but advised for production use.

  1. Create an R2 API Token:

    • Go to R2 > Overview > Manage R2 API Tokens (updated path as of 2026; if not found, search for "API Tokens" in the dashboard).
    • Click Create API Token > Permissions: Object Read & Write > Apply to: Specific buckets > Select your bucket (e.g., "moltbot-data").
    • TTL: No expiration > Create.
    • Copy the Access Key ID and Secret Access Key. Save them securely.

  2. Find Your Cloudflare Account ID:

    • In the dashboard, go to Account Home > Right sidebar > Copy Account ID (a 32-character hex string).

  3. Add R2 Secrets via UI:

    • In your Worker settings: Settings > Variables & Secrets > Secrets tab > Add a secret.
    • Add R2_ACCESS_KEY_ID: Paste the Access Key ID.
    • Add R2_SECRET_ACCESS_KEY: Paste the Secret Access Key.
    • Add CF_ACCOUNT_ID: Paste your Account ID.
    • Click Deploy to apply (data will sync every 5 minutes via cron; manual backup available in admin UI).

Step 5: Access, Pair, and Test

  1. Open the Control UI:

    • Visit https://.workers.dev/?token=.
    • First load may take 1-2 minutes (container startup). If it disconnects, refresh.

  2. Handle Pairing and Admin UI:

    • If prompted for pairing: Open the admin UI at https://.workers.dev/_admin/ (after logging in via email code).
    • Approve your device in the Pending Paired Devices section.
    • R2 status should show as configured; if not, check secrets and redeploy.

  3. Test the AI Agent:

    • In the UI, start a new session and send a message (e.g., "Hello").
    • Check logs in Observability for errors. If no response, verify Anthropic credits or API key.
    • Test security: In an incognito window without your email, access should fail (no code sent).
    • Optional: Add channel integrations (e.g., Telegram) by adding secrets like TELEGRAM_BOT_TOKEN via UI and redeploying.

Troubleshooting Tips

  • Deployment Errors: Refresh pages or retry after enabling plans. Check Worker logs in Workers & Pages > Your Worker > Logs.
  • Container Costs: Add secret SANDBOX_SLEEP_AFTER = "10m" to sleep after inactivity (reduces bills).
  • Updates: The repo was last updated in early February 2026 with rclone for R2 and OpenClaw upgrades—pull changes via GitHub integration if needed.
  • Support: If stuck, check the repo's issues or Cloudflare docs at https://developers.cloudflare.com/workers/. For UX issues, the blog notes this is a proof-of-concept.

This setup gives you a secure, cloud-hosted AI agent. If you need expansions (e.g., AI Gateway or browser automation), add the relevant secrets via UI.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment