Skip to main content
The callback server is a FastAPI application that receives HTTP callbacks from AI agents that execute hidden payloads.

​
Default Configuration

SettingDefaultDescription
Host127.0.0.1Network interface to bind to
Port8080TCP port to listen on
Notify URLhttp://127.0.0.1:8899Main qai web server for hit notifications
The database directory (~/.qai/) is created automatically on first run.

​
CLI Configuration

All server settings are configured via CLI flags on qai ipi listen: 
# Default — localhost only
qai ipi listen

# Alternate loopback port
qai ipi listen --port 9090

# Remote callbacks: keep bind on loopback and use a tunnel
qai ipi listen --tunnel cloudflare
OptionTypeDefaultDescription
--host, -hTEXT127.0.0.1Loopback interface only (127.0.0.1, localhost, ::1)
--port, -pINT8080TCP port to listen on
--notify-urlTEXThttp://127.0.0.1:8899Where to send internal hit notifications

​
Callback URL Structure

The listener accepts callbacks at two URL patterns:
PathToken ValidatedDescription
/c/<uuid>/<token>YesAuthenticated callback — token checked against database
/c/<uuid>NoUnauthenticated callback — recorded with token_valid=False
Both GET and POST methods are accepted. POST bodies are captured for exfil payload types. All callback endpoints return a fake 404 response to avoid alerting the target system.

​
Per-Campaign Authentication

Cryptographic tokens are generated automatically when payloads are created. No separate authentication configuration is needed. The token is embedded in the callback URL during payload generation: 
qai ipi generate --callback http://localhost:8080
# Generates URLs like: http://localhost:8080/c/a1b2c3d4-.../e5f6g7h8...

​
Confidence Scoring

Confidence is assigned automatically based on token validity and User-Agent analysis:
LevelCriteria
HIGHValid campaign token present
MEDIUMNo/invalid token + programmatic User-Agent
LOWNo/invalid token + browser/scanner User-Agent
Confidence thresholds are not user-configurable. The programmatic User-Agent pattern matches: python-requests, httpx, aiohttp, urllib, curl, wget, node-fetch, axios, got, undici, fetch, llm, openai, langchain.

​
Bridge Token

The IPI listener runs as a separate process from the main qai web server. When a hit arrives, the listener notifies the web server via an internal HTTP POST so the web UI can update in real time via WebSocket. This internal communication is authenticated with a shared bridge token:
  • Location: ~/.qai/bridge.token
  • Format: 32 hex characters, generated via secrets.token_hex(16)
  • File permissions: 0600 on POSIX
  • Auto-generated: On first access by either process (race-safe exclusive file creation)
Both processes read from the same file — no manual configuration needed. The listener includes the token in the Authorization header of its internal POST. If the tokens don’t match (stale file), the notification is rejected — the hit is still recorded in the database but won’t appear in the web UI until the page is refreshed.
If WebSocket hit notifications stop working, delete ~/.qai/bridge.token and restart both the web server and the listener. A fresh token will be generated automatically.

​
Health Check

The server exposes a health endpoint at /health that returns {"status": "ok"}.

​
Public exposure and tunnel mode

When the listener runs with --tunnel cloudflare (see Remote callbacks via Cloudflare Tunnel), a few behaviors differ from a bare loopback listener. Forwarded-header trust. In tunnel mode the server resolves each hit’s source_ip from the CF-Connecting-IP header rather than the TCP peer. This trust is scoped to tunnel mode only — a bare loopback listener does not trust forwarded headers. Hardening in tunnel mode. Tunneled listeners activate defensive measures against public-internet exposure: request body size limits, per-peer rate limiting, and a startup warning banner. These are defaults for tunnel mode and cannot be silently disabled. State file permissions. The ~/.qai/active-callback state file is created with mode 0o600 on POSIX (owner read/write only). Windows has no direct equivalent; on Windows the file is protected only by the default user profile ACL. This is best-effort and is called out here as an explicit known limitation, not a hardening claim.

​
Network Considerations

The callback listener (qai ipi listen) is separate from the qai Web UI. Only the callback listener should be exposed to external networks. The Web UI must bind to 127.0.0.1 (localhost) only unless you have configured proper authentication. Do not forward or publish the Web UI host/port via ngrok, Cloudflare Tunnel, or public IPs — doing so exposes an unauthenticated management interface.
For testing against cloud-hosted AI targets, keep the listener on loopback and expose it via tunnel:
  • Local testing: http://127.0.0.1:8080 when the agent runs on the same machine
  • Cloud targets: qai ipi listen --tunnel cloudflare and use the printed HTTPS URL as --callback
# Start the listener with a Cloudflare Quick Tunnel
qai ipi listen --tunnel cloudflare

# Use the printed tunnel URL when generating payloads
qai ipi generate --callback https://<tunnel-host>