Stability promise

Applies from 1.0

This promise starts with v1.0.0. A 0.x release promises nothing: it can change or remove anything, and its release notes say what moved.

Versions

An install has one version, vX.Y.Z. The footer and Settings > About show it. The veltro CLI, the veltro Helm chart and the sign-in service’s image are published at that same version. Both client SDKs ship with the sign-in service’s own release instead, at its version (see SDKs).

Each product’s images and Helm charts keep their own version numbers. About lists them for support, but they’re outside this promise.

The install version has major, minor and patch numbers, as in Semantic Versioning. One thing differs: every release picks up the product releases published since the last one, so a patch can add features too.

Release	Can	Can’t
Patch, 1.0.x	Fix bugs and security issues. Pick up new product releases	Break or deprecate anything this page covers
Minor, 1.x.0	Add endpoints, tools, commands, flags and values. Deprecate something	Break anything this page covers
Major, 2.0.0	Remove or change something this page covers, once a 1.x minor has deprecated it

Breaking changes

A change is breaking when a script, client or config file that worked against something this page covers stops working, or starts doing something different. That includes:

• removing or renaming an endpoint, a response field, an MCP tool, a CLI command or flag, a Helm value, or an SDK class or method
• a new required input: a request field, tool argument, flag or Helm value with no default
• changing the type or meaning of a field, argument, flag or value, or accepting fewer values than before
• asking for a credential or token scope that a call didn’t need before

These aren’t breaking, so write clients that cope with them:

• new endpoints, tools, commands, flags and values
• new optional inputs
• new fields in a response, and new values in a field that returns one of a fixed set (ignore what you don’t recognise)
• different wording in messages, CLI output and tool descriptions
• a fix that makes something do what its docs already said

Two exceptions can land in a 1.x release. A security fix that can’t keep something working safely may refuse what used to be accepted, and its release notes say so under a Breaking heading. And a minor release may stop supporting a Python or Node.js version its upstream no longer supports, once an earlier minor has deprecated it.

Deprecation

A 1.x minor release deprecates anything this page covers before a major release removes or changes it. The release notes and the changelog list it under Deprecated and name what to use instead. It keeps working for the rest of 1.x, and at least one more minor release ships before the major that removes it.

veltro upgrade --dry-run reads the target release’s notes and the notes of each product release it pins, and warns when any of them has a Breaking or Migration heading. Read those sections before you upgrade.

Every release also checks them. It publishes its public surface as veltro-suite-<version>.surface.json: each product’s SDK operations with their required inputs, the MCP tools with their required inputs, the veltro commands and flags, and the Helm chart’s values keys (image repositories and tags aside). Before the release reaches the homelab or GitHub, the workflow compares that file with the previous release’s. A removed or renamed operation, a new required parameter, a removed tool, command, flag or values key, or a new required tool input or flag stops the release, and the log names each one. Only a major release passes with those. Experimental items aren’t in the file, so they can change freely. The check started with the 0.x releases, where it only records what changed.

Experimental

A feature marked experimental is outside this promise, and any minor release can change or remove it. Nothing is marked today. When something is, you’ll see it in these places:

• Docs. The page or section that describes it carries an Experimental callout.
• REST APIs and the SDKs. The operation’s OpenAPI entry has x-veltro-experimental: true. The generated Python method’s docstring and the TypeScript method’s JSDoc say it’s experimental, and the TypeScript one carries an @experimental tag your editor shows.
• MCP. tools/list gives the tool _meta: {"veltrosecurity.com/experimental": true}, and its description starts with Experimental:.
• CLI. --help ends the command’s or flag’s description with (experimental).

Products mark an operation in one line. VectorFlow passes experimental: true when it registers a v1 route in its OpenAPI spec. Sigmatic and Warden add openapi_extra=EXPERIMENTAL (from app.api.experimental) to the route decorator.

What’s covered

REST APIs

Product	Covered	Credential
VectorFlow	Everything under /vectorflow/api/v1 (VectorFlow API)	An environment’s service-account key
Sigmatic	The operations under /sigmatic/api/ that the SDKs bind (Sigmatic API), and the ingest API log shippers call (Send logs)	A personal access token. Ingest takes the data source’s own token
Warden	The operations under /warden/api/ that the SDKs bind (Warden API), and the endpoints generic webhook sources receive on (Integrations)	A personal access token. A webhook source takes its own token

