Quickstart & Operations

This page focuses on how to start qwen serve, how to verify that it is working, and what the internal call chain looks like from qwen serve to the listening server. Architecture, components, and wire protocol details live in the other daemon deep-dive pages.

1. Shortest path

qwen serve

Output:

qwen serve listening on http://127.0.0.1:4170 (mode=http-bridge, workspace=/your/cwd)
qwen serve: bound to workspace "/your/cwd"
qwen serve: trusted loopback mode; local callers have full API access without bearer authentication, including code execution as the daemon user. Use --require-auth with QWEN_SERVER_TOKEN on shared or untrusted hosts.

Open http://127.0.0.1:4170/ in a browser to get the Web Shell UI: chat, session list, and workspace inspection. This token-less loopback primary listener grants local callers full operator API authority, while preserving workspace trust, session ownership, client-id, permission, feature, validation, and resource checks. createServeApp() mounts the bundled Web Shell assets (packages/cli/src/serve/web-shell-static.ts) before bearerAuth, so the shell itself loads without a token; its own API calls carry the bearer when one is configured — start the daemon with --open (which puts the token in the URL fragment, never sent to the server) or append #token=… manually when auth is enabled. --no-web opts out and leaves the daemon API-only.

2. Launch recipes

# 1. Local dev default (loopback, no token)
qwen serve
 
# 2. Explicit workspace + ephemeral port
qwen serve --workspace /path/to/repo --port 0
 
# 3. Hardened loopback development (force bearer even on loopback)
QWEN_SERVER_TOKEN=$(openssl rand -hex 32) qwen serve --require-auth
 
# 4. Expose to LAN (a stable token; without one the daemon generates
#    an ephemeral bearer and prints it once)
QWEN_SERVER_TOKEN=$(openssl rand -hex 32) \
  qwen serve --hostname 0.0.0.0 --port 4170
 
# 4b. Expose to LAN with the generated ephemeral bearer
qwen serve --hostname 0.0.0.0 --port 4170
 
# 5. Tune for many sessions and a larger replay ring
qwen serve --max-sessions 0 --event-ring-size 32000
 
# 6. Multi-client collaboration + strict MCP budget
QWEN_SERVER_TOKEN=secret \
  qwen serve --require-auth \
             --mcp-client-budget 10 \
             --mcp-budget-mode enforce
 
# 7. Start with a consensus policy configured in settings.json
# settings.json: { "policy": { "permissionStrategy": "consensus", "consensusQuorum": 2 } }
qwen serve
 
# 8. Debug logging
QWEN_SERVE_DEBUG=1 qwen serve
 
# 9. Disable the F2 pool (fallback to per-session MCP clients)
QWEN_SERVE_NO_MCP_POOL=1 qwen serve
 
# 10. Allow browser web UI cross-origin access
QWEN_SERVER_TOKEN=secret \
  qwen serve --allow-origin 'http://localhost:3000'
 
# 11. Prompt deadline + SSE idle timeout
qwen serve --prompt-deadline-ms 300000 --writer-idle-timeout-ms 600000
 
# 12. Keep an idle ACP child reusable for at least 60s after work drains
qwen serve --channel-idle-timeout-ms 60000
 
# 13. Enable HTTP rate limiting
QWEN_SERVE_RATE_LIMIT=1 qwen serve

With the hardened loopback recipe (3), /health is registered after bearerAuth, so probes must carry the token like every other API route (the Web Shell static surface stays pre-auth by design; pass --no-web for an API-only daemon).

3. Full startup flags

The CLI is defined in packages/cli/src/commands/serve.ts:

4. Environment variables

Per-handle env overrides are intentional: two daemons running in the same process do not race on process.env. defaultSpawnChannelFactory snapshots env at spawn time.

5. settings.json is also read

Boot calls loadSettings(boundWorkspace) once:

Settings I/O failure, such as malformed JSON, falls back to defaults. InvalidPolicyConfigError is the exception: policy misconfiguration fails boot explicitly.

6. Boot refusal scenarios (explicit failures)

run-qwen-serve.ts intentionally throws instead of falling back in these cases:

A non-loopback bind with NO token source at all is not a refusal: the daemon generates an ephemeral 128-bit bearer (16 random bytes, 22 base64url characters), prints it once at startup, and rotates it on every restart (see the remote quickstart in docs/users/qwen-serve.md). Loopback spellings never generate. The --open-with-auth generator is separate and larger — 32 bytes, a 256-bit bearer — and only runs on loopback.

Every token guard below reads the resolved token, i.e. after that generation step. That is what makes the --require-auth and --allow-origin refusals loopback-only: on a non-loopback bind a generated bearer is already in place.

7. Curl verification checklist

# 1. Liveness
curl http://127.0.0.1:4170/health
# -> {"status":"ok"}
 
