BlackBull Deploy Gateway

Deploy lightweight websites and Workers to Cloudflare through a scoped gateway — without ever handling BlackBull's real Cloudflare credentials.

1. Configure your Codex / Claude project

Point your tooling at the gateway instead of the Cloudflare API. Two things to set:

Store the token as an environment variable in your project — never commit it:

# .env  (git-ignored)
BLACKBULL_DEPLOY_URL=https://deploy.blackbull.technology/cf
BLACKBULL_PROJECT_TOKEN=bbp_xxxxxxxxxxxxxxxxxxxx

Every path below is relative to the base URL and maps to the Cloudflare API under BlackBull's account. You never see the account ID or the real token.

2. Deploy / update a Worker

Your worker name must start with your allowed prefix (e.g. prefix mktg- → mktg-site). Upload the standard Workers multipart bundle:

curl -X PUT "$BLACKBULL_DEPLOY_URL/workers/scripts/mktg-site" \
  -H "Authorization: Bearer $BLACKBULL_PROJECT_TOKEN" \
  -F 'metadata={"main_module":"worker.js","compatibility_date":"2025-01-01"};type=application/json' \
  -F 'worker.js=@worker.js;type=application/javascript+module'

Enable a *.workers.dev URL for it:

curl -X POST "$BLACKBULL_DEPLOY_URL/workers/scripts/mktg-site/subdomain" \
  -H "Authorization: Bearer $BLACKBULL_PROJECT_TOKEN" \
  -H "content-type: application/json" -d '{"enabled":true}'

3. Deploy a static site (Worker Assets)

For a few files, the simplest reliable path is to embed the HTML in a module worker (section 2). For a folder of files, use Worker static assets — a three-step flow (asset bytes stream straight through the gateway and are never stored here):

# 1) start a session (returns a jwt + which file hashes to send)
curl -X POST "$BLACKBULL_DEPLOY_URL/workers/scripts/mktg-site/assets-upload-session" \
  -H "Authorization: Bearer $BLACKBULL_PROJECT_TOKEN" -H "content-type: application/json" \
  -d '{"manifest":{"/index.html":{"hash":"","size":1234}}}'

# 2) upload the files. This step is authed by the SESSION JWT, passed in X-Assets-Jwt
#    (Authorization still carries your project token):
curl -X POST "$BLACKBULL_DEPLOY_URL/workers/assets/upload?base64=true" \
  -H "Authorization: Bearer $BLACKBULL_PROJECT_TOKEN" \
  -H "X-Assets-Jwt: <jwt from step 1>" \
  -F '<hash>=<base64 of file>;type=text/html'   # -> returns a completion jwt

# 3) PUT the script with the assets manifest attached
#    metadata.assets = {"jwt":"<completion jwt>","config":{"html_handling":"auto-trailing-slash"}}

Don't point the wrangler CLI at this gateway — it calls account endpoints that aren't proxied and needs the hidden account ID. Use these REST endpoints directly (any HTTP client works). Full step-by-step for agents is in /llms.txt.

4. Create & use a D1 database

Your D1 database name must start with your prefix. On create, the gateway auto-registers it to your project so you can query it afterwards:

# create
curl -X POST "$BLACKBULL_DEPLOY_URL/d1/database" \
  -H "Authorization: Bearer $BLACKBULL_PROJECT_TOKEN" \
  -H "content-type: application/json" -d '{"name":"mktg-app-db"}'

# list YOUR databases
curl "$BLACKBULL_DEPLOY_URL/d1/database" -H "Authorization: Bearer $BLACKBULL_PROJECT_TOKEN"

# run SQL (use the uuid returned on create)
curl -X POST "$BLACKBULL_DEPLOY_URL/d1/database/<uuid>/query" \
  -H "Authorization: Bearer $BLACKBULL_PROJECT_TOKEN" \
  -H "content-type: application/json" \
  -d '{"sql":"CREATE TABLE IF NOT EXISTS visits(id INTEGER PRIMARY KEY, ts INTEGER);"}'

5. Set Worker secrets

curl -X PUT "$BLACKBULL_DEPLOY_URL/workers/scripts/mktg-site/secrets" \
  -H "Authorization: Bearer $BLACKBULL_PROJECT_TOKEN" \
  -H "content-type: application/json" \
  -d '{"name":"API_KEY","text":"s3cret","type":"secret_text"}'

6. Attach your own custom domain

Bring a domain you own (kept at any DNS provider). Deploy the worker first, then claim the hostname (service is required and must be one of your workers). Ask the gateway for the records to add, then add them at your DNS host — the gateway returns a CNAME plus validation records:

# request records (service = which of your workers it points to)
curl -X POST "$BLACKBULL_DEPLOY_URL/hostnames" \
  -H "Authorization: Bearer $BLACKBULL_PROJECT_TOKEN" \
  -H "content-type: application/json" \
  -d '{"hostname":"promo.acme.com","service":"mktg-site"}'
# -> { result: { hostname, status, records:[ {type,name,value,purpose}, ... ] } }

# check status later (pending -> active once your records propagate)
curl "$BLACKBULL_DEPLOY_URL/hostnames/promo.acme.com" -H "Authorization: Bearer $BLACKBULL_PROJECT_TOKEN"

# list all your domains
curl "$BLACKBULL_DEPLOY_URL/hostnames" -H "Authorization: Bearer $BLACKBULL_PROJECT_TOKEN"

The response's records and dns fields tell you exactly what to add: a CNAME for a subdomain, or A/AAAA records for a root/apex domain (most registrars can't CNAME an apex) — add one or the other, plus any TXT validation records.

Prefer a UI? Open /status, paste your project token, and add domains / copy records / watch status there — no login needed. Your token stays in your browser tab.

Not sure of your prefix or settings? GET $BLACKBULL_DEPLOY_URL/whoami returns your project name, worker prefix, and whether custom domains are enabled.

What you can and cannot do

Every action is audit-logged (project, action, target, status, timestamp). If a call returns 403 gateway: …, it was blocked by policy. Ask an admin if you need your prefix or domain suffix changed.

Health

/health returns gateway status JSON.