Self-hosting

Run Voltro on your own infra — Docker compose, env vars, reverse proxy, scaling.

The runtime that powers Voltro Cloud is the same runtime you run yourself with voltro start — one codebase, one license. Self-hosting is fully supported — no separate "lite" runtime, no feature gates around the core API.

The shape of a self-hosted deploy

You need:

  1. Node.js 24+ to run the api + web processes.
  2. Postgres 16+ with pgvector extension (for AI / search) and wal_level=logical (for subscriptions). Managed Postgres at Neon, Supabase, RDS, or your own server all work.
  3. A reverse proxy (Caddy / nginx / Cloudflare). Terminates TLS, routes paths, fronts the framework's processes.
  4. (Optional) Redis for cross-instance subscription fan-out when you scale beyond one api process.
  5. (Optional) Object storage (R2, S3, GCS) — required if you use @voltro/plugin-storage.

Voltro doesn't require Kubernetes or any orchestrator. A single Docker host + Caddy is enough for ≥99% of deployments.

The supported path: voltro baseline

You don't have to hand-write any of the deploy plumbing below — the CLI ships baselines that generate it. Pick one at project creation or switch later:

voltro create-project acme --api=api-backend --web=frontend-blank --baseline=compose
# or, on an existing project:
voltro baseline set compose       # generates docker/{api,web}.Dockerfile + docker-compose*.yml
voltro baseline sync              # regenerate services from every apps/*/project.json
voltro baseline set helm          # generates charts/voltro-app/ for Kubernetes
voltro baseline status            # which baseline is active
  • bare — .env.example + a sample systemd unit. You bring your own Postgres + deploy.
  • compose — docker/{api,web}.Dockerfile, a pinned PostgreSQL 18.6 service, one database/login per project, docker-compose.dev.yml (locked install + HMR), and docker-compose.prod.yml (built images). Each production migration service applies its reviewed schema plan and then runs declared boot-lifecycle seeds once as part of the pre-deploy job; serving replicas never auto-seed. Project/app additions trigger the same sync automatically.
  • helm — a charts/voltro-app/ chart with per-env values + Deployment / Service / Ingress / Postgres StatefulSet.

The hand-rolled compose + Caddyfile below are a conceptual deployment reference. Prefer the manifest-derived generated files and add your public reverse-proxy policy on top.

The generated development and production stacks also support API-only and web-only workspaces. The web reverse proxy is included only when a web app is declared; API-only services remain reachable on their container network for your own ingress or callers.

Workspace dependency preparation in development

The generated compose development stack runs workspace-deps before any migration, API or web service starts. It first runs pnpm install --frozen-lockfile, then runs the existing build scripts of the transitive workspace dependencies of every declared API and web app, in dependency order. Shared dependencies are selected once across the workspace. Packages without a build script are skipped; the declared app bundles and the workspace root's script are excluded. With no API or web app, this service only installs dependencies. A failed install or dependency build prevents migrations and app services from starting. If an app actually depends on built exports from the workspace root package, prepare that package explicitly; this step does not run its excluded build script.

This prepares local libraries that export built files such as dist/index.js; installing their workspace links alone does not create those files. Dependency packages own their build scripts and output paths. No additional manifest setting or manual dependency-build override is needed for this generated startup step. After upgrading the CLI, run voltro baseline sync to regenerate an existing stack. Keep application-specific overrides in separate Compose files and review any earlier dependency-build override against the generated command.

Preparation runs at startup. It does not watch or rebuild a library when you edit it later; use that library's own rebuild or watch workflow. With bare and helm, prepare dependencies in your native or CI build pipeline. Production API/web Dockerfiles prepare the target app's workspace dependencies in their build stage.

The static compose-mariadb development template also gates its default api and web services on a locked install and their workspace dependency builds. It uses the same dependency order and skips missing build scripts, the default app bundles and the workspace root. It mounts the host workspace, including its dependencies, and does not derive app services from project manifests. For added or renamed apps, keep its preparation selectors and service dependencies aligned in your own Compose configuration. To adopt an updated dev template in an existing workspace, use voltro baseline set compose-mariadb, which backs up the replaced baseline files. Review the result and preserve your custom services and settings from that backup. voltro baseline sync refreshes only this baseline's Dockerfiles; it does not replace its static dev Compose file.

