Worker bindings

Worker bindings

Abstract

Bindings and vars for the AXIS Worker are declared in worker/wrangler.toml (copy from wrangler.toml.example via axis setup worker). Many production bindings ship commented so clone-and-dev does not require Cloudflare® resources; wrangler dev synthesizes local substitutes where possible.

Worker script name: name = "worker-axis". Canonical host worker.axis.hoox.sh. Pages project is axis; canonical Pages host is axis.hoox.sh.

Conceptual model

Rendering…

Interface surface — Env

From src/index.ts:

interface Env {
  API_KEYS?: KVNamespace;
  USAGE?: KVNamespace;
  DB?: D1Database;
  BUNDLES?: R2Bucket;
  SESSIONS?: DurableObjectNamespace;

  EXTERNAL_BACKEND?: string;
  ALLOWED_ORIGIN?: string;
  ADMIN_TOKEN?: string;
  PYODIDE_IN_WORKER?: string;
  ALLOW_OPEN_KEYS?: string;
  REQUIRE_RUN_AUTH?: string;
  GITHUB_OAUTH_CLIENT_ID?: string;
  GITLAB_OAUTH_CLIENT_ID?: string;
}

Vars ([vars])

Prefer secrets for ADMIN_TOKEN and production backends:

# CLI-first
axis secret put ADMIN_TOKEN
axis secret put EXTERNAL_BACKEND
# or: wrangler secret put …

Prod invariant: if DB (D1) is bound, also bind API_KEYS KV — otherwise script routes fail closed with API_KEYS_REQUIRED.

Provision recipes

KV

wrangler kv namespace create API_KEYS
wrangler kv namespace create USAGE
# paste ids into wrangler.toml [[kv_namespaces]]

D1

wrangler d1 create pynescript
# [[d1_databases]] binding = "DB"  (name MUST be DB)
wrangler d1 execute pynescript --remote --file=schemas/scripts.sql

Repo may already contain a database_id for the project’s D1 — treat IDs as environment-specific when forking.

R2 (optional)

wrangler r2 bucket create indicator-bundles
# binding BUNDLES

Durable Objects

Uncomment bindings + migrations in wrangler.toml, then:

wrangler deploy

Class: SessionDO exported from src/index.ts.

Other wrangler settings

Static PWA assets are not served by this Worker in the documented split: Pages serves dist/ at https://axis.hoox.sh, Worker serves API/WS. Project name for Pages deploy is axis.

Deploy commands

cd frontend/worker
wrangler deploy

# Pages (from frontend/)
bun run build
wrangler pages deploy dist --project-name=axis
# or npm run deploy:pages from worker package

Makefile: make worker-deploy, make pages-deploy (note: some Makefile targets still point at legacy tree — prefer dist/ from Vite build; see build and serve).

Invariants & edge cases

1. Do not rename CF project without migrating all binding IDs, custom domains, and CI.
2. Local wrangler auto-provisions mock KV/D1; production needs real IDs.
3. EXTERNAL_BACKEND=localhost on CF cannot reach your laptop — use a public tunnel or co-located VPS.
4. Health reports which optional bindings are present.

Failure modes

See also

• Cloudflare DevOps
• Runtime
• CORS