Host your own bassh instance

Overview

As an operator, you host the bassh infrastructure on your Cloudflare account. Your users can deploy static sites without needing their own Cloudflare accounts—they just need an invite code from you.

What you'll set up:

• Cloudflare Worker — Handles API requests, user registration, and deployments
• KV Namespaces — Store user data and form submissions
• API Token — Grants the Worker permission to create Pages projects

What your users get:

• Deploy static sites with a single command
• Password protection, email access controls, magic links
• Form submissions without a backend
• Custom domains with automatic SSL

Quick Setup

The fastest way to get started. Clone the repo and run the setup script.

# Clone to home directory (required for deploy alias)
git clone https://github.com/get-bassh/bassh.git ~/bassh
cd ~/bassh

# Run the setup script
./setup.sh

The script will:

1. Authenticate with Cloudflare (opens browser if needed)
2. Create KV namespaces for users and forms
3. Generate wrangler.toml configuration
4. Prompt for your API token
5. Configure registration mode (invite-only or open)
6. Deploy the Worker
7. Display your invite code to share with users

Manual Setup

If you prefer to understand each step or need custom configuration, follow these steps.

1Install Wrangler

Wrangler is Cloudflare's CLI for managing Workers.

npm install -g wrangler
wrangler login

This opens your browser to authenticate with Cloudflare.

2Clone the Repository

git clone https://github.com/get-bassh/bassh.git ~/bassh
cd ~/bassh

3Create KV Namespaces

bassh uses two KV namespaces to store user data and form submissions.

npx wrangler kv namespace create USERS
Created namespace "bassh-api-USERS" with id "abc123..."

npx wrangler kv namespace create FORMS
Created namespace "bassh-api-FORMS" with id "def456..."

Save these IDs—you'll need them for the configuration file.

4Create API Token

The Worker needs an API token to create Pages projects and Access policies.

1. Go to Cloudflare API Tokens
2. Click Create Token
3. Select Create Custom Token
4. Add these permissions:

5. Set Account Resources to include your account
6. Set Zone Resources to include all zones
7. Click Continue to summary → Create Token
8. Copy the token immediately (you won't see it again)

5Configure wrangler.toml

Update wrangler.toml with your KV namespace IDs:

name = "bassh-api"
main = "src/index.ts"
compatibility_date = "2024-01-01"

[[kv_namespaces]]
binding = "USERS"
id = "your-users-namespace-id"

[[kv_namespaces]]
binding = "FORMS"
id = "your-forms-namespace-id"

6Set Secrets

Configure the required secrets for your Worker:

# Required: Your Cloudflare Account ID
npx wrangler secret put CF_ACCOUNT_ID
> Enter value: your-32-char-account-id

# Required: API Token from Step 4
npx wrangler secret put CF_API_TOKEN
> Enter value: your-api-token

# Optional: Enable invite-only registration
npx wrangler secret put REGISTRATION_CODE
> Enter value: your-secret-invite-code

Find your Account ID with:

npx wrangler whoami

7Deploy

npx wrangler deploy
Deployed bassh-api to https://bassh-api.your-subdomain.workers.dev

Add a convenience alias to your shell config (~/.zshrc or ~/.bashrc):

alias bassh-deploy="npx wrangler deploy --config ~/bassh/wrangler.toml"

Managing Invite Codes

Control who can register on your bassh instance.

Invite-only mode (recommended)

When you set REGISTRATION_CODE, users need an invite to register:

# Your invite code format: subdomain:secret
your-subdomain:your-secret-code

# Users register with
bassh register alice --invite your-subdomain:your-secret-code

Open registration

Without REGISTRATION_CODE, anyone with your Worker URL can register:

# Users set the API endpoint
export BASSH_API=https://bassh-api.your-subdomain.workers.dev

# Then register without invite
bassh register alice

Rotating invite codes

To change the invite code, update the secret:

npx wrangler secret put REGISTRATION_CODE
> Enter value: new-secret-code

Existing users are unaffected—only new registrations need the new code.

Email Magic Links

Enable the -o flag for email-based site protection with magic links.

Setup with Resend

1. Create a Resend account
2. Add and verify your domain
3. Add the required DNS records (SPF, DKIM)
4. Generate an API key
5. Set the secrets:

npx wrangler secret put RESEND_API_KEY
> Enter value: re_abc123...

npx wrangler secret put EMAIL_FROM
> Enter value: access@yourdomain.com

Your users can now protect sites with magic links:

bassh ./dist -o "alice@company.com,@trusted.com"

Custom Workers Subdomain

Choose a memorable subdomain for your Worker URL.

1. Go to Cloudflare Dashboard → Workers & Pages
2. Click on your account subdomain settings
3. Change to something memorable (e.g., myteam)
4. Redeploy your Worker

Your Worker URL will be: https://bassh-api.myteam.workers.dev

Secrets Reference

Troubleshooting

Deployment fails

Check that your API token has all required permissions. Re-create the token if needed.

Users can't register

• Verify REGISTRATION_CODE is set correctly
• Check the invite code format: subdomain:secret
• Ensure the subdomain matches your workers.dev subdomain

Magic links not sending

• Verify Resend domain is fully verified (check DNS records)
• Ensure EMAIL_FROM uses the verified domain
• Check Resend dashboard for sending errors

KV errors

• Verify namespace IDs in wrangler.toml match what you created
• Ensure API token has Workers KV Storage Edit permission