Skip to main content
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.
The autopilot is exactly that, except the analyst is an LLM and the durable notebook is the project database plus the run’s session directory.

Lifecycle (high-level)


Execution modes

Set agent.olium.autopilot_mode in vigolium-configs.yaml:
Durable sections rotate after 40 turns or 12 consecutive turns without progress. A new section resets the engine and reconstructs a concise brief from the scratchpad, previous closing note, candidate ledger, and recent actions. Section lifecycle events are appended to 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:
  1. CLI override (--provider)
  2. Config file (agent.olium.provider in vigolium-configs.yaml)
  3. Default → openai-compatible with gemma4:latest (a local Ollama endpoint)
Supported provider IDs: 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:
  1. 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 emits EventRunDone. Result.Halted=true, HaltReason populated.
  2. Quiet halt: model finishes a turn with no tool calls and no halt_scan. Treated as a natural stop.
  3. Max turns: turn count hits MaxCommands. Engine emits an EventError; autopilot returns a non-nil error.
  4. Context cancelled: timeout or SIGINT/SIGTERM. Engine teardown cancels in-flight tools.
A separate finding rate-limit lives inside report_finding in legacy/shadow mode:
  • soft warning at 50 findings (still saved)
  • hard cap at 200 (rejected with an IsError result that nudges the model toward halt_scan)

Findings and candidate persistence

In legacy 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 so vigolium finding and vigolium agent sessions can 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 explicit dedup_key if the model supplies one. The DB’s ON CONFLICT handler squashes duplicates.
  • HTTPRecordUUIDs: the record_uuids array the model passes to link the http_records that prove the finding (from replay_request’s replay_record_uuid, web_fetch’s record_uuid, or query_records/inspect_record), so the evidence exchange survives the session and vigolium finding --with-records can rehydrate it.
Persisted findings, candidates, sections, records, and scratchpad state survive a crash or timeout. A failed run updates the parent 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 under agent.sessions_dir (default ~/.vigolium/agent-sessions/):
The run UUID matches the 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:
  1. 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.
  2. 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”).
  3. Skill scope: embedded skills + ~/.vigolium/skills/ are indexed in the system prompt; scan-specific skills like audit-auth and triage-finding are loadable via load_skill.
Vigolium-audit also runs first (foreground) when --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.
Pass --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.
The original free-text prompt is not replayed. Add a new --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

The HTTP request body covers the core target, source, focus, auth, intensity, and audit controls, but it does not expose every CLI-only preparation/debugging flag. The handler resolves provider/source, enters autopilot.Run on a goroutine, and returns the run UUID immediately.

TL;DR

Autopilot is one autonomous operator bounded by MaxCommands 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.