Quick start

This page does one thing: run OctaFuse on your machine and open Admin. For “how to configure providers, routes, keys”, follow the User guide sections. Production or staging is not covered here—see links at the bottom.

Option A: Docker (fastest path)

Prerequisites

Docker Compose v2.20+ (needs service_completed_successfully).
Network access to GitHub (or your fork).

Clone and start

git clone https://github.com/OctaFuse/octafuse-gateway.git
cd octafuse-gateway
docker compose -f docker/compose/quickstart.yml up --build

When containers are ready, in another terminal:

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

Healthy JSON means Proxy is listening at http://localhost:8787.

Open http://localhost:8789 (Admin) in a browser.
Sign in with admin / changeme (local only—change everywhere else).

Recommended next steps (user guide order)

Providers — wire upstream vendors
Models — catalog model ids the gateway understands
Routing — map client model strings to upstreams
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://localhost: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"}]}'

Option B: Cloudflare (local D1)

Skip Docker—or match the Worker + D1 production stack—by running Wrangler locally. State persists under ./.wrangler/state.

Prerequisites: Node.js 20+, npm.

git clone https://github.com/OctaFuse/octafuse-gateway.git
cd octafuse-gateway
npm install
npm run db:migrate          # local D1 migrations
npm run dev:proxy           # Proxy → http://127.0.0.1:8787

In a second terminal:

npm run dev:admin           # Admin preview → http://127.0.0.1:8789

Admin API Bearer must match D1 system_config.MASTER_KEY (dev seed in packages/core/migrations-d1/0002_seed.sql).

More local setups (Node + Postgres/MySQL, multiple D1 dirs, smoke tests): GitHub · local-testing-environments.