Sigmatic’s and Warden’s APIs have no version in the path. Every identity release regenerates the SDKs from each product’s newest release, so the operations the 1.0.0 SDKs bind are the starting set. Every later 1.x release keeps those, plus whatever a 1.x SDK has bound since.

The sign-in service has no REST API for your scripts. These parts of it are covered, because other clients call them:

• the sign-in calls the SDKs make, GET /api/auth/csrf and POST /api/auth/login
• SCIM 2.0 at /api/scim/v2, for your identity provider
• the OAuth endpoints MCP clients discover from /.well-known/oauth-protected-resource/mcp
• personal access tokens as bearer tokens on the Sigmatic and Warden APIs

Health checks are covered too:

• GET /api/health and GET /api/health/ready on the install’s address. Both answer for the sign-in service: 200 with "status": "ready" when it’s ready, and 503 with "status": "not_ready" and a reason when it isn’t. The gateway’s Kubernetes probes use /api/health/ready.
• GET /vectorflow/api/health/ready: 200 with "status": "ok" when VectorFlow can reach its database, and 503 with "status": "error" when it can’t.

Not covered:

• the internal endpoints under /api/peer/, /api/external/, /api/authority/, /api/chrome/ and /api/account/
• VectorFlow’s tRPC API under /vectorflow/api/trpc/
• the API the VectorFlow agent uses. The agent keeps its own version, and each release’s notes say which agent versions it supports

MCP

The endpoint at /mcp and the ways to sign in to it (MCP) are covered, along with:

• Tool names. A tool keeps its product prefix (vf_, sigmatic_, warden_) whichever products are installed, and veltro_list_approvals keeps its name too.
• Each tool’s inputs, under the rules in Breaking changes. A tool’s result follows the same rules as a REST response: fields can be added, not removed.
• The resource URIs vectorflow://pipelines/{id}, sigmatic://alerts/{id}, warden://cases/{id} and warden://runs/{id}, for the installed products.
• Token scope names such as sigmatic:alerts:read, because tokens you’ve already created carry them. Which scopes you can pick depends on the installed products.

A tool is listed only when its product is installed and your token and grants allow it. A tool that’s hidden for one of those reasons hasn’t been removed.

Not covered: tool descriptions, prompts, and the server’s name and instructions, which change with the installed products.

SDKs

The Python veltro-sdk and the TypeScript @veltrosecurity/sdk are published with each release of the sign-in service, identity/vX.Y.Z, at its version (Client SDKs). Covered:

• what each package exports at the top level: the client classes, credentials and error types
• the resource and method names on each product client. They come from the product’s OpenAPI operation ids, so a renamed operation id breaks the SDK the same way a removed endpoint does
• the runtimes: Python 3.10 or later, and Node.js 22 or later, until a minor release drops one as described under Breaking changes

An SDK’s version doesn’t follow your install’s. An older 1.x SDK keeps working against a newer 1.x install. A newer SDK can list operations your install’s products don’t serve yet, and calling one of those fails.

The CLI

veltro-cli is published at the install’s version (The veltro CLI). Covered:

• every command, and every flag its --help lists, apart from install --skip-up, which exists for tests
• the exit status: zero on success, non-zero on failure
• the product selection: --products and VELTRO_PRODUCTS take a comma-separated subset of vectorflow,sigmatic,warden, empty means the core alone, and unset means all three
• the one-line install.sh and its VELTRO_RELEASE variable
• these .env settings: PUBLIC_BASE_URL, VELTRO_HTTP_PORT, VELTRO_TLS_MODE, VELTRO_TLS_HTTP_PORT, VELTRO_HTTPS_PORT, VELTRO_TLS_INGEST_PORT, SIGMATIC_INGEST_BIND_ADDRESS, SUITE_POSTGRES_MAX_CONNECTIONS, SUITE_REDIS_MAXMEMORY, BACKUP_DIR, BACKUP_KEEP, BACKUP_CRON, PROMETHEUS_PORT, ALERTMANAGER_PORT, GRAFANA_PORT, GRAFANA_ROOT_URL and GRAFANA_ADMIN_USER. Secrets and the settings that wire services together aren’t covered

