xalgorixInstall
Linux only. Requires Go 1.24.2 or newer. Node.js + npm are needed only when building the bundled React Web UI from source.
Build from source
git clone https://github.com/xalgord/xalgorix.git cd xalgorix make build sudo install -m 755 build/xalgorix /usr/local/bin/xalgorix
make build compiles the React Web UI into internal/web/static, then builds the Go binary.
Or install with Go
GOPROXY=direct GOSUMDB=off \ go install github.com/xalgord/xalgorix/v4/cmd/xalgorix@latest
Configure
Configuration sources, in order (later overrides earlier): /etc/xalgorix.env → /home/<user>/.xalgorix.env (when launched via sudo) → ~/.xalgorix.env → process environment variables.
Minimal config
# ~/.xalgorix.env XALGORIX_LLM=minimax/MiniMax-M3 XALGORIX_API_KEY=your_provider_api_key
Optional integrations
# Optional integrations GEMINI_API_KEY=AIza... # web-search enrichment AGENTMAIL_POD=am_us_pod_47 # phase 15 email triage AGENTMAIL_API_KEY=ak_... XALGORIX_DISCORD_WEBHOOK=https://discord.com/api/webhooks/... XALGORIX_DISCORD_MIN_SEVERITY=high # Dashboard auth (required before binding to 0.0.0.0) XALGORIX_USERNAME=admin XALGORIX_PASSWORD=change-this-password # prefer XALGORIX_PASSWORD_HASH
Run
Start the dashboard and open it locally:
xalgorix --web # → http://127.0.0.1:9137
Or run a CLI scan without the Web UI:
xalgorix --target https://example.com \ --instruction "Focus on SQLi, IDOR, auth bypass. Avoid destructive tests."
Install as a systemd service:
sudo xalgorix --start sudo xalgorix --restart sudo xalgorix --stop sudo xalgorix --uninstall journalctl -u xalgorix -f
Scan modes
Pick the shape of the engagement; the agent picks the techniques.
Single target
Use it for: Testing one known URL or host.
Flow: xalgorix --target https://example.com — the agent runs against that origin.
Wildcard / multi
Use it for: Enumerating related targets and scanning the discovered attack surface.
Flow: Pass a wildcard or multiple --target flags; the agent enumerates subdomains and fans out one sub-scan per live host.
GitHub App
Install the Xalgorix GitHub App on your repositories to get security reviews on pull requests with no workflow file to maintain. On each PR it posts — and keeps updated in place — a single Xalgorix security review comment.
App vs. Action
- GitHub App — installed once on a repo/org; Xalgorix listens for pull requests and comments the review back. Best for zero-config, org-wide coverage.
- GitHub Action — a workflow you add to your own CI (
.github/workflows/security.yml) that can fail the build on high/critical findings. Best when you want to gate merges. See “Run it on pull requests” in the API docs.
How it works
- Install the app and select the repositories it can access.
- Open or update a PR — Xalgorix reviews the diff and posts a Xalgorix security review comment with any findings. On new commits the auto-review updates that comment in place, so it never spams the PR.
- Comment
@xalgorix reviewanytime to re-run on demand — it reacts 👀 to acknowledge, then posts a fresh review and reacts 🚀 when done.
Free & no account required
Diff-scoped PR reviews are free and need no Xalgorix account or API key — just install the app. It's rate-limited per installation to keep the free tier sustainable. For full exploit-verified pentests and merge gating, add the GitHub Action or use the hosted scanner.
CLI reference
| Flag | Alias | Description |
|---|---|---|
| --web | -w | Start the Web UI on http://127.0.0.1:9137. |
| --port <n> | -p | Web UI port. Default 9137. |
| --bind <addr> | — | Listen address. Default 127.0.0.1. Requires dashboard auth for non-loopback values. |
| --target <url> | -t | Target URL, host, IP, or path. Repeatable. |
| --instruction <txt> | -i | Custom scan instructions (e.g. 'Focus on SQLi and IDOR; avoid destructive tests'). |
| --model <id> | -m | Override XALGORIX_LLM for this run. |
| --update | -up | Update to the latest release. |
| --version | -v | Print version. |
| --start | — | Install and start the system service. |
| --stop / --restart / --uninstall | — | Manage the systemd service. |
Environment variables
A working subset — see the README for the full list (rate limits, proxy, runtime, security, integrations).
| Variable | Default | Description |
|---|---|---|
| XALGORIX_LLM | — | Required model name, usually with provider prefix. |
| XALGORIX_API_KEY | — | Required LLM provider API key. |
| XALGORIX_API_BASE | provider default | Custom OpenAI-compatible API base URL. |
| XALGORIX_REASONING_EFFORT | high | low, medium, high, or xhigh. |
| XALGORIX_LLM_MAX_RETRIES | 5 | Retry count for transient LLM failures. |
| XALGORIX_MAX_ITERATIONS | 0 | Agent iteration cap. 0 = unlimited. |
| XALGORIX_LLM_MAX_INFLIGHT | 4 × max instances | Caps simultaneous outbound LLM calls across all running scans. |
| XALGORIX_DATA_DIR | ~/.xalgorix/data/ | Workspace root for scan output, notes, schedules, and artefacts. |
| XALGORIX_RATE_RPS | 10 | Sustained outbound request rate. |
| XALGORIX_RATE_BURST | 20 | Outbound burst size. |
| XALGORIX_USE_PROXY | false | Enable proxy routing. |
| XALGORIX_PROXY_FILE | — | File containing one proxy per line. |
| XALGORIX_PROXY_ROTATION | roundrobin | roundrobin or random. |
| XALGORIX_DISABLE_BROWSER | false | Disable browser automation. |
| XALGORIX_BROWSER_PATH | auto | Custom Chrome / Chromium executable path. |
| XALGORIX_ALLOW_AUTO_INSTALL | root only | Permit automatic package installation. |
Provider prefixes
When XALGORIX_API_BASE is empty, Xalgorix infers the provider's default API base from the model prefix. Model names are not hard-coded — type any model ID the provider supports.
| Prefix | Default API base |
|---|---|
| openai/ | https://api.openai.com/v1 |
| anthropic/ | https://api.anthropic.com |
| deepseek/ | https://api.deepseek.com/v1 |
| groq/ | https://api.groq.com/openai/v1 |
| google/ | https://generativelanguage.googleapis.com/v1 |
| gemini/ | https://generativelanguage.googleapis.com/v1 |
| ollama/ | http://localhost:11434/v1 |
| minimax/ | https://api.minimax.io/v1 |
Local REST API
Served by the same process on the dashboard's bind address (default 127.0.0.1:9137). Use these endpoints to script scans, integrate with your own UI, or build a SIEM pipeline.
| Method | Endpoint | Purpose |
|---|---|---|
| POST | /api/scan | Start or save a scan. |
| POST | /api/stop | Stop all running scans. |
| POST | /api/restart | Schedule a graceful backend restart. Waits until the scanner is idle (no active scans/instances) before restarting; in-flight work auto-resumes. |
| GET | /api/status | Global status, panics recovered, watchdog kills, llm_inflight_cap, data_dir, allow_list. |
| GET | /api/scans | List scans. |
| GET | /api/scans/:id | Get scan detail. |
| DELETE | /api/scans/:id | Delete a scan and its report data. |
| GET | /api/report/:id | Download a branded PDF report. |
| GET | /api/instances | Live and historical instances. |
| GET | /api/instances/:id/events | Buffered event history for an instance. |
| POST | /api/instances/:id/start | Start a saved or completed scan as a new run. |
| POST | /api/instances/:id/restart | Restart with the same configuration. |
| POST | /api/instances/:id/pause | Pause a running scan. |
| POST | /api/instances/:id/resume | Resume a paused scan. |
| POST | /api/instances/:id/stop | Stop a specific instance. |
| POST | /api/upload-logo | Upload a report logo. |
| POST | /api/upload-targets | Upload a target list. |
| GET | /api/settings/environment | List editable environment settings. |
| POST | /api/settings/environment | Save environment settings. |
| GET | /api/settings/llm | Get LLM settings. |
| POST | /api/settings/llm | Save LLM settings. |
| GET | /api/settings/agentmail | Get AgentMail settings. |
| POST | /api/settings/agentmail | Save AgentMail settings. |
| GET | /ws | WebSocket live event stream — tool calls, agent messages, findings, errors, HTTP, LLM activity. |
WebSocket event stream
Connect to ws://127.0.0.1:9137/ws to receive a live feed of tool calls, agent messages, findings, errors, HTTP activity, and LLM activity.
# Tail the live feed with websocat websocat ws://127.0.0.1:9137/ws
Safety notes
- Use Xalgorix only against targets you own or have explicit written permission to test.
- Review scan instructions before launching; tune
XALGORIX_RATE_RPSand proxy settings to match engagement rules. - Exposing the dashboard externally requires authentication — the server refuses non-loopback binds otherwise.
- Auto-install is disabled by default for non-root users; enable it only when you trust the host.
- The scope guard now blocks tool calls against hosts that aren't a configured target or subdomain, including the dashboard's own listener.
FAQ
Ready to spin it up?
Clone the repo, set two env vars, and you have a local AI pentesting dashboard.