The generated compose stack gives each app/package node_modules volume a bounded readable name with a SHA-256 suffix derived from its relative path, so similar paths do not share dependencies. Regenerating an older stack creates new dependency volumes; the old dependency volumes remain unused. Preserve database volumes when adopting this change: do not use docker compose down -v to reset dependencies, because that also deletes database volumes.

For manifest-derived compose generation, discovered app and package paths must be safe relative paths: start with an ASCII letter or digit, use only ASCII letters, digits, ., _, - and /, and contain no .. segment. Paths with spaces or shell metacharacters are refused before generated Compose files change.

Required and optional production environment

For the compose baseline, declare environment names per app in apps/<project>/project.json, then run voltro baseline sync:

{
  "name": "acme",
  "apps": {
    "api": {
      "kind": "api",
      "path": "api",
      "port": 5190,
      "productionSecrets": ["VOLTRO_FIELD_ENCRYPTION_KEY"],
      "optionalProductionEnv": ["VOLTRO_FIELD_ENCRYPTION_KEY_PREVIOUS"]
    }
  }
}

productionSecrets requires a nonempty host value. optionalProductionEnv passes a host value when supplied and uses an empty string when unset or empty. Both lists contain names only; supply secret values through your deployment environment. The generated production API environment above includes:

VOLTRO_FIELD_ENCRYPTION_KEY: ${ACME_VOLTRO_FIELD_ENCRYPTION_KEY:?set ACME_VOLTRO_FIELD_ENCRYPTION_KEY}
VOLTRO_FIELD_ENCRYPTION_KEY_PREVIOUS: "${ACME_VOLTRO_FIELD_ENCRYPTION_KEY_PREVIOUS:-}"

Names are prefixed with the project name on the host and stay unchanged inside the container. Both lists accept SCREAMING_SNAKE_CASE names on API and web apps. Neither list may override a baseline-owned binding such as NODE_ENV, PORT, an API's VOLTRO_SESSION_SECRET / database settings, a web origin or a generated sibling API address (VOLTRO_API_<APP>_URL). An optional name cannot also be required. App declarations and the app collection must be objects, and each app must have a nonempty string kind. Invalid structures and environment conflicts are refused before any generated file is written; the refusal names the manifest field to correct. Nonruntime app kinds such as mobile do not become Compose services. These declarations affect long-running production services; the generated dev and migration services have their own environment.

For field-encryption rotation, keep the current key required and supply the previous key only during rotation. The field cipher and voltro db encrypt-column treat an empty previous key as absent; other optional variables must be accepted as empty by the application that reads them.

compose-mariadb, helm and bare do not read these manifest lists, and baseline sync does not regenerate their environment. With Helm, omit optional nonsecret values from api.env when unused. Supply sensitive values through Kubernetes Secret references in the API Deployment; an optional previous key uses:

- name: VOLTRO_FIELD_ENCRYPTION_KEY_PREVIOUS
  valueFrom:
    secretKeyRef:
      name: field-encryption
      key: previous
      optional: true

Keep the current key's Secret reference required. With bare, omit the previous key from the process environment or systemd EnvironmentFile outside rotation. Never store encryption keys in chart values or commit them to project manifests.

Docker compose

# docker-compose.yml
services:
  postgres:
    image: pgvector/pgvector:pg16
    environment:
      POSTGRES_PASSWORD: change-me
      POSTGRES_DB: voltro
    command: postgres -c wal_level=logical -c max_replication_slots=10
    volumes:
      - pg-data:/var/lib/postgresql/data

  api:
    build: ./apps/api
    environment:
      DB_DIALECT: postgres
      DB_URL: postgres://postgres:change-me@postgres:5432/voltro
      VOLTRO_SESSION_SECRET: ${VOLTRO_SESSION_SECRET}
      AI_PROVIDER: anthropic
      AI_API_KEY: ${ANTHROPIC_API_KEY}
    depends_on: [postgres]

  web:
    build: ./apps/web
    environment:
      PORT: 5173
    depends_on: [api]

  caddy:
    image: caddy:2
    ports: ["80:80", "443:443"]
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile

