> ## 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.

# Agent Mode

> Vigolium ships seven agent subcommands under `vigolium agent` covering autonomous scanning, AI-guided pipelines, a unified source-audit driver, single-shot prompts, single-finding triage, and an interactive TUI.

Vigolium ships **seven agent subcommands** under `vigolium agent`. They split into four families:

* **Agentic scan modes**: autonomous or AI-guided vulnerability scanning: `autopilot`, `swarm`
* **Source audit mode**: multi-phase AI code audit: `audit` (unified driver for the embedded vigolium-audit harness and/or the standalone piolium harness, selected with `--driver`)
* **Single-shot / interactive**: `query`, `olium`
* **Utility**: `session`, `triage`

The parent `vigolium agent` command itself only supports `--list-templates` and `--list-agents`. All execution requires a subcommand.

Every agent invocation is dispatched through the in-process **olium runtime** (`pkg/olium/`). There are no subprocess SDK or ACP backends, provider selection lives at `agent.olium.provider` in `vigolium-configs.yaml`. See [How It Works](/agentic-scan/how-it-works) for the provider list.

***

## When to use what

| You want to...                                                           | Use         | Why                                                                                                                                                                                                |
| ------------------------------------------------------------------------ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Run a one-off prompt against code or a target (no scanning loop)         | `query`     | Single-shot, template-driven, returns structured findings or HTTP records                                                                                                                          |
| Hand the agent the wheel for a full autonomous pentest                   | `autopilot` | Autonomous operator with full tools; optionally rotate context and verify candidates in durable mode                                                                                               |
| Have the AI **drive the native scanner** on a specific target            | `swarm`     | Master/worker pipeline: AI plans → native modules execute → optional triage+rescan                                                                                                                 |
| Audit source code (secrets, SAST triage, PoC) before or alongside a scan | `audit`     | Unified driver dispatcher: drives the embedded vigolium-audit harness, piolium, or both (`--driver auto\|both\|audit\|piolium`), with per-driver child AgenticScan rows + post-pass findings dedup |
| Chat with an LLM interactively in a TUI (debug, explore, ad-hoc)         | `olium`     | Real-time multi-turn chat; not a security scan, general-purpose agent                                                                                                                              |
| Review past agent runs                                                   | `session`   | Lists prior runs, shows raw output and artifacts                                                                                                                                                   |
| Confirm or downgrade a single existing finding with AI                   | `triage`    | Runs the AI triage flow against one finding by id and updates its verdict/severity                                                                                                                 |

***

## Mode reference

### `query`: single-shot prompt

* **Use for:** code review, endpoint discovery, secret detection, ad-hoc prompts.
* **Not for:** network scanning or multi-phase orchestration.
* **Key flags:** `--prompt-template`, `-p/--prompt`, `--stdin`, `--source`, `--files`, `--source-label`, `--output`, `--dry-run`, `--provider`, `--model`, `--oauth-cred`, `--oauth-token`, `--llm-api-key`.

### `autopilot`: autonomous agentic scan

* **Use for:** pentest-style engagements where you want the agent to be creative and decide what to do.
* **How it works:** one autonomous operator runs until it calls `halt_scan` or hits limits. `legacy` keeps one conversation; `shadow`/`enforced` rotate bounded sections and persist resumable state. When `--source` is provided, vigolium-audit runs first to prepare a frozen whitebox context bundle.
* **Key flags:** `[prompt]`/`--prompt`, `-t/--target`, `--input`, `--burp-bridge-url`, `--prior-context {auto|summary|off}`, `--knowledge-base`, `--plan-file`, `--source`, `--max-duration`, `--intensity {quick|balanced|deep}`, `--audit {lite|balanced|deep|off}`, `--resume`, `--session-dir`, `--transcript`, `--triage`, `--diff`, and `--last-commits`.

See [Autopilot](/agentic-scan/autopilot).

### `swarm`: AI-guided multi-phase scan

* **Use for:** target-specific scanning when you want structure (planning → native scan → triage), source-aware route discovery, or verification loops.
* **How it works:** 10-phase pipeline, normalize → auth (opt) → source-analysis (opt) → code-audit (opt) → discover (opt) → plan (AI) → extension → native scan → triage (opt) → rescan (opt).
* **Key flags:** `[prompt]`/`--prompt`, `-t/--target` (required with `--source`), `--input`, `--plan-file`, `--record-uuid`, `--source`, `--discover`, `--code-audit`, `--triage`, `--max-iterations`, `-m/--modules`, `--vuln-type`, `--audit {lite|balanced|deep}`, `--intensity`, `--only`/`--skip`/`--start-from`, and `--with-extensions`.

See [Swarm](/agentic-scan/swarm).

