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-M2.7 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.
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.