StateSet Worker

Run the StateSet iCommerce engine in a Cloudflare Sandbox — wrangler deploy and you have a full commerce engine with messaging channels, MCP tools, and an admin UI.

Architecture

Browser / AI Agent / Messaging Platform
        │
┌───────┴──────────────────────────────────┐
│  Cloudflare Worker (Hono.js)             │
│  - CF Access auth                        │
│  - Admin UI (React SPA)                  │
│  - HTTP/WebSocket proxy to container     │
│  - Cron: SQLite backup to R2             │
└───────┬──────────────────────────────────┘
        │
┌───────┴──────────────────────────────────┐
│  CF Container (Durable Object)           │
│  - @stateset/cli (stateset-channels.js)  │
│  - @stateset/embedded (Rust/SQLite)      │
│  - 6 messaging channels                 │
│  - MCP server (87 tools)                 │
│  - HTTP gateway on port 8080             │
│  - R2 mounted at /data/stateset          │
└──────────────────────────────────────────┘

Requirements

Workers Paid plan ($5 USD/month) — required for Cloudflare Sandbox containers
Anthropic API key — or use AI Gateway for routing and analytics

Free-tier Cloudflare features used:

Cloudflare Access (authentication)
AI Gateway (optional, for API routing/analytics)
R2 Storage (optional, for persistence)

Quick Start

# Install dependencies
npm install

# Set your API key
npx wrangler secret put ANTHROPIC_API_KEY

# Deploy
npm run deploy

After deploying, your commerce engine is live at https://stateset-sandbox.your-subdomain.workers.dev/.

The first request takes 1-2 minutes while the container boots. A loading page is shown during startup.

To use the admin UI and protected routes, you'll need to:

Set up Cloudflare Access for authentication
Enable R2 storage so commerce data persists (recommended)

Setting Up Cloudflare Access

