> ## 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, 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 modes**: multi-phase AI code audit: `audit` (unified driver for the embedded vigolium-audit harness and/or the standalone piolium harness) and `piolium` (direct piolium driver) * **Single-shot / interactive**: `query`, `olium` * **Utility**: `session` 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` | One long LLM session with full Bash/Read/Write/Grep/Glob; agent picks strategy | | 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, with per-driver child AgenticScan rows + post-pass findings dedup | | Direct piolium harness driver (Pi-native install required) | `piolium` | Skips the dispatcher and runs piolium alone with its own modes | | 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 | *** ## 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 long-running LLM session with full CLI tool access until the agent calls `halt_scan` or hits limits. When `--source` is provided, vigolium-audit runs first to prepare a frozen whitebox context bundle. * **Key flags:** `-t/--target`, `--input` (curl/raw HTTP/Burp XML/URL/stdin), `--source` (auto-runs vigolium-audit), `--focus`, `--max-duration`, `--intensity {quick|balanced|deep}` (sets the command budget, audit mode, browser, and pre-scan strategy), `--audit` (`lite|balanced|deep|off`), `--triage`, `--plan-file`, `--browser`, `--credentials`, `--diff`, `--last-commits`, `--upload-results`. 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:** `-t/--target` (required with `--source`), `--input`, `--record-uuid`, `--source`, `--discover`, `--code-audit`, `--triage`, `--max-iterations`, `-m/--modules`, `--vuln-type`, `--focus`, `--audit {lite|balanced|deep|off}`, `--intensity`, `--only`/`--skip`/`--start-from`, `--force-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 ` 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 `, `--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 `/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). ### `piolium`: direct piolium harness driver * **Use for:** dropping the dispatcher and running piolium alone. Equivalent to `vigolium agent audit --driver piolium`, but exposes piolium-only flags (`longshot`/`smoke` modes, `--plm-*` session passthroughs) without the audit-leg argument parsing. * **Modes:** `lite` (4), `balanced` (9), `deep` (17), `revisit` (9), `confirm` (7), `merge` (7), `diff` (1), `longshot` (3), `status`, `smoke`. * **Key flags:** `--mode`, `--intensity {quick|balanced|deep}`, `--source `, `--commit-depth`, `--no-stream`, `--upload-results`, `--pi-provider`, `--pi-model`, plus `--plm-*` passthroughs for piolium's session flags. See [Agentic Security Audit](/getting-started/agentic-security-audit). ### `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`. *** ## 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`). * **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. *** ## 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.