> ## Documentation Index > Fetch the complete documentation index at: https://docs.vigolium.com/llms.txt > Use this file to discover all available pages before exploring further. # Running the Server > Run Vigolium as a persistent REST API server for traffic ingestion, scan triggers, and agent runs. ## What is Server Mode Vigolium can run as a persistent REST API server, accepting traffic ingestion, scan triggers, and agent runs via HTTP endpoints. Server mode is useful for team workflows where multiple users share a scanning backend, CI/CD integration where automated pipelines submit traffic and retrieve findings, and building custom tooling on top of Vigolium's API. ## Starting the Server ```bash theme={null} # Start with an API key export VIGOLIUM_API_KEY=my-secret-key vigolium server # Custom host and port export VIGOLIUM_API_KEY=my-secret-key vigolium server --host 127.0.0.1 --service-port 9002 # With an upstream proxy for outgoing scanner traffic export VIGOLIUM_API_KEY=my-secret-key vigolium server --proxy http://corporate-proxy:8080 # Without authentication (development only) vigolium server -A # Mirror every ingested record + finding to a browsable filesystem tree vigolium server --mirror-fs ./mirror # Passively scan every ingested request as it arrives (no active traffic) vigolium server --scan-on-receive --passive-only ``` The server listens on `0.0.0.0:9002` by default. ## Live Filesystem Mirror `vigolium server --mirror-fs ` (config `server.mirror_fs_path`) mirrors every saved HTTP record and finding to a flat filesystem tree **as it is persisted**, in addition to the database. This lets an external tool or coding agent read ingested Burp/proxy traffic as plain files in real time: ```bash theme={null} vigolium server --mirror-fs ./mirror ``` Every record and finding lands under `./mirror/traffic//…` and `./mirror/findings//…` using the same layout as the [`fs` export format](/getting-started/output-and-reporting#filesystem-fs) — per-host `.req`, `.resp.headers`, `.resp.body`, and finding `.md` files cross-linked to the request that produced them. * The mirror's indexes are append-only `index.jsonl` (one JSON object per line — `tail -f`/`grep` it live), as opposed to the one-shot export's `index.json` array. * Per-host id numbering resumes from the existing tree across server restarts. * The writer runs on a background goroutine and never blocks the database save path, so mirroring adds no latency to ingestion. The mirror is opt-in and server-only — CLI scans are unaffected. To produce the same tree as a one-shot export from a finished scan or the database, use `--format fs` (see [Output and Reporting](/getting-started/output-and-reporting#filesystem-fs)). ## Scan on Receive `-S/--scan-on-receive` runs the scanner against every ingested request as it is persisted, so forwarded Burp/proxy traffic is analyzed in place without a separate scan command: ```bash theme={null} # Full active + passive assessment on every ingested request vigolium server --scan-on-receive # Passive modules only — no active scan traffic is ever sent (secret detection still runs) vigolium server --scan-on-receive --passive-only ``` * `--passive-only` restricts scan-on-receive to **passive modules only** — the safest way to analyze forwarded traffic in place. * Combining `--passive-only` with `--full-native-scan-on-receive` still crawls (discovery + spidering send requests); for zero active traffic, use `--scan-on-receive` without the full-native flag. ## Authentication All API requests except the public meta endpoints (`/`, `/health`, `/metrics`, `/server-info`, `/swagger/*`, and `POST /api/auth/login`) require a Bearer token: ``` Authorization: Bearer my-secret-key ``` API key resolution order: `VIGOLIUM_API_KEY` env var > `server.auth_api_key` in config file (`~/.vigolium/vigolium-configs.yaml`). ## CORS Configuration The server's CORS behavior is controlled by `cors_allowed_origins` in `~/.vigolium/vigolium-configs.yaml`: ```yaml theme={null} server: cors_allowed_origins: reflect-origin ``` | Value | Behavior | | ---------------------------------------------------- | --------------------------------------------------------------- | | `reflect-origin` (default) | Echoes the requesting `Origin` header back. Allows credentials. | | `*` | Allows all origins without credentials (standard wildcard). | | *(empty string)* | Disables CORS middleware entirely. | | `https://app.example.com, https://admin.example.com` | Comma-separated allowlist. Allows credentials. | ## Project Scoping All server operations are scoped to a project via the `X-Project-UUID` request header. If omitted, the default project is used. ```bash theme={null} curl -X POST http://localhost:9002/api/ingest-http \ -H "Authorization: Bearer my-secret-key" \ -H "X-Project-UUID: a1b2c3d4-..." \ -H "Content-Type: application/json" \ -d '{"input_mode": "url", "content": "https://example.com"}' ``` All queries (findings, HTTP records, stats, scans) return data scoped to the project specified in the header. See [Projects](/others/projects) for the full multi-tenancy reference. ## API Endpoint Overview A condensed view — see the [API References](/others/api-references) index for the full surface. | Method | Path | Description | | --------- | ----------------------------------------------- | ---------------------------------------------------------------------- | | GET | `/` | Static UI (no auth required) | | GET | `/health` | Health check (no auth required) | | GET | `/metrics` | Prometheus metrics (no auth required) | | GET | `/swagger/*` | Swagger UI and OpenAPI spec (no auth required) | | GET | `/server-info` | Server status (no auth required) | | POST | `/api/auth/login` | File-based login → bearer token | | GET | `/api/info` | App info / build metadata | | GET | `/api/user/info` | Current user | | GET | `/api/projects` | List projects | | GET | `/api/modules` | List available scanner modules | | GET | `/api/http-records` | Query stored HTTP records | | GET | `/api/findings` | Query scan findings | | PATCH | `/api/findings/:id/status` | Update finding status (open/triaged/closed) | | POST | `/api/ingest-http` | Ingest HTTP traffic into the database | | POST | `/api/import` | Bulk import scans/records/findings | | GET | `/api/stats` | Aggregated scan statistics | | GET | `/api/oast-interactions` | List OAST callbacks | | GET, POST | `/api/scope` | View/update scope configuration | | GET, POST | `/api/config` | View/update server configuration | | POST | `/api/scans/run` | Trigger a background scan | | POST | `/api/scan-url` | Scan a single URL | | POST | `/api/scan-request` | Scan a single raw request | | POST | `/api/scan-records` | Scan specific record UUIDs | | POST | `/api/scan-all-records` | Scan filtered records | | GET | `/api/scans` | List scans | | GET | `/api/scans/:uuid` | Scan status | | GET | `/api/scans/:uuid/logs` | Scan logs (SSE supported) | | POST | `/api/scans/:uuid/stop` | Cancel a running scan | | POST | `/api/scans/:uuid/pause` | Pause a scan | | POST | `/api/scans/:uuid/resume` | Resume a scan | | POST | `/api/scans/:uuid/update` | Adjust scan parameters mid-run | | GET | `/api/scan/status` | Latest scan status (legacy/global) | | POST | `/api/agent/run/query` | Single-shot agent prompt execution | | POST | `/api/agent/run/autopilot` | Autonomous AI-driven scanning session | | POST | `/api/agent/run/swarm` | AI-guided multi-phase vulnerability scan | | POST | `/api/agent/run/audit` | Audit/piolium driver dispatcher (`driver: auto\|both\|audit\|piolium`) | | GET | `/api/agent/status/list` | List agent runs | | GET | `/api/agent/status/:id` | Get agent run status (includes full result when completed) | | GET | `/api/agent/sessions` | Paginated session history | | GET | `/api/agent/sessions/:id/logs` | Tail or read `runtime.log` (SSE supported) | | GET | `/api/agent/sessions/:id/artifacts[/:filename]` | Browse / fetch agent session artifacts | | POST | `/api/agent/chat/completions` | OpenAI-compatible chat completions | | POST | `/api/storage/upload-source` | Upload source archive to cloud storage | | POST | `/api/storage/presign` | Pre-signed upload/download URLs | | GET | `/api/storage/source/:key` | Download a stored source archive | | GET | `/api/diagnostics` | System readiness check | | GET | `/api/db/tables` | List database tables | | GET, POST | `/api/db/tables/:name/records` | Generic table browser (read / queries) | | GET | `/api/extensions` | List loaded extensions | | PUT, POST | `/api/extensions/:name` | Upload / enable extension | ## Scan Management via API After ingesting HTTP records, trigger a vulnerability scan via the API. ### Trigger a Scan ```bash theme={null} curl -s -X POST http://localhost:9002/api/scans/run \ -H "Authorization: Bearer my-secret-key" \ -H "Content-Type: application/json" \ -d '{}' | jq . ``` Force re-scan with specific modules: ```bash theme={null} curl -s -X POST http://localhost:9002/api/scans/run \ -H "Authorization: Bearer my-secret-key" \ -H "Content-Type: application/json" \ -d '{ "force": true, "enable_modules": ["xss-scanner", "sqli-error-based"] }' | jq . ``` Returns `202 Accepted` with a `scan_uuid` on success, `409 Conflict` if a scan is already running. ### Check Scan Status ```bash theme={null} # Latest scan, legacy/global endpoint curl -s http://localhost:9002/api/scan/status \ -H "Authorization: Bearer my-secret-key" | jq . # Specific scan curl -s http://localhost:9002/api/scans/SCAN-UUID \ -H "Authorization: Bearer my-secret-key" | jq . ``` ### Cancel a Running Scan ```bash theme={null} curl -s -X POST http://localhost:9002/api/scans/SCAN-UUID/stop \ -H "Authorization: Bearer my-secret-key" | jq . ``` See the [API Reference](/api-references/scan) for full request/response details. ## Running AI Agents via API The server exposes agent endpoints that mirror the `vigolium agent` CLI subcommands (query, autopilot, swarm, audit). The audit dispatcher accepts `driver: "auto"|"both"|"audit"|"piolium"` to drive the embedded vigolium-audit harness and/or piolium. Concurrency is bounded by a global heavy/light semaphore plus a per-project heavy cap; new heavy runs return `409 Conflict` when the cap is reached. Set `"stream": true` for real-time SSE output (multi-driver audit streams add a `driver` field per chunk). For full details on agent modes, prompt templates, and API request/response schemas, see the [Agent Mode](/agentic-scan/agent-mode) documentation and the [Agent API Reference](/api-references/agent).