veltro upgrade keeps .env and veltro.toml. It replaces the other files an install is made of, such as the compose files, the gateway configuration, versions.env and scripts/, so edits to them are lost.

Not covered: the wording and layout of CLI output, what --dry-run prints, and the Make targets and scripts in a clone.

Helm values

The veltro chart at oci://ghcr.io/veltrosecurity/charts/veltro is published at the install’s version (Kubernetes). Covered:

• the values in the chart’s own values.yaml, apart from image repositories and tags, which each release sets
• the product-chart values the Kubernetes guide tells you to set, such as sigmatic.suite.authority.issuer

Not covered: the rest of the VectorFlow, Sigmatic and Warden charts’ values, which belong to those charts and their versions; the identity, gateway and monitoring charts installed on their own; and the names Helm gives resources.

Backups

A backup restores into the release that took it. Restore refuses a backup from a newer release, so restore first and then upgrade (Backup and upgrade).

Not covered

• Product images, product Helm charts and their versions
• The internal packages: @veltrosecurity/tokens, @veltrosecurity/ui, @veltrosecurity/shell, @veltrosecurity/suite-auth, veltro-suite-auth, @veltrosecurity/ai and veltro-ai. They keep their own versions
• The web interface: layout, navigation, wording, and page URLs inside a product. The product paths /vectorflow, /sigmatic/ and /warden/ stay
• Compose service and container names, database schemas and Redis keys
• Anything marked experimental (see Experimental), and anything this page doesn’t list

Upgrading between 1.x releases

An upgrade is supported from any release of the previous 1.x minor, or an earlier patch of the same minor, to a later release. For example, 1.3.2 is supported from any 1.2 release and from 1.3.0 or 1.3.1. From anything older, upgrade to the newest patch of each minor in turn. Nothing tests a longer jump yet, so it isn’t supported, and veltro upgrade doesn’t stop you from trying one. The range widens once a test covers upgrades across several releases.

On Compose, run veltro upgrade --to <release>. It takes a backup first and refuses a downgrade; to go back, restore that backup (Backup and upgrade). It only reads the target release’s notes, so read the notes of any release you pass over too.

On Kubernetes, run helm upgrade with the new --version. A database migration can stop a chart rollback from working, so restore a backup before you install an older chart.

Upgrading a 0.x install to 1.0

Read the Migration section of the 1.0 release notes first. What else you need depends on how the install was set up.

Compose, with data in suite-postgres and suite-redis

This covers every install made fresh on suite 0.13.0 or later, and any install that ran the datastore migration. It upgrades straight to 1.0 with veltro upgrade --to 1.0.0.

Suite 0.13 releases also kept the old per-product datastore containers behind a legacy-datastores Compose profile, with their volumes. By suite 0.14.2 the profile was gone, so after the upgrade those containers keep running as orphans. Remove them once with veltro up --remove-orphans, which leaves volumes alone. The old volumes stay on disk until you delete them; the datastore consolidation runbook lists their names.

Compose, with data still in the per-product datastores

This is an install whose data is still in vf-postgres, chad-postgres, warden-postgres and the other per-product stores. The only way off them is suite 0.13.9’s datastore migration, and that runs as stages the protected release workflow dispatches to the Veltrosecurity homelab. There’s no version you can run yourself, so 1.0 has no supported path for such an install. Backups taken on that layout don’t restore into 1.0 either.

Compose, with a full or standalone profile

A veltro.toml that says profile = "full" reads as all three products. A standalone profile is refused, because its users exist only inside the product. See Upgrading from full or a standalone profile and Moving from a standalone install.

Kubernetes

The datastore move was Compose only. The charts never ran suite-postgres, and each product keeps using the database its values point at. Run helm upgrade with --version 1.0.0 after two changes to your values:

• Select products with global.products and each product’s enabled flag. Move any global.profile or global.integrated setting over to them; the chart no longer has either.
• Set the values the Kubernetes guide lists for each enabled product.

Scripts

Sigmatic API keys and the X-API-Key header are gone. Send a personal access token as a bearer token instead. The SDKs dropped chad_api_key and chadApiKey; pass the token as a BearerToken.