# 1.1 Deep health
curl -s 'http://127.0.0.1:4170/health?deep=1' | jq
 
# 2. Capabilities
curl -s http://127.0.0.1:4170/capabilities | jq
 
# 3. Preflight readiness
curl -s http://127.0.0.1:4170/workspace/preflight | jq
 
# 4. Env snapshot (secrets only report presence)
curl -s http://127.0.0.1:4170/workspace/env | jq
 
# 5. MCP pool / budget snapshot
curl -s http://127.0.0.1:4170/workspace/mcp | jq
 
# 6. Create a session
curl -s -X POST http://127.0.0.1:4170/session \
  -H 'Content-Type: application/json' \
  -H 'X-Qwen-Client-Id: curl-debug' \
  -d '{}' | jq
 
# 7. Tail SSE (replace <sid>)
curl -N \
  -H 'Accept: text/event-stream' \
  -H 'X-Qwen-Client-Id: curl-debug' \
  -H 'Last-Event-ID: 0' \
  'http://127.0.0.1:4170/session/<sid>/events'
 
# 8. Web Shell UI
open http://127.0.0.1:4170/

When bearer auth is enabled, add -H "Authorization: Bearer $QWEN_SERVER_TOKEN" to every request. Under the generated-token flow that variable is never set — the daemon prints the bearer once at startup and does not export it — so paste the printed value into your own shell first:

TOKEN='<printed bearer>'
curl -s -H "Authorization: Bearer $TOKEN" http://<bind>:4170/capabilities | jq

8. Is there a browser UI?

Yes — the Web Shell. resolveWebShellDir() finds the built assets (bundled next to the CLI bundle in a release, packages/web-shell/dist in a checkout) and mountWebShellAssets() serves them at /, /assets, and /session/:id document navigations (browser deep links — a plain curl /session/<id> gets the API’s 401/404, not the shell). When the assets are missing the daemon degrades to API-only instead of crashing; --no-web opts out explicitly.

The static shell is mounted before bearerAuth in every launch mode — a browser cannot attach an Authorization header to an address-bar navigation or a <script src> subresource, so gating it would just break the UI. API calls use trusted-loopback authority on the token-less primary listener or attach the configured bearer in authenticated modes. On a non-loopback bind with a token the shell’s same-origin HTTP requests need no allowlist: an Origin equal to the direct socket scheme plus the normalized Host authority is bearer-authenticated and then stripped ahead of the CORS wall, so its POSTs go through. Three cases still need an explicit --allow-origin <origin> — the WebSocket upgrades behind the terminal and voice features; browsers reaching the daemon through a TLS-terminating proxy, whose https origin never matches the plain socket; and any plain-HTTP intermediary that rewrites the Host header (nginx’s default proxy_set_header Host $proxy_host, k8s Ingress), whose forwarded Host then no longer matches the browser’s Origin. Forwarded headers are never trusted to establish same-origin, so the fix is the allowlist entry or a proxy that forwards Host verbatim; port translation alone (docker -p 8080:4170) needs nothing on a non-loopback bind, because only the forwarded Host is compared — on the default loopback bind the Host gate rejects the translated port with 403 Invalid Host header for every request including the shell document, and --allow-origin cannot override it, so forward the same port (ssh -L 4170:localhost:4170) or bind non-loopback.

