Config Web Management API

Config Web is the config-web subcommand of the Go Agent binary. Config Web and the Agent runtime listen on ports 80 and 8080 respectively, and each owns its own PID and service lifecycle. Config Web calls the Agent's loopback-only reload endpoint after configuration is saved, while the Agent reads Config Web's storage-state mirror for archive lookup. Config Web does not proxy Agent chat, session, or Phone Bridge traffic.

Resource Endpoints

All public endpoints use the /api root without an additional version prefix:

Resource	Method and path	Description
Configuration	GET /api/config	Read the resolved agent.toml configuration
Configuration	PATCH /api/config	Apply the merge patch { "config": { ... } }
Configuration	GET /api/config/schema	Read field types, defaults, choices, secret markers, and restart hints
Configuration	PUT /api/config/locale	Update the page language
Configuration	POST /api/config/test	Validate configuration and the device environment without saving
Models	GET /api/models?provider=...&locale=...	Return the localized model catalog
STT test	POST /api/config-test/stt/start	Start a microphone recording test using the submitted unsaved settings
STT test	POST /api/config-test/stt/stop	Stop recording and return the transcription result
Storage	GET /api/storage/status	Read SD/eMMC state and formatting tasks
Storage	POST /api/storage/format	Format the SD card asynchronously
Storage	POST /api/storage/eject	Sync and safely eject the SD card
Device	GET /api/device/snapshot	Read the aggregated initial-page model: configuration, Wi-Fi, device, firmware, and storage summaries
Device	GET /api/device/status	Read the device, firmware, Agent process, USB/HID, and capability summary
Device	POST /api/device/reboot	Reboot the device
Device	POST /api/device/usb/reenumerate	Re-enumerate USB HID/ECM
Network	POST /api/network/wifi/scan	Scan for nearby Wi-Fi networks
Network	PUT /api/network/wifi/connection	Start a bounded asynchronous connect-and-save task
Network	GET /api/network/wifi/connection?task_id=...	Poll connection, persistence, and rollback status
Network	DELETE /api/network/wifi/connection?ssid=...	Forget a network without relying on a DELETE request body
System	GET/PUT /api/system/environment	Read or atomically replace system environment variables
OTA	GET /api/ota/status	Read the current state, progress, and log summary
OTA	POST /api/ota/updates	Create an OTA task and return its task_id
Logs	GET /api/logs/agent	Read the Agent log summary
Logs	GET /api/logs/llm	List available LLM HTTP log files
Logs	GET/PUT /api/logs/llm/{name}	Export a raw LLM HTTP log or import one with the same name
Logs	GET /api/logs/support	Export a diagnostic support-log archive

All endpoints above are served by Config Web on port 80. The page uses only same-origin management requests. Agent port mappings therefore do not affect the configuration portal, and the Agent does not expose duplicate models, STT test, or storage-management handlers on port 8080.

GET /api/storage/status and the storage field of GET /api/device/snapshot share the following response shape:

{
  "effective_mode": 1,
  "card": {
    "present": false,
    "mounted": false,
    "device": "",
    "total_bytes": 0,
    "free_bytes": 0,
    "reason": ""
  },
  "mount_point": "/mnt/sdcard",
  "format_job": {"status": "idle"},
  "migration": {"status": "idle"}
}

format_job is asynchronous and its status can be idle, running, success, or failed. migration represents the background migration from eMMC to SD and uses the same status values. A card can be present without being mounted, so clients must use card.present and card.mounted independently when enabling the format and eject actions.

Configuration Save Response

A successful PATCH /api/config response includes:

{
  "ok": true,
  "persisted": true,
  "applied": true,
  "revision": 123,
  "changed_paths": ["model.model"],
  "reboot_required": false,
  "restart_required": false,
  "restart_reasons": [],
  "agent_restart_scheduled": false
}

persisted means the configuration file was written atomically. applied means the Agent accepted and loaded that revision. Clients must present these states separately. If reload fails, the endpoint returns HTTP 503 while retaining persisted=true, applied=false, and the error details. Config Web then schedules an Agent restart and reports agent_restart_scheduled=true; a restart launch failure is reported instead of leaving the saved revision with no recovery path. On a successful response, restart_required mirrors reboot_required: HID changes that need a clean USB session set both fields and the page offers to reboot the board. restart_reasons explains why that reboot is required. agent_restart_scheduled instead describes the fallback process restart used when the running Agent rejects an in-place reload.

Agent Restart Lifecycle

Updating /api/system/environment persists the environment file and schedules an Agent restart. A rejected hot reload follows the same restart lifecycle. STT configuration tests are owned by Config Web and remain available while the Agent restarts. Restart launch failures are returned to the caller instead of being reported as a successfully scheduled restart.

Storage Ownership

Config Web is the sole owner of StorageManager: it detects and mounts the SD card, runs format/eject operations, migrates governed data, and writes /run/aiden/storage.state. The Agent runtime never performs those hardware operations. It uses a read-only state view to include the SD archive root when serving previously migrated audio.

Wi-Fi Task Lifecycle

PUT /api/network/wifi/connection returns HTTP 202 with a task_id immediately. The task has a 120-second total deadline covering candidate application, verification, persistence, and rollback. Clients poll the GET form until the status is succeeded or failed; failure responses distinguish the candidate apply result from the rollback result.

API Boundary

Retired routes such as /api/wifi/*, /api/system/env, /api/ota/update, /api/reboot, /api/agent/*, and /api/llm-logs/* have been removed and return 404 Not Found; no compatibility adapters are provided. Clients must use the canonical resources in the table above. GET /api/config has only configuration semantics; use /api/device/snapshot for the aggregated initial page load.

Internal Agent Reload

POST /api/internal/config/reload accepts loopback requests only and may carry a revision. The Agent validates that revision and reports applied=true only after every affected runtime dependency has been rebuilt successfully. A stale revision returns HTTP 409. This endpoint is not part of the public management API.