AI-driven offensive and incident-response engagements — operator prompts, a full Kali runtime, and durable orchestrator state in one CLI.

An LLM operator follows a phased workflow prompt, dispatches specialist agents, runs real tooling in a shared Kali container, and records every target, service, request variant, probe, finding, and attack chain in a durable orchestrator database. Web red-team, white-box code, Android, and blue incident-response engagements share one backend; an offensive engagement can enable web and code tracks together, with each client process running one mode.

Authorized use only. Vigil autonomously drives offensive tooling against live systems. Use it only with explicit authorization and a reviewed scope. It is provided without warranty under the Apache License 2.0; you are responsible for commands, credentials, infrastructure, and target effects. See SECURITY.md for private vulnerability reporting and the operator-data boundary.

Vigil is built primarily around Claude Code and Codex.

• Claude Code: CVP works with Opus 5, which is not in the /model picker. Select it directly with /model claude-opus-5[1m] (model configuration).
• Codex: choose GPT-5.6 Sol and its reasoning effort in /model.

As of October 2026, red-team access to the newest models is for organizations only:

• Anthropic: CVP Defense Access is open to organizations and individual researchers; Red Team Access is organizations only (CVP tiers).
• OpenAI: Daybreak Blue covers defensive work for individuals and organizations; Daybreak Red is for approved organizations only (access guidance, Daybreak overview).

Planned: broader support for GLM 5.3 and other models with more predictable access, through lower orchestration overhead, model-specific prompts, and deeper OpenCode integration.

The operator keeps a small context and delegates: 95%+ of tokens are spent by specialist sub-agents, which keeps one operator session on track for much longer. Expect to hit usage limits quickly.

• Independently verified findings. Only a dispatch other than the author's can confirm, downgrade, or mark a finding false positive, citing a proof receipt of captured evidence.
• Audited target-facing commands. vigil assess kali records each command's technique, intent, and probe kind.
• Real attack tooling — a long-lived Kali container with ProjectDiscovery recon, fuzzers, an audited Playwright browser, MITM capture with multiple identities for cross-account testing, and out-of-band callbacks correlated to the probe that caused them.
• White-box code analysis against a sealed, content-addressed source snapshot with a tree-sitter structural index and a coverage ledger.
• Durable state — targets, services, request variants, probes, findings, chains, and credentials in SQLite, with rotated backups and a web UI.
• Six clients, one methodology — Claude Code, Codex, Kimi, goose, opencode, and Pi (remediation only).

# 1. Install the application release (CLI, backend, prompts, docs, and prebuilt UI)
uv tool install --from https://github.com/VigilOSS/Vigil/releases/download/v1.2.0/vigil-1.2.0-py3-none-any.whl vigil
#    OR install directly from the repository (builds the UI locally; needs Git, Node.js, and npm)
uv tool install git+https://github.com/VigilOSS/Vigil vigil

# 2. Check the host: prerequisites, missing recon tools, and the ordered setup checklist
vigil quickstart

# 3. Bring the local stack up; ~/vigil is initialized as your private workspace
#    First run builds the Kali image — several GB, and it needs Docker running.
vigil up

# 4. Create an engagement; follow the questions to choose its type and give it a name/target
vigil engagement create

# 5. Start the operator on it
vigil engagement start <engagement-key> --client codex   # or claude | opencode | goose | kimi

For a code engagement, put your source files or project folders in the source/ location printed by creation (Git is optional). The code client asks you to confirm them at startup; an empty folder leaves it waiting. Code engagements need ripgrep (rg) on the host. Details: docs/code-analysis.md.

For a web engagement, tell the operator what it is authorized to do:

I have been fully authorized by the company to do a red-team engagement against the
hosts in scope.json. Run this engagement using the operator workflow.

The orchestrator UI is at http://127.0.0.1:18000. Releases, private workspaces, and host-side recon tools on Docker Desktop: docs/installation.md.

