SuperQwen docs

SuperQwen has two parts: the web console (apps/web) and the control-plane API (services/api). By default the console runs against an in-browser mock runtime, so you can try it without a model or backend. Set NEXT_PUBLIC_API_URL to drive the real API instead.

1 · Run the console

cd apps/web
npm install
npm run dev          # http://localhost:3000

2 · Run the API

cd services/api
uv sync
uv run fastapi dev   # http://127.0.0.1:8000/docs

3 · Connect the console to the API

# terminal 1 — the fake adapter plays a scripted agent
cd services/api
SUPERQWEN_MODEL_ADAPTER=fake SUPERQWEN_FAKE_LATENCY_MS=600 uv run fastapi dev

# terminal 2
cd apps/web
NEXT_PUBLIC_API_URL=http://127.0.0.1:8000 npm run dev

The sidebar shows api instead of mock when connected. Tasks, workspaces, models and tools then come from the API, and an open task follows its event stream live.

4 · Point it at a self-hosted model

ollama pull qwen2.5-coder:7b
SUPERQWEN_MODEL_ENDPOINT=http://localhost:11434/v1 \
SUPERQWEN_MODEL_NAME=qwen2.5-coder:7b \
uv run fastapi dev

A task is one goal in one workspace. It carries an owner, an execution mode, a budget, success criteria, a plan, an event timeline, approvals, artifacts and a final report. Its status follows an explicit state machine:

succeeded is only reachable after validation passes. A failed task marked recoverable can be resumed from its persisted state.

A workspace is a registered repository plus its configuration: branch, test command, lint command, policy and sandbox limits. Today the agent inspects the workspace checkout read-only; from Sprint 3 each task runs in an isolated copy, so changes never reach the primary branch until you apply the diff yourself. See the live list on Workspaces.

Every task has four hard limits. Reaching any of them stops the task with a partial report and marks it resumable; resuming extends each exhausted limit (steps +4, tool calls +10, wall minutes +10, retries +2) and continues from the persisted state.

The model only proposes tool calls. The policy engine decides, per tool and per mode, whether a call is allowed, needs approval or is denied.

Each approval is bound to a hash of its exact parameters. When you approve, the client sends back the hash you reviewed; if the agent later changes the parameters (for example, a revised patch), a new approval is required. In supervised mode the agent also asks you to approve its plan (plan.execute) before anything runs; the approval is bound to that exact plan.

{
  "approvalId": "b2d7a1c4-…",
  "paramsHash": "9b3dcd11…"
}

Every tool is registered with an input schema, a category, a timeout and a per-mode policy. Expand schemas on the Tools page.

All routes live under /api/v1 and enforce owner and workspace authorization. A task you can't see returns 404, exactly like one that doesn't exist.

Create a task

curl -X POST http://127.0.0.1:8000/api/v1/tasks \
  -H "Authorization: Bearer dev:you" \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "Fix the failing test_invoice_rounding test",
    "workspaceId": "ws-billing",
    "modelProfileId": "qwen-coder-7b-local",
    "mode": "supervised",
    "budget": { "maxSteps": 12, "maxToolCalls": 40, "maxWallMinutes": 20, "maxRetries": 3 },
    "successCriteria": ["test_invoice_rounding passes"]
  }'

Errors: 401 unauthenticated · 404 not found or not visible · 409 illegal transition, already decided, or hash mismatch · 422 validation.

GET /tasks/{id}/events replays the task timeline as server-sent events, then follows it live until the task is terminal. It sends three frame types: task_event (one timeline event; its SSE id is a sequence number), task (a snapshot of the task without events, whenever it changes) and a final end. Reconnect with Last-Event-ID to resume without gaps. A tool run emits two tool events (started, finished) with the same execution.id; keep the latest. Each event has an id, an at timestamp and a kind:

The API reads environment variables prefixed with SUPERQWEN_, or a services/api/.env file.

The console reads two build-time variables: