Setting Up the Agent - Vigolium Documentation

olium talks to a provider (Claude / OpenAI / a local model), and two specialised drivers, vigolium-audit and piolium, run on top of it for source-code audits.

What	Section	When you need it
olium provider	Olium agent	Always, every agent command needs one provider.
Codex (OpenAI OAuth)	Codex	You have a ChatGPT Plus/Pro/Team subscription.
Claude	Claude	You have a Claude Code subscription (Agent SDK bridge — the default — or the `claude` CLI), an OAuth token, or an Anthropic API key.
Custom LLM backend / local model	Custom LLM backend	You want a local model (Ollama, LM Studio) or a custom OpenAI- / Anthropic-compatible gateway (OpenRouter, vLLM, LiteLLM, …).
Vigolium Audit	Vigolium audit	You want a whitebox source-code audit with no extra install.
Piolium audit	Piolium audit	You want piolium’s 17-phase Pi-native audit (separate install).

All settings live in ~/.vigolium/vigolium-configs.yaml. You can edit it directly, or use vigolium config set <key> <value>.

1. Olium agent, the engine everything runs on

olium is the in-process agent runtime (pkg/olium/) that backs every vigolium agent … subcommand. Setting it up means picking one provider and giving it credentials. The supported providers:

Provider	Auth	Default model	Notes
`openai-compatible` (default)	optional `api_key`	`gemma4:latest` (via `custom_provider.model_id`)	Custom OpenAI-format backend: Ollama, OpenRouter, LM Studio, vLLM, …
`anthropic-compatible`	optional `api_key`	via `custom_provider.model_id`	Custom Anthropic Messages-format backend (self-hosted gateway / LiteLLM proxy).
`openai-codex-oauth`	`~/.codex/auth.json` (from `codex login`)	`gpt-5.5`	Cheapest with a ChatGPT sub.
`anthropic-api-key`	`$ANTHROPIC_API_KEY`	`claude-opus-4-7`	Direct Anthropic API billing.
`anthropic-oauth`	`claude setup-token` bearer	`claude-opus-4-7`	Uses your Claude Pro/Max plan.
`openai-api-key`	`$OPENAI_API_KEY`	`gpt-5.5`	Direct OpenAI API billing (Chat Completions).
`openai-responses`	`$OPENAI_API_KEY`	`gpt-5.5`	Direct OpenAI API billing via the public Responses API (`/v1/responses`).
`anthropic-claude-sdk-bridge`	Claude Code subscription (no key)	Claude Code default	Claude via the Agent SDK; the recommended default Claude path.
`anthropic-cli`	`claude` binary on `$PATH`	`claude-opus-4-7`	Shells out to the Claude Code CLI (alias: `anthropic-claude-cli`).
`anthropic-vertex`	GCP service-account JSON	`claude-opus-4-6`	Claude on Vertex AI.
`google-vertex`	GCP service-account JSON	`gemini-2.5-pro`	Gemini on Vertex AI.

Verify any setup with:

vigolium ol -p 'what model are you running'

If that returns a model name, the provider is wired correctly. From there, vigolium agent autopilot, vigolium agent swarm, etc. all work.

2. Codex, cheapest with a ChatGPT subscription (Recommended)

If you already use OpenAI’s Codex CLI, vigolium reuses the same OAuth credential file. No API key needed, refresh handled automatically.

# 1. Install Codex CLI (one-time) and log in.
codex login
codex exec 'hello'             # sanity check — should print a model name

# 2. Pin vigolium to it (defaults already match; this just makes it explicit).
vigolium config set agent.olium.provider openai-codex-oauth
vigolium config set agent.olium.oauth_cred_path ~/.codex/auth.json
vigolium config set agent.olium.model gpt-5.5

# 3. Verify.
vigolium ol -p 'what model are you running'

~/.codex/auth.json is read on every run; the JWT is auto-refreshed when it expires, so you don’t have to re-login.

