Skip to main content

​
Prerequisites

Node.js 18+

Required for wrangler CLI

Cloudflare account

Free tier is sufficient for development

Go 1.26+

Required to run the backend API locally

Python 3.11+

Required for the CLI and security helpers

​
1. Clone the repository

git clone https://github.com/your-org/superbox
cd superbox

​
2. Install Wrangler

npm install -g wrangler
# or use it locally:
cd cloudflare
npm install

​
3. Authenticate with Cloudflare

wrangler login
This opens a browser window - log in and authorise the OAuth token. No account_id needs to be set in wrangler.jsonc; wrangler reads it from the OAuth session.

​
4. Create the R2 bucket (one-time)

wrangler r2 bucket create superbox-mcp-registry
If the bucket already exists you will see a warning - that is fine.

​
5. Configure the Worker

Edit cloudflare/wrangler.jsonc if you want to change the worker name or add custom domains. The default config works out of the box.

​
6. Deploy the Worker

cd cloudflare
npx wrangler deploy
After deployment you should see: 
Deployed superbox-executor (X.XX sec)
  https://superbox-executor.<your-subdomain>.workers.dev

​
7. Configure the backend API

Copy the example env file: 
cd backend
cp .env.example .env
Fill in the required values: 
# Cloudflare account
CLOUDFLARE_ACCOUNT_ID=<your-account-id>

# Cloudflare R2 (from the Cloudflare dashboard > R2 > Manage R2 API tokens)
CLOUDFLARE_R2_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com
CLOUDFLARE_R2_ACCESS_KEY_ID=<r2-access-key-id>
CLOUDFLARE_R2_SECRET_ACCESS_KEY=<r2-secret-access-key>
CLOUDFLARE_R2_BUCKET_NAME=superbox-mcp-registry

# Firebase (from Firebase Console > Project settings > Service accounts)
FIREBASE_PROJECT_ID=<your-project-id>
FIREBASE_PRIVATE_KEY=<your-private-key>
FIREBASE_CLIENT_EMAIL=<your-client-email>

# Cloudflare Worker URL
CLOUDFLARE_WORKER_URL=https://superbox-executor.<your-subdomain>.workers.dev

​
8. Run the backend locally

cd src/superbox/server
go run .
The API will be available at http://localhost:8000.

​
Verification

# Check the Worker is live
curl https://superbox-executor.<your-subdomain>.workers.dev/health

# List servers in R2 via the API
curl http://localhost:8000/api/v1/servers

​
Next steps

Monitoring

Watch live Worker logs

Troubleshooting

Common deployment issues