CSP is built by buildWebShellCsp() and is deliberately looser than a static page’s ('unsafe-inline' for the inline performance.measure patch, eval/wasm/blob workers for shiki and mermaid, data: for katex fonts, connect-src 'self' for SSE). frame-ancestors 'none' plus X-Frame-Options: DENY block clickjacking, except when an extension origin is explicitly allowed via --allow-origin so the UI can be hosted in a Chrome side panel (#5626).

For raw protocol inspection, subscribe to the SSE stream directly (routes/sse-events.ts) — see the curl recipes in section 7.

9. Call chain from qwen serve to the listening server

qwen serve
   |
   v (process)
packages/cli/index.ts              main()
   |
   v
llm.tsx                         main() - parseArguments()
   |
   v (yargs assembly)
config/config.ts                   import { serveCommand } ...
config/config.ts                   .command(serveCommand)
config/config.ts                   await yargsInstance.parse()
   |
   v (handler)
commands/serve.ts                  handler(argv) - boot pre-checks
commands/serve.ts                  const { runQwenServe } = await import('../serve/index.js')   # lazy load
commands/serve.ts                  await runQwenServe({...})
   |
   v
serve/run-qwen-serve.ts              runQwenServe(opts, deps)
   |  |- resolve token (trim / env fallback / non-loopback ephemeral generation)
   |  |- hostname mismatch fallback
   |  |- auth preflight (reads the resolved token)
   |  |- workspace validation + canonicalization
   |  |- MCP budget validation + childEnvOverrides
   |  |- loadSettings + validatePolicyConfig
   |  |- PermissionAuditRing + publisher
   |  |- resolveBridgeFsFactory
   |  `- createHttpAcpBridge({...})
   |
   v
serve/run-qwen-serve.ts              const app = createServeApp(opts, () => actualPort, {...})
   |
   v
serve/server.ts                    createServeApp() - builds Express app (**does not listen**)
   |  |- middleware chain (loopback Origin strip / access log + trace id / Host allowlist / remote same-origin strip / CORS / pre-auth health + shell / webhooks / bearerAuth / rate limit / JSON / telemetry / per-route mutation gate)
   |  |- route mounting (health / web-shell static / capabilities / workspace / session / SSE / ACP HTTP)
   |  `- return app
   |
   v
serve/run-qwen-serve.ts              server = createServer(app) / https.createServer(..., app)
   |  |- lifecycle.bindServer(server, { startupReady, drainHost })
   |  |- server.listen(port, hostname)
   |  |- server.maxConnections = cap
   |  |- actualPort = server.address().port
   |  |- write "qwen serve listening on ..."
   |  |- register SIGINT / SIGTERM (onSignal)
   |  `- resolve(handle: RunHandle)
   |
   v
commands/serve.ts                  await blockForever()    // block forever until signal

Key facts:

• createServeApp only builds; it does not listen. It returns an express() instance with middleware and routes mounted. Ordinary-only embedders may continue to own app.listen(). Embedders that use Live/Conversations must bind the actual Node server to the exported app lifecycle before listening and await that lifecycle during shutdown.
• () => actualPort is a lazy closure. actualPort is assigned in the server.listen callback. The hostAllowlist middleware reads it on demand, so ephemeral ports (--port 0) still gate the Host header correctly.
• await blockForever() is intentional. If yargs.parse() resolves, the CLI top level falls through into the interactive TUI entrypoint (llm.tsx). SIGINT / SIGTERM exit through runQwenServe’s onSignal path.

10. HTTP route file split

The main assembly happens in createServeApp() in server.ts, which wires middleware and mounts focused route modules:

For the complete route and wire protocol reference, see ../qwen-serve-protocol.md. For architecture, see 01-architecture.md.

11. Graceful vs hard shutdown

• First SIGINT / SIGTERM -> runQwenServe onSignal -> two-phase graceful shutdown:
  1. bridge.shutdown(): each channel gets KILL_HARD_DEADLINE_MS (10s), then channel.kill().
  2. server.close(): in-flight requests drain, SHUTDOWN_FORCE_CLOSE_MS (5s) triggers closeAllConnections(), then a second 2s deadline applies.
• Second SIGINT / SIGTERM while already exiting -> bridge.killAllSync() synchronously SIGKILLs all ACP children and calls process.exit(1) to avoid orphan processes.

RunHandle.close() returned by runQwenServe is the programmatic equivalent used by repository-internal hosts and tests.

12. Embedding boundary

runQwenServe, createServeApp, and their lifecycle helpers are internal implementation APIs; the published @qwen-code/qwen-code package does not export a ./serve subpath. External integrations should start qwen serve --no-web and use the documented HTTP/SSE protocol or @qwen-code/sdk. Repository code and tests may import the source modules directly, but those imports are not a supported integration contract.

For repository-internal callers of createServeApp, the default fsFactory.trusted = false. Agent-side ACP writeTextFile is rejected as untrusted_workspace, and a stderr warning is printed once. Either inject deps.fsFactory with explicit trust, inject deps.bridge, or accept the trust-gated default behavior.

13. Debugging recipes

See the debugging section in 19-observability.md. The common commands are:

# Is the daemon alive?
curl http://127.0.0.1:4170/health
 
# Which capabilities are advertised?
curl -s http://127.0.0.1:4170/capabilities | jq
 
# Daemon-host readiness
curl -s http://127.0.0.1:4170/workspace/preflight | jq
 
# Tail live SSE
curl -N -H 'Accept: text/event-stream' \
     -H 'Last-Event-ID: 0' \
     'http://127.0.0.1:4170/session/<sid>/events'
 
# Verbose logs
QWEN_SERVE_DEBUG=1 qwen serve

References

• CLI entry: packages/cli/src/commands/serve.ts
• Bootstrap: packages/cli/src/serve/run-qwen-serve.ts
• Express factory: packages/cli/src/serve/server.ts
• Middleware: packages/cli/src/serve/auth.ts
• Bridge factory: packages/acp-bridge/src/bridge.ts
• Web Shell static mount: packages/cli/src/serve/web-shell-static.ts
• User docs: ../../users/qwen-serve.md
• Wire protocol: ../qwen-serve-protocol.md