3. Claude (Anthropic)

Prefer the official Claude Code client. The recommended way to drive Claude from olium is through Anthropic’s own client — the Agent SDK bridge (anthropic-claude-sdk-bridge, 3a below, the default) or the claude CLI shell-out (anthropic-cli, 3b). Both ride your existing Claude Code subscription through the sanctioned path. The raw OAuth token (3c) and API key (3d) options talk to the Messages API directly — a Pro/Max token used that way lands you in rate-limit / overage territory almost immediately, and the API key bills per token at the highest rates of any provider listed here — so reach for them only if you need direct-API billing (see the warnings on each).

Four options, in order of preference. The first two ride the official Claude Code client; the last two hit the Messages API directly.

3a. Claude Code Agent SDK (`anthropic-claude-sdk-bridge`)

This is the recommended default way to use Claude with vigolium. It drives Claude Code through the Claude Agent SDK by shelling out to the vigolium-audit bridge sidecar (from vigolium/vigolium-audit) — no API key, it uses your logged-in Claude Code subscription. The run is a controlled, reproducible SDK invocation that always loads the vigolium-scanner skill so the agent knows the vigolium CLI.

# 1. Be logged into Claude Code once.
claude          # complete the interactive login

# 2. Point vigolium at the SDK bridge (the default Claude config).
vigolium config set agent.olium.provider anthropic-claude-sdk-bridge
vigolium config set agent.olium.model opus     # optional: opus | sonnet | a full id; omit for the Claude Code default

# 3. Verify.
vigolium ol -p 'what model are you running'

The vigolium-audit binary that hosts the bridge is embedded in vigolium — no separate install. Override it with vigolium config set agent.olium.bridge_binary /path/to/vigolium-audit or the per-run --bridge-bin flag. When agent.olium.llm_api_key / oauth_token is set it’s forwarded to the bridge; otherwise the ambient subscription is used.

Unlike the claude CLI shell-out (3b), the SDK bridge does not load your personal ~/.claude config or a project’s CLAUDE.md — it’s a self-contained, reproducible run that behaves the same on any machine (CI, containers). Pick the CLI shell-out below when you want your full personal Claude Code environment applied to the current directory.

3b. Anthropic CLI (`claude` shell-out)

If you’d rather have vigolium delegate to the claude binary on $PATH (so it uses whatever auth claude itself is configured with, plus your personal CLAUDE.md, MCP servers, and installed skills):

which claude   # must resolve

vigolium config set agent.olium.provider anthropic-cli    # alias: anthropic-claude-cli
vigolium config set agent.olium.model claude-opus-4-7

This mode spawns a fresh claude -p subprocess per turn (slower than the SDK bridge above), but it’s the way to apply your full personal Claude Code environment to the current directory.

Note on permissions. vigolium invokes claude -p with --permission-mode bypassPermissions so Bash / Read / WebFetch tool calls execute without interactive approval (the wrapper is non-interactive, there’s no TTY for you to confirm prompts on). This is equivalent to running claude --dangerously-skip-permissions and applies for the duration of the subprocess only.

3c. Claude OAuth (Claude Pro/Max subscribers)

claude setup-token mints an OAuth bearer token tied to your Claude subscription. No per-token billing.

# 1. Install Claude Code, then mint a token.
claude setup-token                                 # prints sk-ant-oat01-…
export ANTHROPIC_API_KEY=sk-ant-oat01-<your-token> # shell rc; survives reboots

# 2. Point vigolium at the OAuth provider.
vigolium config set agent.olium.provider anthropic-oauth
vigolium config set agent.olium.model claude-opus-4-7

# 3. Verify.
vigolium ol -p 'what model are you running'

anthropic-oauth reads agent.olium.oauth_token first, then falls back to $ANTHROPIC_API_KEY. The env var is the path of least resistance.