### `audit`: unified source-audit driver

* **Alias:** `vigolium audit` is a top-level alias for `vigolium agent audit` (identical flags).
* **Use for:** running the embedded vigolium-audit harness and/or the standalone piolium harness against a single source tree under one AgenticScan, with per-driver session subdirs (`{session}/audit/`, `{session}/piolium/`), per-driver child AgenticScan rows under one parent, and a post-pass project-wide findings dedup once both drivers exit.
* **Driver values (`--driver`):**
  * `auto` (default) — run vigolium-audit; fall back to piolium only if the `claude`/`codex` CLI required by audit is missing.
  * `both` — run vigolium-audit then piolium back-to-back, unconditionally.
  * `audit` — run only the embedded vigolium-audit harness.
  * `piolium` — run only the standalone piolium harness (no audit, no fallback).
* **Modes:** when the run includes both drivers (`auto` or `both`), `--mode` is restricted to the shared set: `lite`, `balanced`, `deep`, `revisit`, `confirm`, `merge`. Use `--driver=piolium` for `longshot`/`smoke` or `--driver=audit` for `mock`. `--intensity deep` expands to the chain `deep,confirm`.
* **Agent selection (audit leg only):** `--provider <olium-provider>` resolves the agent **and** forwards that provider's BYOK auth (`anthropic-*` → claude, `openai-*` → codex). `--agent {claude|codex}` is a pure agent selector layered on top of `--provider` (rejected for invalid values; warned under `--driver=piolium`).
* **Key flags:** `--driver {auto|both|audit|piolium}`, `--mode`, `--modes` (chain), `--intensity {quick|balanced|deep}`, `--source <path|git-url>`, `--commit-depth`, `--interactive`, `--no-stream`, `--no-dedup`, `--upload-results`, `--provider`, `--agent`, plus the `--pi-*` and `--plm-*` passthroughs for the piolium leg. `--list-modes` prints the embedded vigolium-audit binary's mode graph and exits.
* **Raw output (audit leg):** `--keep-raw` is **on by default** (CLI), retaining `<source>/vigolium-results/` in the source tree; `--clean-raw` removes it after the run (the session copy is always kept). `--keep-raw`+`--clean-raw` is an error. The REST `keep_raw` default is unchanged (off).
* **One-shot report:** `-S`/`--stateless` runs the audit into a throwaway temp DB (main DB untouched, like `vigolium scan -S`) and auto-writes a self-contained HTML report to `vigolium-result/vigolium-audit-report.html` (override with `-o`/`--output`; supports `gs://` and `{ts}`). Not valid with `--interactive`.
* **REST equivalent:** `POST /api/agent/run/audit` with `driver: "auto"|"both"|"audit"|"piolium"` (default `"auto"`).

See [Agentic Security Audit](/getting-started/agentic-security-audit).

<Note>
  There is no standalone `vigolium agent piolium` subcommand. Piolium runs only through the audit dispatcher, `vigolium agent audit --driver piolium` (piolium alone), `--driver both` (audit then piolium), or `--driver auto` (piolium as fallback when the `claude`/`codex` CLI is missing). Piolium-only modes (`longshot`, `smoke`) and passthroughs (`--pi-*`, `--plm-*`) are exposed on `agent audit`.
</Note>

### `olium`: interactive TUI chat

* **Aliases:** top-level `vigolium olium` / `vigolium ol`.
* **Use for:** interactive debugging, exploration, or one-shot non-interactive prompts. Provider-agnostic.
* **Not for:** orchestrated scanning, there are no scan phases.
* **Key flags:** `--provider`, `--model`, `--llm-api-key`, `--oauth-cred`/`--oauth-token`, `--system`, `-p/--prompt` (one-shot non-interactive), `--stdin`.

### `session`: agent run history

* **Aliases:** `sessions`, `sess`.
* **Use for:** auditing prior runs, debugging failed scans.
* **Key flags:** `--mode {query|autopilot|swarm|audit}`, `-n/--limit`, `-o/--offset`, `--tail`, `--full`.

### `triage`: single-finding confirmation

* **Use for:** confirming or downgrading one existing finding with AI, without launching a full scan.
* **How it works:** `vigolium agent triage [finding-id]` loads the stored finding (and its linked request/response), runs the AI triage flow against it, and updates the finding's verdict/severity in place.
* **Not for:** discovering new issues, it only re-evaluates a finding you already have.

***

## Picking between `autopilot` and `swarm`

Both are agentic scan modes. The distinction:

* **`autopilot`**: the agent **is** the scanner. It opens a shell, reads files, runs tools, and decides everything. Best when the target is fuzzy or you want creative, exploratory testing.
* **`swarm`**: the agent **directs** the native scanner. It plans, picks modules, generates JS extensions, and the deterministic Go pipeline does the heavy traffic. Best when you want structured, repeatable results with optional verification loops.

