Skip to main content
Architecture series: Overview · Native Scan · Agentic Scan · Data & Storage · Server & API
Vigolium runs as a long-lived service via vigolium server, a Fiber REST API that ingests traffic, triggers native and agentic scans, and serves results, all sharing the same project-scoped persistence layer as the CLI. This document explains the service’s shape and request lifecycle. For curl-by-curl recipes see Server & Ingestion; for the full endpoint catalogue see API Overview and the API Reference.

​
1. Process model

The server is pkg/server/ (Fiber). It owns no scan logic of its own, it wraps the same internal/runner native pipeline and the same pkg/agent orchestrators the CLI uses, so behavior is identical whichever entry point launches a scan. Three traffic sources feed the same RecordWriter → repository path: the /api/ingest-http endpoint, the optional transparent HTTP proxy, and the vigolium ingest client.

​
Middleware chain

Every request (except /, /health, /metrics, /swagger/*) passes:
  1. CORS: server.cors_allowed_origins, reflect-origin (default, credentialed echo), * (wildcard, no credentials), explicit comma-separated allowlist, or empty (disabled).
  2. Auth: Authorization: Bearer <key>; key resolves VIGOLIUM_API_KEY env > server.auth_api_key config. vigolium server -A disables auth (development only).
  3. Project resolution: X-Project-UUID header selects the tenant (default project if absent); X-User-Email drives optional per-project access control (403 on denial). See Data & Storage.

​
2. Traffic ingestion

POST /api/ingest-http is the universal entry point. A single endpoint accepts many input_modes, normalizes them into HttpRequestResponse items, and hands them to the async RecordWriter: Large payloads should use the *_base64 fields to avoid JSON escaping. The same parsers back the vigolium ingest CLI, which runs in two modes: remote (-s http://server → POSTs to /api/ingest-http) or local (--server omitted → fetches and writes straight to the DB).

​
Transparent proxy

vigolium server --ingest-proxy-port 9003 opens a recording HTTP proxy. Plain HTTP traffic routed through it is captured into the DB; HTTPS CONNECT tunnels pass through without recording. This is the zero-instrumentation path for capturing traffic from arbitrary tools (curl -x, httpx -proxy, nuclei -proxy).

​
3. The REST surface

Endpoints group by concern; each group has a dedicated page under the API Reference.

​
Asynchronous job pattern

Scan and agent runs are long-lived, so the API is launch-and-poll, not request/response:
  1. POST /api/scans/run or /api/agent/run/* → 202 Accepted with a UUID (409 Conflict if one is already active, only one agent run at a time).
  2. Poll GET /api/scan/status or GET /api/agent/status/:id until status leaves running.
  3. Fetch artifacts: GET /api/agent/sessions/:id/{logs,artifacts,artifacts/*} (logs SSE-capable; artifact reads support nested paths and a ?max_bytes= cap).
Opting into "stream": true on a run endpoint switches to Server-Sent Events instead, data: lines carrying {"type":"chunk|phase|done|error", …}. Most consumers should prefer the async poll-and-tail flow to keep warm sessions and prompt caches stable.

​
4. Agent run API

pkg/server/handlers_agent.go mirrors the vigolium agent subcommands over HTTP. It does not re-implement agent logic, it invokes the same orchestrators documented in Agentic Scan, with one deliberate constraint:
  • Server-default provider, BYOK per request. The server falls back to agent.olium.* in vigolium-configs.yaml (which keeps warm sessions and prompt caches stable across requests), but every agent run endpoint also accepts per-request BYOK credentials (api_key, oauth_token, oauth_cred_file, oauth_cred_json) so callers can swap providers on a single request without editing YAML.
  • Backward-compatible source field. Request types expose EffectiveSourcePath() to accept both source and legacy repo_path JSON keys.
  • Audit driver dispatch. POST /api/agent/run/audit takes driver: "auto"|"both"|"audit"|"piolium" (default "auto" — run audit; fall back to piolium only if audit fails). Multi-driver modes run sequentially under one parent run, expose per-driver BYOK auth (audit_auth, piolium_auth), and multiplex SSE chunks with a driver field when streaming.
  • OpenAI-compatible endpoint. POST /api/agent/chat/completions exposes the in-process olium engine through the OpenAI Chat Completions wire format so existing SDKs (LangChain, LlamaIndex, custom proxies) can drive Vigolium agents.

Server & Ingestion

Startup flags, curl recipes per input mode.

API Overview

Full endpoint catalogue and request/response schemas.

Agentic Scan

The orchestrators the agent endpoints invoke.

Data & Storage

Project scoping and the persistence layer the handlers share.