Heads-up, enable extra usage on your Claude account. Pro/Max subscriptions ship with the OAuth token capped to the in-app Claude Code allowance. Driving the same token from vigolium (or any third-party client) hits the Messages API directly and is rejected with 429 rate_limit_error until you turn on extra usage / pay-as-you-go overage in the Anthropic Console (Settings → Billing → Usage limits). Without that toggle the verify call above will fail even with a valid token.

3d. Anthropic API key

For users billing through the standard Anthropic API.

export ANTHROPIC_API_KEY=sk-ant-api03-<your-key>

vigolium config set agent.olium.provider anthropic-api-key
vigolium config set agent.olium.model claude-opus-4-7

vigolium ol -p 'what model are you running'

4. Custom LLM Backend (OpenAI/Anthropic Compatible API)

vigolium can drive any custom LLM backend — a cloud gateway or a local LLM API — through two provider drivers that share the same agent.olium.custom_provider config block, differing only in the wire format they speak:

openai-compatible — endpoints that speak the OpenAI Chat Completions format: Ollama, LM Studio, vLLM, OpenRouter, Together, Groq, LocalAI, or any custom proxy.
anthropic-compatible — endpoints that speak the Anthropic Messages (/v1/messages) format: a self-hosted gateway or LiteLLM-style proxy fronting Claude (or other) models.

Both read custom_provider.base_url (required), custom_provider.model_id, an optional custom_provider.api_key (empty = no auth header, for local servers), and custom_provider.extra_headers. Pick whichever matches your backend’s wire format — everything below applies to both.

Ollama (local, no key)

ollama pull gemma4:latest
ollama serve   # if not already running

vigolium config set agent.olium.provider openai-compatible
vigolium config set agent.olium.custom_provider.base_url http://localhost:11434/v1
vigolium config set agent.olium.custom_provider.model_id gemma4:latest

vigolium ol -p 'what model are you running'

Empty api_key means no Authorization header is sent, required for Ollama.

OpenRouter

export OPENROUTER_API_KEY=sk-or-…

vigolium config set agent.olium.provider openai-compatible
vigolium config set agent.olium.custom_provider.base_url https://openrouter.ai/api/v1
vigolium config set agent.olium.custom_provider.model_id anthropic/claude-3.5-sonnet
vigolium config set agent.olium.custom_provider.api_key '${OPENROUTER_API_KEY}'

# Optional: OpenRouter ranking signal (shows your app on the leaderboard).
vigolium config set agent.olium.custom_provider.extra_headers.add 'HTTP-Referer: https://your-site.example'
vigolium config set agent.olium.custom_provider.extra_headers.add 'X-Title: vigolium'

LM Studio

vigolium config set agent.olium.provider openai-compatible
vigolium config set agent.olium.custom_provider.base_url http://localhost:1234/v1
vigolium config set agent.olium.custom_provider.model_id <model-id-from-lm-studio>

Anthropic-compatible gateway

If your backend speaks the Anthropic Messages API (/v1/messages) rather than OpenAI Chat Completions — a self-hosted gateway or a LiteLLM-style proxy fronting Claude — switch the provider to anthropic-compatible. The custom_provider block is identical:

vigolium config set agent.olium.provider anthropic-compatible
vigolium config set agent.olium.custom_provider.base_url https://my-gateway.example.com/v1
vigolium config set agent.olium.custom_provider.model_id claude-3-5-sonnet
vigolium config set agent.olium.custom_provider.api_key '${MY_GATEWAY_KEY}'   # optional; empty = no x-api-key header

vigolium ol -p 'what model are you running'

base_url accepts a full /v1/messages URL, a /v1 root (/messages is appended), or a bare host (/v1/messages is appended). Use extra_headers to switch to a Bearer scheme or pin a specific anthropic-version — entries are applied after the standard headers.

Custom headers (auth, routing, observability)

