Developer & DevOps guide · verified against shipped product

Run Veirox the way
your team works.

Side-by-side CLI and Console workflows for every operational lifecycle: install, onboard, run, integrate, govern.

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

CLI

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
Console

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.

CLI

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
Console

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.

CLI

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>
Console

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.

CLI

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
Console

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.

CLI
# 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
Console

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.

CLI
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"
Console

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.

Console

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.

CLI
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>
Console

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)

CLI
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"}'
Console

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.

CLI

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
Console

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 →

CLI
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"
Console

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.

CLI
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
Console

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.

CLI
veirox audit list \
  --action-prefix auth. \
  --from 2026-05-01 \
  --limit 100

veirox audit stats --days 30
veirox audit export --format csv
Console

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.

CLI
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
Console

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.

CLI
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
Console

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.