Quick start

This page does one thing: run OctaFuse on the recommended Cloudflare path and open Admin. Individuals and light traffic can usually deploy and run within the Workers / D1 free tier.

For providers, routes, and keys, follow the User guide. Prefer not to use Cloudflare? See Docker deployment.

Repository

Run commands from the octafuse-gateway repository root.

1. Run locally (local D1)

Prerequisites

• Node.js 20+, npm.
• No Cloudflare account required.

Clone and start

git clone https://github.com/OctaFuse/octafuse-gateway.git
cd octafuse-gateway
npm install
npm run db:migrate
npm run dev:proxy

In a second terminal:

npm run dev:admin

Service	URL / location
Proxy	http://127.0.0.1:8787
Admin	http://127.0.0.1:8789
Console login	admin / admin (local default; first dev:admin auto-creates packages/admin/.dev.vars)
Local D1	./.wrangler/state
Admin API Bearer	sk-dev-admin-key (management API, not the console password)

Health check:

curl -sS http://127.0.0.1:8787/health

2. Deploy to Cloudflare

Requirements: a Cloudflare account and npx wrangler login.

npx wrangler login
npm run bootstrap:cloudflare

Follow the CLI for GATEWAY_URL / GATEWAY_MASTER_URL, then verify with GET $GATEWAY_URL/health. Full steps and releases: Cloudflare Workers deployment.

Sign in to Admin

1. Locally open http://127.0.0.1:8789 (use your Admin URL after cloud deploy).
2. Local defaults: admin / admin (local only; edit packages/admin/.dev.vars to change). After bootstrap, use the ADMIN_PASSWORD you set. Docker one-shot local defaults are admin / changeme—see Docker deployment.

After signing in, Dashboard shows API keys, accounts, requests, tokens, cost, latency, and recent errors.

Recommended next steps (user guide order)

1. Providers — wire upstream vendors
2. Models — catalog model ids the gateway understands
3. Routing — map client model strings to upstreams
4. Users and API keys — who can call and with what budget

Optional: one inference smoke test

After Provider + route + API key exist in Admin, replace the key and model below:

curl -sS http://127.0.0.1:8787/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"your-route-model","messages":[{"role":"user","content":"Hello"}]}'

After cloud deploy, use your Proxy URL as the host.

Not using Cloudflare?

Docker / Postgres / MySQL self-hosting: Docker deployment. More local stacks (Node + SQL, smoke tests): GitHub · local development.