The admin UI at /_admin/ and all /api/admin/* routes require Cloudflare Access authentication.

1. Enable Access on workers.dev

Go to the Workers & Pages dashboard
Select your Worker (stateset-sandbox)
In Settings > Domains & Routes, click the ... menu on the workers.dev row
Click Enable Cloudflare Access
Configure who can access (email allow list, Google, GitHub, etc.)
Copy the Application Audience (AUD) tag

2. Set Access Secrets

npx wrangler secret put CF_ACCESS_TEAM_DOMAIN
# Enter: myteam.cloudflareaccess.com

npx wrangler secret put CF_ACCESS_AUD
# Enter: your-application-audience-tag

Find your team domain in the Zero Trust Dashboard under Settings > Custom Pages.

3. Redeploy

npm run deploy

Now /_admin/ requires Cloudflare Access authentication.

Persistent Storage (R2)

By default, commerce data (SQLite database, config) is lost when the container restarts. R2 storage enables persistence.

Setup

Go to R2 > Overview in the Cloudflare Dashboard
Click Manage R2 API Tokens
Create a token with Object Read & Write permissions for the stateset-data bucket

npx wrangler secret put R2_ACCESS_KEY_ID
npx wrangler secret put R2_SECRET_ACCESS_KEY
npx wrangler secret put CF_ACCOUNT_ID

How It Works

SQLite backup — The commerce database is backed up safely using SQLite's built-in .backup API, which handles concurrent writes correctly. A cron job runs every 5 minutes.

Config sync — Gateway configuration is synced to R2 via rsync.

Restore on boot — On container startup, data is restored from R2 if the backup is newer than local data. An integrity check verifies the database before restoring.

Manual backup — Trigger an immediate backup from the admin UI Storage tab or via POST /api/admin/storage/sync.

Admin UI

Access the admin UI at /_admin/ with three tabs:

Overview — Gateway status, commerce stats (customers, orders, returns, products), channel summary, restart controls
Channels — Per-channel status cards for all 6 messaging channels (Telegram, Discord, Slack, WhatsApp, Email, SMS)
Storage — R2 configuration status, last backup time, manual backup button, backup strategy info

Messaging Channels

Configure channels via environment secrets. Each channel is enabled automatically when its token is set.

Telegram

npx wrangler secret put TELEGRAM_BOT_TOKEN

Discord

npx wrangler secret put DISCORD_BOT_TOKEN

Slack

npx wrangler secret put SLACK_BOT_TOKEN
npx wrangler secret put SLACK_APP_TOKEN

WhatsApp

npx wrangler secret put WHATSAPP_TOKEN

Email

npx wrangler secret put EMAIL_SMTP_HOST

SMS (Twilio)

npx wrangler secret put TWILIO_ACCOUNT_SID

Commerce Settings

# Enable apply mode
npx wrangler secret put ALLOW_APPLY
# Enter: true

# Override default AI model
npx wrangler secret put DEFAULT_MODEL
# Enter: claude-opus-4-5

AI Gateway (Optional)

Route API requests through Cloudflare AI Gateway for caching, rate limiting, and analytics:

npx wrangler secret put AI_GATEWAY_API_KEY
npx wrangler secret put AI_GATEWAY_BASE_URL
# Enter: https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/anthropic

AI Gateway variables take precedence over direct ANTHROPIC_API_KEY if both are set.

Container Lifecycle

By default, the container stays alive indefinitely. To sleep after inactivity (reduces cost, adds cold start latency):

npx wrangler secret put SANDBOX_SLEEP_AFTER
# Enter: 10m (or 1h, 30m, etc.)

With R2 configured, data persists across restarts.

Debug Endpoints

Enable with DEBUG_ROUTES=true (requires Cloudflare Access):

Endpoint	Description
`GET /debug/version`	Container and stateset version info
`GET /debug/processes`	All container processes (add `?logs=true` for output)
`GET /debug/cli?cmd=...`	Run a CLI command in the container
`GET /debug/logs?id=...`	Logs for a specific process
`GET /debug/env`	Sanitized environment configuration
`GET /debug/container-config`	Gateway config from inside the container

Local Development

cp .dev.vars.example .dev.vars
# Edit .dev.vars with your ANTHROPIC_API_KEY
npm install
npm run dev

Set DEV_MODE=true in .dev.vars to skip Cloudflare Access auth.

All Secrets Reference

Secret	Required	Description
`ANTHROPIC_API_KEY`	Yes*	Anthropic API key (or use AI Gateway)
`AI_GATEWAY_API_KEY`	Yes*	AI Gateway provider key (requires `AI_GATEWAY_BASE_URL`)
`AI_GATEWAY_BASE_URL`	No	AI Gateway endpoint URL
`OPENAI_API_KEY`	No	OpenAI API key (alternative provider)
`CF_ACCESS_TEAM_DOMAIN`	Yes	Cloudflare Access team domain
`CF_ACCESS_AUD`	Yes	Cloudflare Access application audience
`STATESET_GATEWAY_TOKEN`	No	Gateway auth token
`R2_ACCESS_KEY_ID`	No	R2 access key for persistent storage
`R2_SECRET_ACCESS_KEY`	No	R2 secret key for persistent storage
`CF_ACCOUNT_ID`	No	Cloudflare account ID (required for R2)
`TELEGRAM_BOT_TOKEN`	No	Telegram channel
`DISCORD_BOT_TOKEN`	No	Discord channel
`SLACK_BOT_TOKEN`	No	Slack channel
`SLACK_APP_TOKEN`	No	Slack channel (required with SLACK_BOT_TOKEN)
`WHATSAPP_TOKEN`	No	WhatsApp channel
`EMAIL_SMTP_HOST`	No	Email channel
`TWILIO_ACCOUNT_SID`	No	SMS channel (Twilio)
`ALLOW_APPLY`	No	Set to `true` to enable apply mode
`DEFAULT_MODEL`	No	Override default AI model
`DEV_MODE`	No	Set to `true` for local dev (skips auth)
`DEBUG_ROUTES`	No	Set to `true` to enable `/debug/*` routes
`SANDBOX_SLEEP_AFTER`	No	Container sleep timeout: `never` (default), `10m`, `1h`

* One of ANTHROPIC_API_KEY or AI_GATEWAY_API_KEY is required.

Troubleshooting

Container fails to start: Check npx wrangler tail for logs. Verify ANTHROPIC_API_KEY is set.

R2 not mounting: Ensure all three secrets are set (R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY, CF_ACCOUNT_ID). R2 mounting only works in production.

Access denied on admin routes: Verify CF_ACCESS_TEAM_DOMAIN and CF_ACCESS_AUD are set correctly.

Slow first request: Cold starts take 1-2 minutes. A loading page is shown automatically.

Config changes not working: Update the Dockerfile cache bust comment and redeploy.

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
.github/workflows		.github/workflows
src		src
.dev.vars.example		.dev.vars.example
.gitignore		.gitignore
AGENTS.md		AGENTS.md
Dockerfile		Dockerfile
README.md		README.md
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
start-stateset.sh		start-stateset.sh
stateset.json.template		stateset.json.template
tsconfig.json		tsconfig.json
vite.config.ts		vite.config.ts
vitest.config.ts		vitest.config.ts
wrangler.jsonc		wrangler.jsonc

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

StateSet Worker

Architecture

Requirements

Quick Start

Setting Up Cloudflare Access

1. Enable Access on workers.dev

2. Set Access Secrets

3. Redeploy

Persistent Storage (R2)

Setup

How It Works

Admin UI

Messaging Channels

Telegram

Discord

Slack

WhatsApp

Email

SMS (Twilio)

Commerce Settings

AI Gateway (Optional)

Container Lifecycle

Debug Endpoints

Local Development

All Secrets Reference

Troubleshooting

Links

About

Uh oh!

Releases

Packages

Languages

stateset/stateset-worker

Folders and files

Latest commit

History

Repository files navigation

StateSet Worker

Architecture

Requirements

Quick Start

Setting Up Cloudflare Access

1. Enable Access on workers.dev

2. Set Access Secrets

3. Redeploy

Persistent Storage (R2)

Setup

How It Works

Admin UI

Messaging Channels

Telegram

Discord

Slack

WhatsApp

Email

SMS (Twilio)

Commerce Settings

AI Gateway (Optional)

Container Lifecycle

Debug Endpoints

Local Development

All Secrets Reference

Troubleshooting

Links

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages