Agent Mode

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.

Vigolium ships eight 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: archon (Claude/Codex/OpenCode), piolium (Pi-native), and audit (unified driver that runs both back-to-back)
• 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, archon-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 archon), --focus, --max-commands, --max-duration, --intensity {quick|balanced|deep}, --archon (lite|balanced|deep|off), --browser, --credentials, --diff, --last-commits, --token-budget, --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, --archon {lite|balanced|deep|off}, --intensity, --only/--skip/--start-from, --force-extensions.

See Swarm.

​

archon — AI security source audit (Claude/Codex/OpenCode)

• Use for: deep code audit standalone, or as the source-aware companion to autopilot/swarm.
• Modes: lite (3 phases), balanced/scan (6), deep (10), revisit, confirm, merge, diff, status, mock.
• Key flags: --mode, --source <path|git-url>, --agent {claude|codex|opencode}, --no-stream.

See Archon Audit.

​

piolium — AI security source audit (Pi-native)

• Use for: the same multi-phase audit as archon but running through the Pi runtime + the user-installed piolium extension. Useful when the host already has Pi configured for non-Anthropic providers (OpenAI/Codex, Gemini).
• 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 Piolium Audit.

​

audit — unified driver (archon + piolium)

• Use for: scoring a single source tree under both audit harnesses with one AgenticScan. Sequential execution (archon first, piolium second), per-driver session subdirs ({session}/archon/, {session}/piolium/), per-driver child AgenticScan rows under one parent, and a post-pass project-wide findings dedup once both drivers exit.
• Modes: when --driver=both, only the shared modes are accepted: lite, balanced, deep, revisit, confirm, merge. Use --driver=piolium for longshot/smoke or --driver=archon for mock.
• Key flags: --driver {piolium|archon|both}, --mode, --intensity, --source, --commit-depth, --no-stream, --no-dedup, --upload-results, --agent (archon platform), plus the --pi-* and --plm-* flags from agent piolium.
• REST equivalent: POST /api/agent/run/audit with driver: "piolium"|"archon"|"both" (default "both").

​

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}, -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 an archon-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 driver: "both" (default) and multiplexes SSE chunks with a driver field bracketed by driver_start/driver_end markers when stream: true. See Piolium Audit for the full unified-driver request schema. 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 are CLI / server-config only

The CLI exposes per-invocation provider flags (--provider, --model, --oauth-cred, --oauth-token, --llm-api-key, --system). These are not mirrored on the REST request schemas. The server resolves the provider once from agent.olium.* in vigolium-configs.yaml and reuses it across requests, which keeps prompt caches stable. To switch providers on a server-side workload, edit the YAML and reload — there is no per-request override field. See API Reference — Agent for the full request/response schemas.