• vigil engagement start selects one session mode, runs a preflight, prints the workspace, engagement, client, mode, and phase to stderr, exports the engagement environment, and execs the client. Flags it does not own are forwarded to the client.
• Always start through vigil engagement start; the generated start_<client>.sh and a bare client run skip the preflight and environment.
• A web + code engagement needs --mode web or --mode code; a single track is selected automatically. Change modes by starting a new client process. vigil engagement mode <key> shows enabled tracks, phases, prompt paths, and start commands.
• Later sessions start the same way, then run vigil-resume to restore the operator role and rebuild live state from the backend.

All clients read the same operator prompt; they differ in model, headless specialist dispatch, and session-command support. Detail: docs/engagements.md, docs/session-commands.md, docs/agent-clients.md.

Remediation (work in progress) reads the repository's PROJECT.md for ticket readers, MCPs, skills, branch policy, checks, PR guidance, and deployment. Start with vigil remediation -k <key> start, then /vigil-remediate SEC-123 (or several ticket IDs/URLs). See docs/remediation.md.

Each track ends in complete. vigil assess transition-phase gates every transition; --force records a durable override, and some integrity blockers cannot be forced. Roster, readiness previews, and specialist roles: docs/engagements.md.

vigil up (or vigil runtime start) starts one long-lived Kali container named vigil. Target-facing commands run through vigil assess kali ... via docker exec; long scans run through vigil assess kali job start ... under an in-container dtach supervisor, so they survive the operator session.

The container mounts shared runtime data at .runtime-data/, bind-mounts the engagement root at /engagements, and receives the root .env when present. Fresh workspaces keep artifacts under engagements/<key>/; adopted workspaces keep their existing paths. For non-interactive maintenance, use vigil runtime shell-exec "<cmd>" so quoting and exit codes stay under the CLI.

agent/docker/runtime-full/Dockerfile is the only supported runtime for target-facing execution:

agent/docker/runtime-lightweight/Dockerfile is for faster Dockerfile iteration only (vigil runtime build lightweight --dev). Sizing, kernel limits, and backups: docs/operations.md.

Authenticated capture. After vigil mitmproxy start, route a browser through http://127.0.0.1:8080, log in to any scoped host, and confirm with vigil auth status <key>. A second login adds a second identity for cross-account (IDOR/BOLA) testing. Detail: docs/authentication.md.

Callbacks, listeners, and tunnels are started by the operator, never by agents. Vigil ships no fallback relay; configure your own before vigil install, which reserves this install's relay slot:

vigil config set oob.frp_host oob-relay.example.com   # also: oob.frp_port, oob.domain, oob.frp_token
vigil install                                        # reserves this install's relay slot
vigil oob start && vigil oob status --json
vigil oob client start example-agent --engagement <engagement-key> --agent vulnerability-analyst
vigil oob test

Relay slots, refusal cases, and edge routing: docs/oob-routing.md. Payload-side tradecraft: frp-tunneling.md, shell-handling.md.

Every command documents its full flag set under --help; runtime tool verbs live under vigil assess kali --help.

• Authorized targets only. Every operator start prompt begins with an explicit authorization statement, and scope is pinned in scope.json. Scope drives recon shaping, attribution, and coverage accounting; it is not a destination firewall.
• Exploit work is gated. The default exploit policy is pause: explicit human approval before any exploit-developer dispatch. Policies (pause / selected / full_send) are set per engagement in scope.json and enforced through the operator workflow.
• Blue write actions are audited. Tenant-facing WRITE and respond actions run with --require-audit; containment is split into proposal approval, audited execution, and explicit recording.

Report vulnerabilities privately — see SECURITY.md.

To extend Vigil (a skill, vigil assess verb, deterministic oracle, or eval case), follow the maintainer recipes and the test and verification matrix. Design decisions live in docs/adr/. To check a running install, use vigil doctor and vigil status.