If you have **source code** and a **target URL**, both work; `swarm --source --target ... --code-audit --triage` gives you the most structured output, while `autopilot --source ...` gives the agent more freedom (and runs a vigolium-audit prep first).

***

## Cross-cutting

* **Session dir:** `~/.vigolium/agent-sessions/` (override via `agent.sessions_dir` in `vigolium-configs.yaml`).
* **Durable autopilot:** set `agent.olium.autopilot_mode` to `shadow` or `enforced`; `legacy` remains the default.
* **Prompt templates:** `~/.vigolium/prompts/` or embedded under `public/presets/prompts/`.
* **Output schemas:** `findings`, `http_records`, `attack_plan`, `triage_result`, `source_analysis`.
* **Engine:** every agent run is dispatched through the in-process olium runtime (`pkg/olium/`). Provider selection lives at `agent.olium.provider` in `vigolium-configs.yaml`, see [How It Works](/agentic-scan/how-it-works) for the provider list.
* **Source flag:** `--source` is the canonical source-code flag across all modes; the legacy `--repo`/`--repo-url`/`--source-url` flags have been removed.
* **Task guidance:** autopilot and swarm use `--prompt` or the positional prompt. Their former CLI flags `--focus`, `--instruction`, `--instruction-file`, `--browser`, and `--credentials` are removed; put focus and login details in the prompt. Structured equivalents remain available in the REST API.

***

## REST API

The server exposes the run modes plus a status/artifact surface so a controller can launch and tail runs without the CLI.

| Method | Path                                       | Purpose                                                                                                                                 |
| ------ | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| POST   | `/api/agent/run/query`                     | One-shot prompt execution.                                                                                                              |
| POST   | `/api/agent/run/autopilot`                 | Launch an autopilot scan.                                                                                                               |
| POST   | `/api/agent/run/swarm`                     | Launch a swarm scan.                                                                                                                    |
| POST   | `/api/agent/run/audit`                     | Unified audit driver dispatcher, `driver: "auto"\|"both"\|"audit"\|"piolium"` (default `auto`).                                         |
| GET    | `/api/agent/status/list`                   | List active and historical runs (DB + in-memory merge).                                                                                 |
| GET    | `/api/agent/status/:id`                    | Status of a single run.                                                                                                                 |
| GET    | `/api/agent/sessions`                      | Paginated session history (richer than `/status/list`).                                                                                 |
| GET    | `/api/agent/sessions/:id`                  | Full session detail incl. raw output, plan, child runs.                                                                                 |
| GET    | `/api/agent/sessions/:id/logs`             | Read or tail `runtime.log` (SSE when `Accept: text/event-stream`).                                                                      |
| GET    | `/api/agent/sessions/:id/artifacts`        | List files inside the session\_dir (recursive, capped at 500 entries).                                                                  |
| GET    | `/api/agent/sessions/:id/artifacts/{name}` | Read one file. Wildcard supports nesting (`vigolium-audit/state.json`). Optional `?max_bytes=N` cap (default 10 MiB, hard cap 100 MiB). |
| POST   | `/api/agent/chat/completions`              | OpenAI-compatible chat completions (synchronous).                                                                                       |

Run endpoints return `202 Accepted` with `{agentic_scan_uuid, status: "running"}` and execute in the background. Expected workflow:

1. `POST` one of the `run/*` endpoints, capture `agentic_scan_uuid`.
2. Poll `GET /api/agent/status/:id` until `status` leaves `running`.
3. Fetch the session artifacts via `/api/agent/sessions/:id/logs`, `/artifacts`, or `/artifacts/{name}` for the raw outputs (`output.md`, `swarm-plan.json`, `audit-stream.jsonl`, generated extensions, etc.).

The `audit` endpoint dispatches sequentially when more than one driver runs (`auto` with fallback or `both`), and multiplexes SSE chunks with a `driver` field bracketed by `driver_start`/`driver_end` markers when `stream: true`. See [Agentic Security Audit](/getting-started/agentic-security-audit) for the unified-driver overview.

Set `stream: true` on the run endpoints to opt into Server-Sent Events instead of the async response, most consumers should stick with the async flow and tail logs on demand.

### Provider overrides

The CLI exposes per-invocation provider flags (`--provider`, `--model`, `--oauth-cred`, `--oauth-token`, `--llm-api-key`, `--system`). 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`). The audit dispatcher additionally accepts `audit_auth` and `piolium_auth` for per-driver overrides.

See [API Reference, Agent](/api-references/agent) for the full request/response schemas.