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:
- Node.js 24+ to run the api + web processes.
- Postgres 16+ with
pgvectorextension (for AI / search) andwal_level=logical(for subscriptions). Managed Postgres at Neon, Supabase, RDS, or your own server all work. - A reverse proxy (Caddy / nginx / Cloudflare). Terminates TLS, routes paths, fronts the framework's processes.
- (Optional) Redis for cross-instance subscription fan-out when you scale beyond one api process.
- (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 activebare—.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), anddocker-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— acharts/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: trueKeep 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.localserverUrl / 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:
- 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). - 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-broadcastwith a Redis or NATS provider toapp.config.ts.pluginsso every replica sees every change. - Workflows:
@effect/clustershards 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_APPSandVOLTRO_DASHBOARD_TOKEN, nothing else. The dashboard is a web app with noapis, noenvcontract and no auth plugin, so the env gate has nothing to require —VOLTRO_SESSION_SECRETbelongs to@voltro/plugin-authand is not read here. The image boots with none of them set and answers/internal/readinesswith200; the third becomes mandatory the moment the second carries a token.Targets at runtime: set
VOLTRO_DASHBOARD_APPSto a JSON array of{ name?, url, token?, writeToken? }, whereurlis each app's origin — inside a cluster the Service, not the ingress —tokenis that app'sVOLTRO_INSPECT_TOKENandwriteTokenitsVOLTRO_INSPECT_WRITE_TOKEN, for the panels' actions. The dashboard serves the list from/api/dashboard/configon 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 noVOLTRO_INSPECT_TOKENin the pod every request — the live stream included — answers401. There is nothing to set.VOLTRO_INSPECT=offturns that into a503; giving the pod its own token and listing its own URL inVOLTRO_DASHBOARD_APPSmakes the dashboard observe itself.Lock it — the dashboard has a door of its own. Set
VOLTRO_DASHBOARD_TOKEN—voltro secret generate dashboardprints 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 — answers401. A dashboard whoseVOLTRO_DASHBOARD_APPScarries 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), gets401 inspect proxy refusedfrom 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_SECRETrotated from CSPRNG, stored in a secrets manager (not env file in git!) -
cookieSecure: truein the@voltro/plugin-authconfig - Postgres
wal_level=logical,max_replication_slots≥10 -
pgvectorextension if you use AI features - OpenTelemetry exporter pointed at your sink (Datadog / Honeycomb / Grafana / Loki)
-
VOLTRO_INSPECT_TOKENset, orVOLTRO_INSPECT=offin 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.