volumes:
  pg-data:

Caddyfile

your-product.com {
  # The api serves the rpc WebSocket upgrade at /ws, the one-shot HTTP rpc
  # at /rpc, and introspection under /_voltro/*. Everything else is the web app.
  reverse_proxy /ws         api:4000
  reverse_proxy /rpc        api:4000
  reverse_proxy /_voltro/*  api:4000
  reverse_proxy *           web:5173
}

Single-origin deployment — no CORS, SameSite=strict cookies, no Domain attribute needed. The cleanest production layout. (Adjust the paths if your app mounts the rpc transport on a custom path — see below.)

Custom WebSocket path — transport.wsPath

For workspace APIs, the production web host preserves the incoming Host and Origin when forwarding a WebSocket upgrade to an internal API hostname. The upstream URL selects the server; it must not replace the browser's authority. This keeps the API's native same-origin guard enabled behind Docker or an ingress. Foreign and opaque (null) origins remain rejected; forwarded-host headers do not grant trust. An app-declared HTTP proxy to its own API should likewise use changeOrigin: false. Proxies to genuinely external services can retain their default host rewriting and require the appropriate explicit origin policy.

The production web host's HTTP proxy owns the RESPONSE lifetime, not merely the incoming request's. A completed GET fires no request aborted when the browser later abandons the response — an SSE feed, a long download — so the proxy watches the response: a premature close cancels the upstream; a normal finish keeps the upstream connection alive for reuse; an upstream error after the first bytes destroys the downstream connection instead of appending proxy text to a partial payload. No application-side cancellation wrapper or extra proxy timeout is needed. Before this an abandoned SSE response stayed open upstream until the process ended.

By default the browser connects the realtime rpc WebSocket to a same-origin path derived per api (/ws/<name>), and the api serves it at /ws. When your edge only allows WebSocket upgrades on a specific path (a WAF / CDN rule), or you must match a path a previous stack used, set transport.wsPath on the api app. The api then serves the socket there AND the web client auto-derives the same path — declare it once, no web-side config, no drift:

// apps/api/app.config.ts
export default {
  type: 'api' as const,
  name: 'api',
  store: 'postgres' as const,
  // Serve the rpc WebSocket on a fixed absolute path. The web app that
  // consumes this api reads this value and connects here — nothing to set on
  // the web side.
  transport: { wsPath: '/api/sync' },
}

Then route that path to the api in your proxy — everything else is unchanged:

your-product.com {
  reverse_proxy /api/sync   api:4000   # the custom WS path (served by the api)
  reverse_proxy /rpc        api:4000
  reverse_proxy /_voltro/*  api:4000
  reverse_proxy *           web:5173
}

The path is relative in the bundle, so the host resolves at runtime — one built image works across every environment; only the path is fixed. Keep the socket same-origin with the web app: the session cookie rides the WS upgrade, and a cross-origin socket wouldn't carry it (every subscription would run anonymous). For an api on a genuinely separate origin, use the api spec's absolute url on the web side plus a token-based headers resolver instead of a cookie. (One custom wsPath per origin — the framework fails the build if two same-origin apis would collide on it.)

Split web/api deployment — the SSR api origin — serverUrl

When web and api deploy as separate services (e.g. different k8s namespaces, one ingress routing /api* → api), the browser reaches the api by its relative wsPath against the page origin — but a renderMode:'ssr' page's ctx.query runs in the web pod, which has no page origin and must reach the api by internal DNS. These are genuinely different endpoints, so url (which is also the browser's ws origin) can't express the internal one without shipping an unreachable host to the browser.

Set the server-only serverUrl (or the env override) to the api's internal origin:

// web/app.config.ts
apis: {
  app: {
    package: '@app/api',
    transport: { wsPath: '/api/sync' },        // browser → relative, same-origin
    serverUrl: process.env.VOLTRO_API_ORIGIN,  // web pod → internal DNS
  },
},
# or set it purely from ops, no app.config edit — per-api, name upper-cased:
VOLTRO_API_ORIGIN_APP=http://api.my-namespace.svc.cluster.local
# or a single shared origin for every api:
VOLTRO_API_ORIGIN=http://api.my-namespace.svc.cluster.local

serverUrl / VOLTRO_API_ORIGIN* is never emitted into the browser bundle. It supplies the SSR POST /rpc origin; under voltro dev, the env form also supplies Vite's server-side WS/inspect proxy upstream, which is what lets a web container reach a sibling API by service DNS instead of its own localhost. SSR resolution order is env > serverUrl > (under voltro dev only) the dev proxy target > an external api's absolute url. Under voltro start, a package api with none of these set makes the SSR query fail loud — naming the api and the config to set — instead of dialing the dev localhost port and surfacing a cryptic ECONNREFUSED in a 500.

allowedHosts — fronting the web app on a real domain

Vite 8's DNS-rebind guard returns HTTP 403 for any request whose Host header isn't an IP or localhost. So a Voltro web app served through a reverse proxy / ingress on a real domain (e.g. app.dev.example.com) 403s in the browser until that host is allow-listed. Add the new optional field on the web app's app.config.ts:

// apps/web/app.config.ts
export default {
  type: 'web' as const,
  name: 'web',
  // string[] | true — default: unset = Vite default (only IPs + localhost).
  allowedHosts: ['app.dev.example.com'],   // a leading-dot entry like
                                           // '.example.com' matches all subdomains
  // allowedHosts: true,                   // disable the check entirely —
                                           // only behind a trusted proxy, since
                                           // it removes the rebind protection
}

This applies to the dev / Vite-served surface — a production voltro start SSR/SPA host fronted by the proxy. If you see a 403 in the browser but the proxy logs show the request reaching the app, this is almost always the cause.

Env vars

Var Required Notes
DB_DIALECT for SQL stores postgres (default) / mysql / mariadb / mssql / sqlite / turso
DB_URL for SQL stores Database connection string (falls back to DB_PRIMARY_URL; or the discrete DB_* / PG_* fields)
VOLTRO_SESSION_SECRET when using @voltro/plugin-auth 32+ random bytes from a real CSPRNG — the session-cookie signing key (voltro secret generate session)
VOLTRO_DATA_TRANSFER_SECRET to enable --target api export/import Gates POST /_voltro/admin/{export,import}; ≥16 chars or the routes stay unmounted (voltro secret generate data-transfer)
VOLTRO_BUNDLE_KEY for encrypted .vbundle exports Passphrase for at-rest bundle encryption — a DEDICATED key, not the transfer secret (voltro secret generate bundle-key)
VOLTRO_FIELD_ENCRYPTION_KEY once any .encrypted() column is declared — @voltro/plugin-webhooks declares one Key for .encrypted() columns; boot refuses if missing while such columns exist (voltro secret generate field-encryption)
VOLTRO_STORAGE_SECRET optional (@voltro/plugin-storage) Signs private-file grant tokens; falls back to the session secret if unset
AI_PROVIDER when using @voltro/ai anthropic / openai / mock
AI_API_KEY with AI_PROVIDER Provider's API key
SSR_CACHE optional memory (default) or postgres for the ISR cache. postgres needs a database in the WEB process's env (DB_URL / DB_HOST / PG_HOST) — without one it aborts the boot in production rather than falling back to memory
VOLTRO_API_ORIGIN / VOLTRO_API_ORIGIN_<NAME> split web/api deploys or containerized dev The api's internal origin the WEB process uses for SSR ctx.query and, under voltro dev, its WS/inspect proxy (http://api.<ns>.svc.cluster.local). Per-api _<NAME> (name upper-cased) wins over the shared one and over serverUrl. Never sent to the browser An origin named here counts as operator-configured: the dev inspect proxy may send it the web pod's VOLTRO_INSPECT_TOKEN, for a requester it trusts
PORT optional App's listen port. Outranks --port and app.config.ts port: — a platform that assigns a port sets this one, so it has to win. Unset, the app binds its declared port:, then 4000 (api) / 5173 (web).
VOLTRO_INSPECT optional off to disable _voltro/inspect/* in prod
VOLTRO_INSPECT_TOKEN recommended Bearer token guard on inspect endpoints
VOLTRO_DASHBOARD_APPS dashboard only JSON [{name?,url,token?,writeToken?}] — target apps + their inspect read/write tokens the deployed DevTools dashboard proxies to; the tokens stay in the pod (/api/dashboard/config serves only where the targets are and whether the pod holds credentials)
VOLTRO_DASHBOARD_TOKEN dashboard; web dev server the dashboard's own lock (16+ chars): the browser proves it once on the login page and gets an HttpOnly session cookie; every /api/dashboard/* route answers 401 without one. Required in production whenever VOLTRO_DASHBOARD_APPS carries a token — the dashboard refuses to boot otherwise Also locks a web dev server's /_voltro/api/<name> inspect proxy: set it on the web pod and a developer signs in once from the overlay (see voltro dev → Reading a remote api)

Scaling beyond one instance

When one api process isn't enough:

  1. Run multiple api containers behind the reverse proxy. The proxy's load-balancing default (round-robin) is fine for HTTP — for WebSocket, use sticky sessions (Caddy: lb_policy ip_hash).
  2. Cross-instance subscription invalidation: on Postgres (LISTEN/NOTIFY) and MySQL/MariaDB (binlog CDC) this is built in — nothing to install. On any other dialect, or when you prefer a broker, add @voltro/plugin-broadcast with a Redis or NATS provider to app.config.ts.plugins so every replica sees every change.
  3. Workflows: @effect/cluster shards work across instances by workflow ID. No further config — every instance pulls from the shared workflow queue.

For multi-region: you need to run Postgres logical replication between regions yourself (or move to Voltro Cloud which handles it).

Scaling is replicas, not a service split

Scaling is never a reason to split an app. One app, scaled by running more replicas of it — with @effect/cluster sharding durable work across instances by workflow ID — is the architecture, and more replicas of the same image is the answer to load.

A second app IS right when something has its own data or credential boundary: a worker that holds a cloud provider's keys for every tenant should not be the process that answers requests from the internet. Then the rule is absolute — every api app owns its database, and one app reaches another's data by calling it, never through its tables. The framework enforces both halves: a second app booting against a database another app owns refuses to start, and a store call on a table the app does not declare fails. How two apps call each other — typed service: procedures, apis: bindings, per-edge credentials, and reactions that watch another app's open work — is Services. An external system boundary is still REST routes + OpenAPI, and a reliable outbound side effect the transactional outbox.

Into a network with no route out: voltro transfer

An installation without internet access gets its releases on a medium: the builds, the license, the docs. voltro transfer seal <dir> signs such a directory for one installation. It writes voltro-transfer.json, a manifest with a bundle id, a sequence, when it was made, until when it holds (--valid-days, default 30), who sealed it (--exporter), the installation it is for (--scope) and every other file with its size and SHA-256. Beside it, voltro-transfer.sig holds an Ed25519 signature over the manifest's exact bytes. The key pair comes from voltro secret keypair.

Inside, voltro transfer verify <dir> checks the bundle before anything from it is used, and exits 1 on any problem, naming each one:

  • the signature is from a key named with --trust (repeatable), not just any valid signature;
  • the bundle has not expired, and was not made in the future;
  • it is for this installation (--scope), and newer than the last bundle taken (--after <sequence>);
  • every listed file is there with its size and digest, nothing unlisted was added, and no path leaves the directory.
# Once, outside: the sealing key pair. Keep the private key outside.
voltro secret keypair

# Outside: build, collect everything the site needs, seal it for the installation.
voltro transfer seal ./release --key sealing.pem --scope acme-onprem --sequence 7

# Inside, before anything from it is used:
voltro transfer verify ./release --trust sealing.pub.pem --scope acme-onprem --after 6

--json prints the manifest (seal) or the verdict (verify) instead.

Backups

Postgres is the source of truth. Use your provider's backup features (Neon PITR, RDS snapshots, pg_dump on a cron). Object-storage assets back up via the provider's lifecycle policies.

Deploying the DevTools dashboard

The DevTools dashboard (route sitemap, rpc list, logs / traces, schedules, the per-plugin inspect panels) can run as its own deployment on its own URL. It reaches each observed app's /_voltro/inspect/* through its own same-origin proxy, so the target apps only need to be reachable from the dashboard pod — not the browser.

The image is the npm package

@voltro/dashboard on npm is the built, boot-verified app; voltro dashboard serves it through the same voltro start path a container runs. The image is that package installed into a node image, versioned in lockstep with the framework — docker.io/voltro/dashboard:<version> is built from exactly this Dockerfile. If the tag you need is not there, the same file builds it from npm in one command; there is no source to check out and nothing is copied from the build context:

FROM node:24-alpine
ARG VOLTRO_VERSION
RUN corepack enable && corepack prepare pnpm@12.3.2 --activate
WORKDIR /app
RUN printf '{ "name": "voltro-dashboard-image", "private": true }\n' > package.json \
 && printf "allowBuilds:\n  esbuild: false\n  '@parcel/watcher': false\n  msgpackr-extract: false\n  protobufjs: false\n" > pnpm-workspace.yaml \
 && pnpm add --save-exact --config.optional=false "@voltro/dashboard@${VOLTRO_VERSION}" "@voltro/cli@${VOLTRO_VERSION}"
ENV NODE_ENV=production PORT=5180 VOLTRO_IS_DASHBOARD=1
EXPOSE 5180
CMD ["node", "node_modules/@voltro/cli/bin/voltro.mjs", "start", "node_modules/@voltro/dashboard"]
docker build --build-arg VOLTRO_VERSION=<version> -t voltro/dashboard:<version> .

The image can only start. It is installed without optional dependencies, so vite, esbuild and tsx are not inside; the entrypoint is voltro start on the installed package, which the CLI runs in-process from its build without a TypeScript loader; and voltro dev cannot even spawn there. The package itself ships its build and its config, no source. voltro dashboard (the command a host runs) has no dev mode at all: a package without a build is refused in every environment, and a source tree is served by voltro dev instead. The package also carries an artefact marker (.framework/dist/.voltro-artifact.json) that voltro dev and voltro build refuse on before loading anything, so a toolchain installed by hand cannot develop or rebuild it either. PORT from the environment is the listen port.

What the pod needs

  • Environment: PORT, VOLTRO_DASHBOARD_APPS and VOLTRO_DASHBOARD_TOKEN, nothing else. The dashboard is a web app with no apis, no env contract and no auth plugin, so the env gate has nothing to require — VOLTRO_SESSION_SECRET belongs to @voltro/plugin-auth and is not read here. The image boots with none of them set and answers /internal/readiness with 200; the third becomes mandatory the moment the second carries a token.

  • Targets at runtime: set VOLTRO_DASHBOARD_APPS to a JSON array of { name?, url, token?, writeToken? }, where url is each app's origin — inside a cluster the Service, not the ingress — token is that app's VOLTRO_INSPECT_TOKEN and writeToken its VOLTRO_INSPECT_WRITE_TOKEN, for the panels' actions. The dashboard serves the list from /api/dashboard/config on boot — where the targets are and whether the pod holds credentials for them (hasToken, hasWriteToken), never the values; the proxy attaches a configured target's credentials itself. So one image serves any environment and the tokens never leave the pod:

    VOLTRO_DASHBOARD_APPS='[{"name":"api","url":"http://api.prod.svc.cluster.local:4000","token":"…","writeToken":"…"}]'
  • Its own inspect surface is closed, and that is the intended state. The dashboard is itself a Voltro app and serves /_voltro/inspect/* fail-closed: with no VOLTRO_INSPECT_TOKEN in the pod every request — the live stream included — answers 401. There is nothing to set. VOLTRO_INSPECT=off turns that into a 503; giving the pod its own token and listing its own URL in VOLTRO_DASHBOARD_APPS makes the dashboard observe itself.

  • Lock it — the dashboard has a door of its own. Set VOLTRO_DASHBOARD_TOKEN — voltro secret generate dashboard prints it paste-ready (16+ characters required). The browser proves it once on the login page (POST /api/dashboard/login) and gets an HttpOnly, SameSite=Strict session cookie derived from the token by HMAC, valid for 12 hours; rotating the token invalidates every cookie. Without a session every /api/dashboard/* route — the registry, the config, the proxy, the live stream — answers 401. A dashboard whose VOLTRO_DASHBOARD_APPS carries a token and which has no lock refuses to boot in production: a pod that holds other apps' credentials must not be open to whoever knows its URL. An IP allow-list or an SSO proxy in front of the Ingress is still a good second layer; it is no longer the only one. Each target app's inspect surface stays token-gated on its own (VOLTRO_INSPECT_TOKEN). An unlocked dashboard lends the tokens it holds only to its own machine — a direct loopback connection no proxy relayed; a request from another address, or relayed by a reverse proxy (X-Forwarded-For), gets 401 inspect proxy refused from the proxy, its upload/download relays and its live stream.

Targets behind a Service with several replicas

Each proxied request lands on one replica, and both kinds of answer are built for that. Anything asked with ?scope=fleet is assembled from the shared store, so any replica answers for all of them — the fleet view and its completeness are the same whichever pod took the call. Everything else is process-scoped and says so in its origin.replicaId: one pod's answer, honestly labelled, and a refresh may show another pod's. ?replica=<id> asks one named pod through whichever pod is reachable; it needs each replica to publish a reachable address — POD_IP from the downward API, or VOLTRO_INSPECT_ADVERTISE_HOST — see Inspect scope.

A live stream is one TCP connection and stays on the pod that accepted it for its lifetime; a reconnect may land on another pod, and every event carries origin, so the switch is visible rather than silent. The stream is Server-Sent Events over a plain GET under /_voltro/inspect/stream: an ingress that forwards /_voltro/inspect forwards it, provided response buffering is off (the framework sends X-Accel-Buffering: no). The inspect surface, stream included, is gated by the token alone — no Host restriction applies outside voltro dev, so a Service or ingress hostname is never refused.

Kubernetes

An unset NODE_ENV is not a development opt-in. voltro dashboard uses voltro start, which resolves an unset or empty NODE_ENV to production. With configured target credentials and no dashboard token, both unset and production refuse to boot; explicitly setting NODE_ENV=development exempts the local development case. Keep the lock on a deployed dashboard instead of using that exception to get past the refusal. A token shorter than 16 characters is refused in every environment.

The same probes and shutdown contract as every Voltro app, on the dashboard pod — the production hardening page explains each line:

apiVersion: apps/v1
kind: Deployment
metadata: { name: voltro-dashboard }
spec:
  replicas: 1
  selector: { matchLabels: { app: voltro-dashboard } }
  template:
    metadata: { labels: { app: voltro-dashboard } }
    spec:
      terminationGracePeriodSeconds: 30
      containers:
        - name: dashboard
          image: voltro/dashboard:<version>
          ports: [{ name: http, containerPort: 5180 }]
          env:
            - { name: PORT, value: "5180" }
            - { name: VOLTRO_SHUTDOWN_GRACE_MS, value: "10000" }
            - name: VOLTRO_DASHBOARD_APPS
              valueFrom: { secretKeyRef: { name: voltro-dashboard-targets, key: VOLTRO_DASHBOARD_APPS } }
          lifecycle: { preStop: { exec: { command: ["sh", "-c", "sleep 5"] } } }
          startupProbe:   { httpGet: { path: /internal/startup,   port: http }, periodSeconds: 5, failureThreshold: 24 }
          readinessProbe: { httpGet: { path: /internal/readiness, port: http }, periodSeconds: 10 }
          livenessProbe:  { httpGet: { path: /internal/liveness,  port: http }, periodSeconds: 20 }
---
apiVersion: v1
kind: Secret
metadata: { name: voltro-dashboard-targets }
stringData:
  VOLTRO_DASHBOARD_APPS: '[{"name":"api","url":"http://api.prod.svc.cluster.local:4000","token":"…","writeToken":"…"}]'

Production checklist

  • HTTPS terminates at the edge with HSTS preload
  • VOLTRO_SESSION_SECRET rotated from CSPRNG, stored in a secrets manager (not env file in git!)
  • cookieSecure: true in the @voltro/plugin-auth config
  • Postgres wal_level=logical, max_replication_slots≥10
  • pgvector extension if you use AI features
  • OpenTelemetry exporter pointed at your sink (Datadog / Honeycomb / Grafana / Loki)
  • VOLTRO_INSPECT_TOKEN set, or VOLTRO_INSPECT=off in production
  • CORS allow-list is exact origins (no * with credentials)
  • Database backups verified (a backup you've never restored isn't a backup)
  • At least one staging deploy that mirrors production exactly

See @voltro/plugin-auth/COOKIES.md for the full cookie audit, and the Why Voltro? page for what we won't build (and what we will).

Project pnpm version and proxy parity

baseline set compose and baseline set compose-mariadb render the API, web and dev Dockerfiles with the root package.json's exact packageManager pnpm version. Corepack integrity suffixes are accepted. Without that field, the CLI uses the invoking pnpm version; if it cannot identify one, it refuses before writing files. A different package manager or a version range is refused. The framework's build-tool version does not determine your lockfile's toolchain.

The dev image runs pnpm once as root while it is built. pnpm 11 and later download a native binary on their first run, and the dev services run as your host user, who cannot write where corepack keeps it; without that build step every service stops with EACCES … pnpm-native….tgz. An image from an earlier sync needs voltro baseline sync and a rebuild.

baseline sync refreshes these three generated Dockerfiles using the current project pin. Keep custom Dockerfiles outside these generated paths. For compose, sync also regenerates the five manifest-derived Compose/Caddy/Postgres files. For compose-mariadb, sync refreshes the Dockerfiles only.

A web app can mount REST at the API root with:

export default {
  type: 'web' as const,
  proxies: { '/api': { target: 'http://api:5190', rewrite: '/', changeOrigin: false } },
}

changeOrigin: false preserves browser authority for REST writes to a Voltro API. Generic HTTP proxies otherwise default to rewriting Host for the target service; that default can make an API reject browser POSTs under its same-origin guard. Do not loosen the API origin policy to compensate.

A web app reaches a plugin's HTTP routes on its bound api — the /auth/* routes of @voltro/plugin-auth, say — by naming the api instead of an origin:

export default {
  type: 'web' as const,
  apis: { app: { package: '@acme/api' } },
  proxies: { '/auth': { api: 'app' } },
}

{ api } forwards to the same upstream as that api's WebSocket, in voltro dev and voltro start alike, and always keeps the browser's Host. The session cookie the api sets is therefore first-party on the web origin. A name missing from apis, or an external api the browser reaches directly, refuses the boot.

Both voltro dev and voltro start send /api/tenants/berlin/theme upstream as /tenants/berlin/theme. Query strings survive unchanged, /apix does not match /api, and the longest matching HTTP prefix wins. A declared prefix always reaches its upstream, even when a page route would also match the path. Workspace API WebSockets preserve the browser's Host and Origin, including behind a reverse proxy; the default /ws/<name> to /ws rewrite preserves query parameters too. The API still refuses foreign browser origins. The bearer-authenticated inspect proxy separately presents the upstream Host.