Some OpenAI- and Anthropic-compatible backends need extra headers, non-Bearer auth schemes, tenant/routing signals, request tagging for cost analytics, etc. extra_headers takes a list of curl-style "Key: Value" entries that are applied after the standard headers, so they can override Authorization (or x-api-key) when needed.

# Clear, then add. Each .add appends one header to the list.
vigolium config set agent.olium.custom_provider.extra_headers.clear ""
vigolium config set agent.olium.custom_provider.extra_headers.add 'X-Custom-ID: your-cli'
vigolium config set agent.olium.custom_provider.extra_headers.add 'Authorization: Bearer custom-api-token'

Or edit ~/.vigolium/vigolium-configs.yaml directly:

agent:
  olium:
    custom_provider:
      extra_headers:
        - "X-Custom-ID: your-cli"
        - "Authorization: Bearer custom-api-token"   # overrides the default Bearer api_key

Notes:

${VAR} references are expanded from the environment when the config is loaded, so credentials don’t need to be checked into the file.
On duplicate keys the last entry wins (matches http.Header.Set semantics).
Malformed entries (no :) are logged at warn level and skipped, the agent keeps running.
To replace the whole list, run .clear "" first, then .add each entry.

You can also pass these as one-shot overrides without touching the config:

vigolium ol \
  --provider openai-compatible \
  --base-url http://localhost:11434/v1 \
  --model gemma4:latest \
  -p 'hello'

extra_headers has no CLI flag, set it once in YAML (or via config set ... .add) and it sticks across runs.

Tool-calling caveat. OpenAI-style function tools are part of the wire format but only some models actually emit them. gemma4, qwen2.5-coder, llama3.1-instruct, and mistral-nemo work well. Smaller models often ignore tool definitions and reply in prose, if the agent never calls tools, switch model.

5. Vigolium audit, source-code driver

vigolium agent audit runs a whitebox source-code audit. The harness (agents, commands, skills) ships embedded in the vigolium binary, no extra install. It drives the claude or codex CLI under the hood (resolved from agent.olium.provider), so you need a working Claude or Codex setup from section 2 or section 3.

# 1. Make sure `claude` (or `codex`) is installed and authenticated.
claude --version
claude -p 'hello'   # sanity check

# 2. Run an audit.
vigolium agent audit --source ~/src/your-app

# 3. Or wire it into autopilot/swarm so it runs automatically when --source is set.
vigolium config set agent.audit.enable true
vigolium config set agent.audit.mode lite          # lite | balanced | deep
vigolium agent autopilot -t https://example.com --source ~/src/your-app

Audit modes: lite (3 phases, CI-friendly), balanced (9 phases, default for --audit=balanced), deep (12 phases, full audit). All produce findings under the same parser/schema as native scanner output and are ingested into the vigolium DB. Findings land under ~/.vigolium/agent-sessions/<scan-uuid>/vigolium-results/. See Agentic Security Audit for the full reference.

6. Piolium audit, Pi-native driver

vigolium agent audit --driver=piolium runs a separate, more thorough audit (17 phases at deep) via the Pi coding-agent runtime. Unlike vigolium-audit, piolium is not embedded, you install it once and vigolium drives the pi binary.

# 1. Install Pi runtime.
bun install -g @earendil-works/pi-coding-agent
pi --version

# 2. Install the piolium extension.
pi install git:[email protected]:vigolium/piolium.git
pi list                                # verify "piolium" appears

# 3. Configure pi's default provider (the audit subprocess uses pi's own auth,
#    not vigolium's). Example with Anthropic:
pi login                               # or: pi /login

# 4. Run an audit.
vigolium agent audit --driver=piolium --source ~/src/your-app                            # balanced (default)
vigolium agent audit --driver=piolium --source ~/src/your-app --mode lite               # quick triage
vigolium agent audit --driver=piolium --source ~/src/your-app --intensity deep          # full 17-phase

# 5. Override pi's provider/model just for this run if you want.
vigolium agent audit --driver=piolium --source ~/src/your-app \
  --pi-provider vertex-anthropic --pi-model claude-opus-4-6

