1 · Orientation
Veirox is a single Claude-powered agent that runs your DevOps workflows. The same agent — the same memory, knowledge, approvals, and audit — answers in three places:
Console
Browser at /console/. Best for chat, dashboards, knowledge editing, governance.
CLI
Terminal at your shell. Best for CI, scripts, live tail, idempotent triggers, MCP wiring.
Channels
Slack, Telegram, WhatsApp, voice. Best for on-call and mobile interactions.
This guide focuses on CLI + Console. Channel setup lives under Integrations.
2 · Install
Get the binary
Pick a package manager — Homebrew, Scoop, curl|sh, or Docker. See the CLI install page for all options.
brew install veirox-cloud/veirox/veirox veirox version veirox doctor
Open in a browser
No install needed — the console is a static SPA hosted at /console/. First visit redirects to the login screen at /console/login.
open https://console.veirox.com/
First account: the very first user to sign in is the org owner. They can invite teammates from /console/<org>/settings/members or by sharing a magic-link via the Console settings.
3 · Onboard a project
Every resource — tasks, secrets, sessions, runbooks — lives in a project. Projects are isolated tenants; nothing crosses between them.
veirox init
Detects local context (git remotes, kubectl context, AWS profile), creates a project, seeds starter runbooks, and wires up your local agent client (Cursor, Claude Code, Codex…).
veirox login veirox init --project payments-api # Resume a flow that was interrupted veirox init --resume
New project wizard
From /console/projects, click New project. The wizard walks through name → slug → optional connectors → review.
- → Pick a colour for the project (used in tags / badges)
- → Optionally seed runbooks from the marketplace
- → Optionally invite teammates by email
4 · Chat with the agent
A "session" is one conversation with the agent. The same agent identity answers in chat, runs scheduled tasks, and processes webhook alerts — they all share memory.
veirox agent run
One-shot prompt. With --follow, streams the resulting session live until completion.
veirox agent run "check prod-api error rate" --follow # Cancel an in-flight session veirox agent cancel <session-id>
Chat at /console/<org>/chat
Three-pane layout: session list (left), transcript with tool-call cards (centre), artifacts & entity sidebar (right). Inline approval buttons appear when the agent requests permission.
- → Pin sessions you want to keep around
- → Fork a session to explore an alternate path
- → Export a session to Markdown or PDF
5 · Tasks & schedules
Tasks are reusable agent runs with a configured prompt and trigger. Three trigger sources: manual, cron, and webhook.
veirox task
# Browse + filter veirox task list --enabled --limit 20 # Create a daily task veirox task new \ --name "morning prod check" \ --cron "0 9 * * *" \ --prompt "@runbook morning-check" # Trigger from CI with idempotency veirox task run <task-id> \ --idempotency-key "$BUILD_ID" \ --wait
Tasks at /console/<org>/tasks
- → Templates tab — install pre-built tasks (auto-remediator, alert investigator, change correlator, cost monitor)
- → New task — visual cron picker with preview, prompt editor, channel/repo links
- → Each task has a public webhook URL (configurable) for inbound triggers
- → Per-task Sessions tab shows every run with its outcome
6 · Live sessions & logs
Every session emits a Server-Sent Event stream — text deltas, tool calls, approvals, completion. Both surfaces consume the same stream.
# Charm UI for the latest active session veirox tail # Stream by id veirox logs <session-id> --follow # ndjson for jq pipelines veirox logs <id> --follow --plain \ | jq -r 'select(.type=="text") | .text' # Poll-based watch over lists veirox watch tasks veirox watch sessions veirox watch connectors
Live transcript
Open any session at /console/<org>/sessions/<id> while it's running. Tool calls render as collapsible cards; approval requests pop a modal.
- → Two viewers can watch the same session simultaneously
- → Cancel and retry are one-click
- → Token / tool / latency metrics shown per turn
7 · Human-in-the-loop approvals
When the agent wants to do something risky — destructive command, sensitive write — it pauses and asks. Configure must-always / must-never rules in agent settings; everything else is on-the-fly.
veirox approval list --limit 25 veirox approval info <id> # Approve / reject from the terminal veirox approval approve <id> \ --comment "lgtm — checked diff" veirox approval reject <id> \ --comment "wrong window"
Approvals queue
Browse pending decisions at /console/<org>/approvals. Inline approval buttons also appear in chat, Slack, and Telegram — same backing record.
- → Public read links for one-off external reviewers
- → Threaded comments per approval
- → Mark resolved when the action is no longer relevant
8 · Knowledge, memory, and skills
The agent reads your runbooks, memory files, and skill definitions on every turn. They're plain Markdown under the project workspace's .claude/ tree — version-controllable, diffable, reviewable.
Runbooks
Step-by-step procedures the agent invokes via @runbook <name>. Edit at /console/<org>/runbooks.
Memory
Long-lived notes the agent updates itself (people, services, recurring incidents). Edit at /console/<org>/memory.
Skills
Reusable agent macros — describe how to do a thing once. Edit at /console/<org>/skills.
9 · OAuth integrations
Five OAuth providers ship today: Google Workspace, Microsoft 365, Slack, Jira, Confluence. Connect once at the project level; the agent gets read/write access scoped to your account's permissions.
Connect at /console/<org>/integrations
Click the provider tile, approve the OAuth dialog, optionally narrow scopes. Tokens are encrypted at rest with the project's secret vault key.
CLI parity for OAuth flows is on the roadmap — for now use the console for the initial grant.
10 · Webhooks
Nine providers with verified signatures: AlertManager, Grafana, Datadog, Sentry, PagerDuty, GitHub, GitLab, Stripe, plus a generic HMAC-SHA256 receiver. Each provider knows its signature scheme, dedup key, and resolved-event signal.
veirox webhook list veirox webhook providers veirox webhook events --limit 50 # Send a test event veirox webhook test <config-id> \ --body-json '{"alertname":"Smoke"}' # Replay a delivered event veirox webhook replay <event-id>
Webhooks at /console/<org>/webhooks
Click New webhook, pick a provider, paste sample payload to validate, copy the URL into your alerting tool.
- → Event timeline per webhook with replay + drilldown
- → Routing rules: priority, fan-out, approval-gated dispatch
- → Privacy controls: redaction rules, metadata-only mode, payload purge
Step-by-step provider guides: AlertManager · Grafana · PagerDuty
11 · MCP — both directions
Veirox speaks the Model Context Protocol on both sides. in Register external MCP servers your agent calls. out External agents (Claude Code, Cursor, Codex) call Veirox.
11a · External MCP servers (your agent calls them)
veirox mcp list veirox mcp register \ --name "slack-extra" \ --transport stdio \ --command "mcp-slack" veirox mcp tools <server-id> veirox mcp test <id> <tool> \ --input '{"channel":"#ops"}'
MCP servers at /console/<org>/mcp-servers
Add stdio or streamable-HTTP servers. The console pings each on save and renders the tool catalogue.
11b · Drive Veirox from external agents
The MCP-EXT server publishes 100+ curated tools plus an auto-bridge for every tagged FastAPI route — over 200 tools available externally, gated by your API key's scopes and per-key tool allow-list.
veirox mcp setup
Wires Cursor (deeplink), Claude Code / Codex (CLI handoff), Continue / Claude Desktop (snippet) in one go.
veirox mcp setup \ --client cursor \ --client claude-code \ --client codex veirox mcp print --client claude-desktop veirox mcp doctor
API & MCP Access
Mint an API key at /console/<org>/settings/api-keys. The reveal modal generates copy-paste config snippets for every supported client + a "Try it" button that previews the tool list.
12 · Veirox Connect — reach your private infra
Install a tiny outbound-only agent on any Linux host or Kubernetes cluster you want the agent to reach. The connector dials out, registers, and accepts tunnelled commands gated by per-connector policy. Full install guide →
veirox connector list veirox connector add "prod-bastion" \ --description "prod jumpbox" \ --label env=prod # Mint a one-time enrollment token veirox connector enroll <id> # See what was tried + denied veirox connector logs <id> veirox connector policy show <id> veirox connector policy simulate <id> \ --command "systemctl status nginx"
Connectors at /console/<org>/connectors
- → Mint enrollment token button — copy, paste into the install command
- → Per-connector live status, command log, auth-event timeline
- → Policy editor with simulator — test rules before saving
- → Policy groups — apply floors across many connectors
- → Three-layer tenant verification on every command
13 · API keys & RBAC
Org-scoped, non-human credentials with format ops_k_…. Plaintext is shown once at create / rotate. Database stores only the prefix and SHA-256 hash.
veirox api-key list veirox api-key create \ --name "ci-pipeline" \ --role member \ --scope tasks:trigger \ --project-id <uuid> \ --ttl-days 90 veirox api-key rotate <id> veirox api-key revoke <id> --yes
API & MCP Access
At /console/<org>/settings/api-keys: list, create, rotate, revoke. Three-mode tool allow-list ("all my scopes" · "pick specific tools" · "use template") and a per-mount tool-list preview.
Roles: viewer · member · admin · owner. Scopes layer on top — see services/auth/rbac.py for the full ladder.
14 · Audit log
Every state-mutating action is recorded in a partitioned, append-only audit log (SOC2 CC6.1 / CC7.2). Admins and owners can list, filter, and export.
veirox audit list \ --action-prefix auth. \ --from 2026-05-01 \ --limit 100 veirox audit stats --days 30 veirox audit export --format csv
Audit at /console/<org>/settings/audit
- → Filter bar: action, actor, resource, date range
- → Per-row metadata viewer (with secrets scrubbed)
- → Stats panel + CSV export
15 · Data governance
Per-entity retention TTLs, GDPR Article 17/20 (export & erasure) workflow, and an auto-discovered PII inventory.
veirox governance retention list # 90-day TTL for sessions veirox governance retention set sessions \ --days 90 --archive-to-s3 # File a Data Subject Request veirox governance dsr create \ --subject-email user@example.com \ --request-type erasure veirox governance pii-inventory
Governance at /console/<org>/settings/governance
- → Retention policy table with TTL sliders + archive toggle
- → DSR queue with state transitions
- → PII entity inventory and field-level redaction rules
16 · Cost & billing
Atomic cost ceilings prevent runaway spend; daily rollovers reset the budget. Plans, subscription, invoices, and Stripe customer portal all live under billing.
veirox billing plans veirox billing subscription veirox billing invoices --limit 12 veirox billing portal # Stripe portal URL veirox dashboard usage summary veirox dashboard usage trend
Billing at /console/<org>/settings/billing
Plan selector, usage chart, invoice list, change/cancel/resume flows. Cost-ceiling configuration is in agent settings under "Limits".
17 · CLI cheat sheet
Persistent flags work on every command:
-p, --profile <name> active profile (env VEIROX_PROFILE) --workspace <url> override workspace URL --org <slug> override default org --project <slug> override default project -o, --output <fmt> pretty | json | yaml | table --no-color disable ANSI colors --no-interactive force non-interactive mode (CI) --idempotency-key <k> override the auto-generated Idempotency-Key --debug verbose stderr logs
All 36 commands are listed on the CLI install page. Every command supports --help.
18 · Troubleshooting
CLI says not authenticated
Run veirox login. If you have multiple workspaces, pass --workspace https://veirox.acme.com --profile work. The OS keyring stores one entry per profile.
CLI version doesn't match backend
The CLI checks /api/version on first call per session. Update via your package manager — for Homebrew: brew upgrade veirox; for Scoop: scoop update veirox; for Docker: pull a new tag.
A connector won't come online
veirox connector logs <id> shows the most recent commands and exit codes. veirox connector auth-events <id> shows handshake failures. The connector needs outbound 443 to the Veirox backend.
Webhook events not arriving
veirox webhook events --limit 50 shows the last 50 deliveries (signed or unsigned). For a specific provider, check the per-provider page (e.g. AlertManager) for signature scheme and dedup-key configuration.
Cost ceiling hit (402)
The org's daily ceiling is exceeded. veirox billing portal opens the Stripe portal to upgrade; admins can also raise the ceiling in agent settings under "Limits".
Stuck on something specific?
Open a GitHub issue, or just ask the agent — it has access to its own docs.