GUI API¶

Not part of the hosted product

G6 is hosted: you reach it over MCP by pointing Claude Code (or any MCP client) at the server. There is no desktop app to install and no self-hosted deployment. This page documents a surface that exists in the repository but is not part of the hosted product today — it is kept as engineering reference, not as instructions for customers.

The GUI API is a local FastAPI sidecar that powers the desktop GUI workbench. It provides run management, HITL approvals, artifact inspection, chat, and learning layer access over HTTP.

Overview¶

# Launch the GUI API sidecar (shipped desktop binary)
g6 --gui-api --host 127.0.0.1 --port 8001

In a development source checkout, the same server is available as a module:

python -m mvp.gui_api

The API binds to localhost only by default (port 8001). It is not a public-facing service — it serves the local browser GUI and is started automatically when you run g6 --gui.

Authentication¶

All requests (except OPTIONS and GET /) require an X-G6-GUI-Token header.

Aspect	Detail
Header	`X-G6-GUI-Token`
Token source	Auto-generated via `secrets.token_urlsafe(32)` on launch, or set via `G6_GUI_AUTH_TOKEN` env var
Comparison	Constant-time (`secrets.compare_digest`)
Exempt routes	`OPTIONS` (CORS preflight), `GET /` (health check)

The desktop launcher passes the token to the GUI frontend via URL query parameter. The frontend persists it to localStorage for subsequent requests.

Endpoints¶

Health & System¶

Method	Path	Response Model	Description
`GET`	`/`	`HealthResponse`	Health check — version, available backends
`GET`	`/backends`	`list[AIBackend]`	List available AI backends (local-summary, codex-cli)
`GET`	`/system/status`	`SystemStatusResponse`	App, license, update, and model status
`GET`	`/system/diagnostics`	`SystemDiagnosticsResponse`	Recent logs, log directory, diagnostic text
`POST`	`/system/open-logs`	`OpenLogsResponse`	Open log folder in OS file manager
`GET`	`/system/update-check`	`UpdateCheckResponse`	Check for new versions with signature verification
`POST`	`/system/activate-license`	`ActivateLicenseResponse`	Activate license via API key + passphrase
`POST`	`/system/openrouter-key`	`ConfigureOpenRouterResponse`	Save or clear the local OpenRouter API key

Run Management¶

Method	Path	Response Model	Description
`GET`	`/runs`	`list[RunSummary]`	List discovered runs (optional `root_path` query)
`GET`	`/runs/current`	`RunSummary`	Get the currently active run
`GET`	`/runs/{run_id}`	`RunSummary`	Get a specific run by ID
`POST`	`/runs`	`CreateRunResponse`	Create a new run (goal, constraints, workspace)
`POST`	`/runs/{run_id}/start`	`CreateRunResponse`	Start a queued run in background worker
`POST`	`/runs/{run_id}/stop`	`CreateRunResponse`	Request a running run to stop

HITL Decisions¶

Method	Path	Response Model	Description
`GET`	`/runs/{run_id}/hitl`	`list[HITLTaskSummary]`	List pending HITL tasks (optional `include_completed`)
`POST`	`/runs/{run_id}/hitl/{task_id}`	`CompleteHITLResponse`	Approve or reject a HITL task

Data & Search¶

Method	Path	Response Model	Description
`POST`	`/load-data`	`dict`	Load reasoning chain from three artifact paths
`POST`	`/load-from-directory`	`LoadDirectoryResponse`	Load all artifacts from a run directory
`GET`	`/data-summary`	`dict`	Summary of loaded reasoning chain
`GET`	`/full-data`	`dict`	Complete reasoning chain data
`GET`	`/search`	`dict`	TF-IDF search over loaded reasoning chain
`GET`	`/source-text`	`dict`	Get raw text for a specific artifact field

Chat¶

Method	Path	Response Model	Description
`POST`	`/chat`	`ChatResponse`	Send a message, get AI response with source citations
`GET`	`/conversation/{id}`	`dict`	Retrieve conversation history
`DELETE`	`/conversation/{id}`	`dict`	Clear a conversation

Learning Layer¶

Method	Path	Response Model	Description
`GET`	`/learning/status`	`dict`	Learning layer status
`GET`	`/learning/theories`	`dict`	List extracted theories (optional `status_filter`)
`GET`	`/learning/artifacts/{run_id}`	`dict`	Get learning artifacts for a run
`POST`	`/learning/build-dataset`	`dict`	Build training dataset from source path
`POST`	`/learning/train`	`dict`	Train model on dataset (strategy: T0-T3)
`POST`	`/learning/evaluate`	`dict`	Evaluate trained model
`POST`	`/learning/export`	`dict`	Export learning harness to path
`POST`	`/learning/import`	`dict`	Import learning harness from bundle

Key request models¶

CreateRunRequest¶

{
  "goal": "Analyse quarterly sales data",
  "user_context": "We have CSV exports from Salesforce",
  "constraints": "Budget under $50",
  "workspace_name": "sales-q1",
  "workspace_base_dir": null,
  "recursion_depth": 3,
  "breadth": 3,
  "priority": "normal"
}

CompleteHITLRequest¶

{
  "approved": true,
  "comment": "Looks correct, proceed",
  "human_prediction": "",
  "human_confidence": 0.0,
  "override_reason": ""
}

ChatRequest¶

{
  "message": "What was the original objective?",
  "backend_id": "local-summary",
  "conversation_id": null
}

ConfigureOpenRouterRequest¶

{
  "api_key": "sk-or-..."
}

Send an empty string to clear the saved key. Non-empty keys must start with sk-or-.

Successful responses include the persisted local path and never echo the secret:

{
  "status": "success",
  "message": "OpenRouter key saved.",
  "configured": true,
  "config_path": "C:\\Users\\you\\.g6\\.env"
}

Security¶

Control	Detail
Bind address	`127.0.0.1` (loopback only)
Non-loopback	Requires `G6_GUI_API_ALLOW_NON_LOOPBACK=1`
CORS	Regex-matched to `http://(localhost\\|127.0.0.1):\d+`
Path validation	Input paths validated against traversal attacks

Environment variables¶

Variable	Default	Description
`G6_GUI_AUTH_TOKEN`	(auto-generated)	Session authentication token
`G6_GUI_API_HOST`	`127.0.0.1`	API bind address
`G6_GUI_API_PORT`	`8001`	API bind port
`G6_GUI_API_ALLOW_NON_LOOPBACK`	(unset)	Set to `1` to allow non-localhost access
`OPENROUTER_API_KEY`	(unset)	OpenRouter key; the API can also load and update this in `~/.g6/.env`

Source files¶

File	Purpose
`bases/mvp/gui_api/app.py`	FastAPI app factory, all route handlers, request/response models
`bases/mvp/gui_api/rag_service.py`	`ReasoningChainService` — artifact loading, TF-IDF search, chat backends, run management
`bases/mvp/gui_api/__main__.py`	Uvicorn entry point