vigolium agent autopilot is the autonomous agentic scan. One operator decides what to investigate, drives tools (Bash, file I/O, web fetch, browser probes, and first-class Vigolium tools), and halts when it has nothing productive left to do.
The default legacy mode keeps one growing conversation. The opt-in shadow and enforced modes split the run into bounded sections, rebuild each section from durable state, and verify finding candidates in a fresh context. There is still no master/worker phase pipeline; use Swarm when you want that structure.
Mental model
Think of it as a security analyst sitting at a terminal:- The analyst is given a target URL, optional source and reference documentation, and task guidance.
- They have shell access, file-read access, web access, and the vigolium CLI.
- They can mine traffic and findings already stored in the project, follow leads, record evidence, and stop when there is nothing more worth digging into.
Lifecycle (high-level)
Execution modes
Setagent.olium.autopilot_mode in vigolium-configs.yaml:
transcript.jsonl, and rows are stored in agent_sections and agent_finding_candidates.
Use shadow first when you want to compare verifier decisions without changing which findings land. Use enforced when you want verification to gate finding creation.
CLI
Key flags
The CLI no longer exposes
--focus, --instruction, --instruction-file, --browser, --credentials, or the other auth-intent flags. Put that information in --prompt (or the positional prompt). Browser tooling is always available, and the intent parser extracts login details and browser requirements. The REST API keeps its structured focus, instruction, browser, and credential fields for programmatic callers.
API
EffectiveSourcePath() accepts either source or the legacy repo_path JSON field. The server resolves provider/model from agent.olium.* by default; pass api_key, oauth_token, oauth_cred_file, or oauth_cred_json on the same request to override per call. Returns 202 Accepted with {agentic_scan_uuid, status}. Set stream: true for an SSE response.
The REST schema still exposes structured focus, instruction, browser, and authentication fields. CLI-only orchestration flags added in v0.3.1—--resume, --knowledge-base, --prior-context, --burp-bridge-url, --session-dir, and --transcript—are not request fields on this endpoint.
What the agent actually has access to
The autopilot is not restricted to the vigolium CLI. The engine ships a generic agentic toolset, and — once a project database is wired — a set of first-class vigolium scanner/record tools on top of it. Much of the security-specific behavior still comes from the system prompt and skills, not just the tool surface.
When a project database is wired (always the case for a real autopilot run) the agent also gets first-class vigolium tools from
pkg/olium/vigtool/, so it doesn’t have to shell out to the CLI for common scanner actions:
The model still decides when to invoke
vigolium scan-url, vigolium finding, etc. via bash for anything not covered by a first-class tool. See the olium tools reference for the full surface.
Provider selection
olium.ResolveProvider picks the backend in this order:
- CLI override (
--provider) - Config file (
agent.olium.providerinvigolium-configs.yaml) - Default →
openai-compatiblewithgemma4:latest(a local Ollama endpoint)
Prompt caching (
EnablePromptCache: true) is set on the engine; only the Anthropic providers and the Codex OAuth provider actually emit cache markers — openai-compatible (including Ollama), openai-api-key, and openai-responses ignore them.
Intensity presets
--intensity bundles several settings; explicit flags always override.
MaxCommands is the autopilot’s own turn cap (the agent’s DefaultAutopilotMaxTurns is 200; intensity overrides it). When the cap is hit the run ends with an error event — the model didn’t get to halt cleanly. agent.olium.max_turns applies to the shorter, non-autopilot engine uses (swarm phases, source analysis, query), not to autopilot.
Halt conditions
The autopilot exits in one of four ways:- Natural halt: model calls
halt_scan. The current turn is allowed to finish; the engine then sees no further tool calls on the next turn and emitsEventRunDone.Result.Halted=true,HaltReasonpopulated. - Quiet halt: model finishes a turn with no tool calls and no
halt_scan. Treated as a natural stop. - Max turns: turn count hits
MaxCommands. Engine emits anEventError; autopilot returns a non-nil error. - Context cancelled: timeout or SIGINT/SIGTERM. Engine teardown cancels in-flight tools.
report_finding in legacy/shadow mode:
- soft warning at 50 findings (still saved)
- hard cap at 200 (rejected with an
IsErrorresult that nudges the model towardhalt_scan)
Findings and candidate persistence
Inlegacy mode, every successful report_finding call writes a finding directly. shadow keeps that behavior and mirrors a candidate. In enforced mode, the operator writes only a candidate; the post-run verifier promotes confirmed candidates.
Promoted and directly reported findings share these fields:
ProjectUUID,ScanUUID,AgenticScanUUID, propagate the project/scan scope sovigolium findingandvigolium agent sessionscan join back.ModuleID = "olium-autopilot",ModuleType = "ai-agent",FindingSource = "autopilot", distinguishes agent-originated findings from scanner-module findings.FindingHash: SHA-256 over (title, severity, source_file, url, description-fingerprint), or over an explicitdedup_keyif the model supplies one. The DB’sON CONFLICThandler squashes duplicates.HTTPRecordUUIDs: therecord_uuidsarray the model passes to link thehttp_recordsthat prove the finding (fromreplay_request’sreplay_record_uuid,web_fetch’srecord_uuid, orquery_records/inspect_record), so the evidence exchange survives the session andvigolium finding --with-recordscan rehydrate it.
AgenticScan status but does not discard the work already saved. Use --resume in shadow or enforced mode to continue the same run.
Session artifacts
For each run, autopilot creates a UUID-named directory underagent.sessions_dir (default ~/.vigolium/agent-sessions/):
AgenticScan.uuid row, so vigolium agent sessions and vigolium log <uuid> both work without extra plumbing. Use --session-dir to pin this directory and --transcript <path> to copy the transcript after the run. Stale dirs older than 48h are swept on startup; orphan PID files are cleared during process cleanup.
Source-aware mode
When--source is set, three things change:
- Source resolution: accepts local paths, git URLs (cloned to a temp dir),
--diff PR-url|ref...ref|HEAD~N, and--last-commits N. The agent gets a local path and (optionally) a list of changed files. - Initial prompt mode hint: the prompt switches between blackbox (“probe the live target”), whitebox (“navigate the source tree”), or a greybox blend (“read the code to find what’s risky, then probe”).
- Skill scope: embedded skills +
~/.vigolium/skills/are indexed in the system prompt; scan-specific skills likeaudit-authandtriage-findingare loadable viaload_skill.
--source is set, freezing its findings into vigolium-audit/ for the operator to consult.
Prior project context and Burp
--prior-context auto is the default. Before this run’s pre-scan, Vigolium summarizes data already in the active project: totals, up to 20 distinct endpoints, and up to 10 open findings. Larger projects get a pointer telling the operator to use query_records and list_findings for the rest, so prompt cost stays bounded.
auto: include the bounded endpoint/finding tables when prior data exists.summary: include totals and a one-line tool pointer.off: do not front-load prior project data.
--burp-bridge-url http://127.0.0.1:9009 (or set VIGOLIUM_BURP_BRIDGE_URL) to import live Burp Proxy history before the brief is built. That makes black-box runs start from captured operator traffic instead of a cold target.
Knowledge base
--knowledge-base <file|dir> supplies application documentation such as authentication flows, roles, privilege tiers, and business rules. Vigolium indexes .md, .markdown, .mdx, .txt, .rst, and .adoc files while skipping binary/vendor trees.
The default path uses one bounded, tool-less LLM call to produce a compact briefing. The opening prompt receives that summary plus an authoritative path index; full documents stay on disk for read_file and grep on demand. Distillation failure is non-fatal and falls back to the deterministic index. The result is cached as knowledge-base-brief.md for provenance and resume reuse.
Use --knowledge-base-raw to skip the distillation call and include only the deterministic index. This is useful for offline or reproducible runs.
Resume
--resume <agentic-scan-uuid> is available only when agent.olium.autopilot_mode resolves to shadow or enforced. It:
- reuses the original AgenticScan UUID, project, target, source path, and session directory;
- restores the scratchpad and candidate ledger;
- marks any section left running by a crash as interrupted; and
- skips native pre-scan, pre-flight discovery, and source-audit preparation.
--prompt if the resumed pass needs extra direction. Resume requires the original database and session artifacts to remain available.
Multi-app fan-out
When the positional prompt parses to multiple apps (vigolium agent autopilot "scan source at ~/src/A, ~/src/B"), the package-level autopilot flags are snapshotted and reapplied per app, then runAutopilotOlium is invoked sequentially for each. Each app gets its own session dir, AgenticScan row, and provider session.
A single-app prompt re-enters runAgentAutopilot directly with the parsed flags, same code path as a flag-driven invocation.
REST API workflow
autopilot.Run on a goroutine, and returns the run UUID immediately.
TL;DR
Autopilot is one autonomous operator bounded byMaxCommands and wall-clock time. Legacy mode keeps one conversation and reports findings directly. Durable modes rotate context through persisted sections, support --resume, and can require a fresh-context verifier before a candidate becomes a finding. Use --prior-context, --burp-bridge-url, and --knowledge-base to start the operator with the evidence and application intent it would otherwise need to rediscover.