Documentation
This quick start takes you from an empty terminal to your first approved, deployed configuration on Veltrix. Veltrix is a Security-as-Code platform: you author a security tool's configuration as code, then drive it through an approval-gated pipeline — validate → deploy → rollback → health-check → drift-detect → status. Everything below works the same whether you run on hosted SaaS or the free, self-hostable Community Edition.
This guide uses the veltrix CLI against an existing tenant. If you need to stand up your own self-hosted platform first — OS, Docker, and port requirements included — see the Installation Options guide.
Veltrix runs two ways, and apps and configurations behave identically on both:
A key's role decides what it can do. Deploying configuration needs configuration-canvas:write; the sandbox dev loop needs sandbox:read / sandbox:write (an administrator key covers both). Give each developer their own key — sandbox quota is tracked per key.
Install the CLI globally from npm:
npm install -g @veltrixsecops/cliAuthenticate against your tenant. Pass your platform URL and paste your API key when prompted:
veltrix login --url https://app.veltrixsecops.com
The key is verified against the platform and stored in ~/.veltrix/config.json (mode 600). Confirm who you are — this prints the authenticated tenant and the key's scopes:
veltrix whoami
The VELTRIX_API_KEY and VELTRIX_URL environment variables override the stored profile, so a build agent can skip veltrix login entirely.
A Veltrix app teaches the platform how to manage one tool's configuration as code. If you're building or customizing one, this is the inner loop. (Just using apps someone else built? Skip ahead to Connect a Tool.)
veltrix init pulls the canonical app layout and rewrites its identity to your app id:
veltrix init crowdstrike-edr
cd crowdstrike-edr && npm install
Each configuration type your app declares implements the pipeline handlers — validate, deploy, rollback, healthCheck, driftDetect, and getStatus — against the typed contract in @veltrixsecops/app-sdk:
npm install --save-dev @veltrixsecops/app-sdkSee App Development for the full walkthrough of the handlers, the manifest, and the canvas schema.
Run the exact checks CI enforces on every pull request — manifest schema, handler completeness, import boundaries, and the size cap:
veltrix validateA sandbox runs your work-in-progress app inside your own tenant. Create one, then start the two-way dev loop — every local save is validated and synced up, and edits made in the portal's in-browser editor sync back down to your files in near-real time:
veltrix sandbox create crowdstrike-dev --app crowdstrike-edr
veltrix dev --sandbox crowdstrike-dev --create
Sandboxes require a tenant with SANDBOX_ENABLED and a key authorized for sandboxes.
When the app works, deploy a configuration through the pipeline (approval-gated — see below), and check whether a live target has drifted from what you deployed:
veltrix deploy crowdstrike.deploy.yaml --wait
veltrix drift check <canvasId>To manage a real tool, install its app and give it a credential to authenticate with.
Open the Apps page in your tenant and enable an app from the marketplace catalog (platform administrators install and upload apps; tenants enable the ones available to them). The catalog lists 96 apps across SIEM, EDR, SOAR, IAM, Network, Cloud Security, Compliance, Endpoint Management, and Threat Intelligence.
Go to Settings → Connections, add a credential for the app (its endpoint plus an API token or client id/secret), and click Test. The app runs one lightweight authenticated probe and reports whether the credential works.
Create a dedicated API account in each tool for Veltrix, for clean access control and audit trails. Secrets are encrypted at rest and resolved server-side only — the platform never returns a decrypted credential to the browser.
With an app installed and a connection in place, you can deploy configuration as code. A deploy spec is a small YAML file describing what to push:
name: "Okta API Test Group"
app: okta-identity # the installed app's id
configType: groups # a configuration type the app declares
environment: LocalBabong # environment name OR its Tag id
approvers: # who must approve — emails or user ids
- lead@example.com
sections: # the canvas content for this config type
- name: Group
fields:
- { key: name, label: Name, fieldType: text, value: "Veltrix API Test Group" }
- { key: description, label: Description, fieldType: text, value: "Created via veltrix deploy" }Deploy it. The CLI creates a draft canvas, validates it, and submits it for approval — it never self-approves:
veltrix deploy okta-groups.deploy.yaml
Every deploy is gated on a human — the pipeline refuses to deploy anything not yet approved. Add --wait to poll until an approver signs off in the portal, then deploy and stream the deployment to completion in one command:
veltrix deploy okta-groups.deploy.yaml --waitOnce an approver signs off in the portal, the configuration deploys to the tool. From there the platform health-checks the result and can watch it for drift on a schedule.
You've installed the CLI, connected a tool, and deployed a configuration through the approval-gated pipeline. Where to go from here:
Every veltrix command and flag — sandbox, deploy, config, and drift.
The typed app contract in @veltrixsecops/app-sdk — contexts, results, and manifest.
The full walkthrough of the six handlers, the manifest, and the canvas schema.
Understand the change pipeline, environments, and governance features in depth.
See supported vendors and install additional apps from the marketplace.
Give AI agents scoped keys and keep humans on the approval gate.
96 apps span SIEM, EDR, SOAR, IAM, Network, Cloud Security, Compliance, Endpoint Management, and Threat Intelligence. Browse them on the Apps page, or consume the published catalog directly:
https://captivatortechnologies.github.io/veltrix-apps/catalog.jsonIf you need additional assistance, there are several resources available:
Was this documentation helpful? Let us know how we can improve it.