Vigolium runs a one-turn preflight against pi before the audit to catch auth/quota errors early. If preflight fails you’ll see the upstream error (e.g. No API key found for google-vertex. Use /login to log into a provider) and the audit won’t start. By default vigolium uses pi’s per-user install at ~/.pi/agent. To use a system-wide install instead, export PIOLIUM_HOME=/opt/piolium (or any other path). See Agentic Security Audit for modes, intensity presets, and the full flag reference.

vigolium-audit vs piolium

	Vigolium Audit	Piolium
Install	Embedded, zero setup	Requires `pi` + `pi install …`
Driver	`claude` or `codex` CLI	`pi --mode json -p /piolium-<mode>`
Modes	lite (3), balanced (9), deep (12), revisit, confirm, merge, diff, longshot, reinvest, refresh, mock	lite (4), balanced (9), deep (17), revisit, confirm, merge, diff, longshot, smoke
Provider	Whatever `claude` / `codex` is configured with	Whatever `pi` is configured with (separate from olium)
Best for	”I want a source audit, no extra setup"	"I want the most thorough audit available”

You can also run both side-by-side with vigolium agent audit --driver both --source …, that dispatches vigolium-audit then piolium under a single parent scan with project-wide deduplication.

7. Verifying the full stack

After whichever sections you set up, run these in order. Each one fails fast with a useful error if a piece is missing:

# Olium: one prompt, one provider call. No DB, no scan.
vigolium ol -p 'hello'

# Agent query: same path the engine takes for source-code review.
vigolium agent query -p 'list every route in this repo' --source .

# Autopilot smoke test (target-only, no source):
vigolium agent autopilot -t https://example.com --intensity quick --max-duration 5m

# Vigolium audit (requires claude or codex installed):
vigolium agent audit --source . --mode lite

# Piolium audit (requires pi + piolium installed):
vigolium agent audit --driver=piolium --source . --mode lite

If any of these errors out, the message points at the missing piece, usually an unset env var, a wrong agent.olium.provider, or a missing binary.

Where to go next

Olium Agent, what olium is and what its tools do.
Autopilot, autonomous scanning.
Swarm, guided multi-phase scanning.
Agentic Security Audit, vigolium-audit + piolium reference.
Configuration Reference, every config knob with inline docs.

​1. Olium agent, the engine everything runs on

​2. Codex, cheapest with a ChatGPT subscription (Recommended)

​3. Claude (Anthropic)

​3a. Claude Code Agent SDK (anthropic-claude-sdk-bridge)

​3b. Anthropic CLI (claude shell-out)

​3c. Claude OAuth (Claude Pro/Max subscribers)

​3d. Anthropic API key

​4. Custom LLM Backend (OpenAI/Anthropic Compatible API)

​Ollama (local, no key)

​OpenRouter

​LM Studio

​Anthropic-compatible gateway

​Custom headers (auth, routing, observability)

​5. Vigolium audit, source-code driver

​6. Piolium audit, Pi-native driver

​vigolium-audit vs piolium

​7. Verifying the full stack

​Where to go next

1. Olium agent, the engine everything runs on

2. Codex, cheapest with a ChatGPT subscription (Recommended)

3. Claude (Anthropic)

3a. Claude Code Agent SDK (`anthropic-claude-sdk-bridge`)

3b. Anthropic CLI (`claude` shell-out)

3c. Claude OAuth (Claude Pro/Max subscribers)

3d. Anthropic API key

4. Custom LLM Backend (OpenAI/Anthropic Compatible API)

Ollama (local, no key)

OpenRouter

LM Studio

Anthropic-compatible gateway

Custom headers (auth, routing, observability)

5. Vigolium audit, source-code driver

6. Piolium audit, Pi-native driver

vigolium-audit vs piolium

7. Verifying the full stack

Where to go next