Agent Mode

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 for the provider list.

---

​

When to use what

---

​

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.

​

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.

​

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.

​

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 <path|git-url>, --commit-depth, --no-stream, --upload-results, --pi-provider, --pi-model, plus --plm-* passthroughs for piolium’s session flags.

See 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 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. 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 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 for the full request/response schemas.