Develop

VOLT's application code lives in one pnpm monorepo, VoltLabs-Research/VOLT. The native libraries, every plugin and the plugin CLI live in their own repositories. This page covers the monorepo: what each package is, how to build it, how to run the server, the cluster daemon and the client while you work on them, and what CI checks on every push.

To deploy VOLT rather than develop it, see Self-hosting.

Repository layout

The workspace (pnpm-workspace.yaml) is every directory under packages/apps, packages/infra, packages/shared and packages/sdk.

Prerequisites

Install and build

git clone https://github.com/VoltLabs-Research/VOLT.git
cd VOLT
pnpm install
pnpm build          # pnpm -r build: every package that has a build script

To build one package, build its workspace dependencies first and then the package. The SDKs' package.json types point at their dist/, so a consumer's typecheck needs them built:

pnpm --filter "volt-server^..." build   # the dependencies of volt-server
pnpm --filter volt-server build

The web runtime bundles the backends' built dist/, so build them before it, with Emscripten on your PATH:

source ~/emsdk/emsdk_env.sh
pnpm --filter "@volt/web-runtime^..." build
pnpm --filter @volt/web-runtime build

The client's Vite plugin copies the built runtime into the client's build and fails with @volt/web-runtime: … is not built (run its build first) when it is missing. pnpm --filter "volt-webapp^..." build builds the runtime along with the client's other dependencies.

Package scripts

The root package.json runs build, typecheck and lint across the workspace (pnpm -r).

Running in development

Server

The server reads packages/infra/server/.env. Copy .env.example and point DATABASE_URL at a PostgreSQL database; the example value is postgres://volt:volt@localhost:5432/volt. One way to get that database:

docker run -d --name volt-dev-postgres -p 5432:5432 \
  -e POSTGRES_USER=volt -e POSTGRES_PASSWORD=volt -e POSTGRES_DB=volt \
  postgres:17-alpine

Then start the server from source. It listens on SERVER_PORT (8000 unless set):

cd packages/infra/server
cp .env.example .env
pnpm --filter volt-server start

GET /healthz answers {"status":"ok", ...} once it is up. Configuration lists the variables.

Cluster daemon

The daemon reads its configuration from the environment; it does not load a .env file. packages/infra/cluster/.env.example lists the variables. It needs at least TEAM_CLUSTER_ID, TEAM_CLUSTER_DAEMON_PASSWORD and VOLT_CLOUD_URL (the server's origin), which you get by creating a cluster in the app (see Clusters).

cd packages/infra/cluster
set -a; source .env; set +a
pnpm dev

dev first fetches the daemon's vendor tools (volt-dump-transform and zstd, from the CoreToolkit release pinned in package.json under coreToolkitTools), then runs src/daemon.ts with tsx. scripts/start.js sets the V8 heap to 80% of the machine's memory, or of its cgroup limit; set DAEMON_HEAP_MB to override it.

Client

VITE_PROXY_API_URL=http://localhost:8000 pnpm --filter volt-webapp dev

The dev server listens on port 5170 over HTTPS and proxies /api and /socket.io (WebSockets included) to VITE_PROXY_API_URL, else VITE_SERVER_ENDPOINT, else http://127.0.0.1:8000. Without certificates it serves a self-signed one. Service workers reject self-signed certificates, so to run the in-browser stack from the dev server, generate a trusted local CA and certificate first:

packages/apps/client/scripts/dev-certs.sh            # localhost, 127.0.0.1 and this host's LAN IPs
packages/apps/client/scripts/dev-certs.sh my-host    # extra names or IPs

The script writes packages/apps/client/.certs/ and trusts the CA in the user's NSS database (Chrome and Brave on Linux). It needs openssl and certutil. Import .certs/volt-dev-ca.pem by hand in Firefox and on other devices.

Desktop app

The desktop window loads the client's build from packages/apps/client/dist, so build the client first:

pnpm --filter "volt-webapp..." build
pnpm --filter volt-desktop dev

The Docker stack

packages/apps/desktop/stack/compose.yml describes the stack: volt-postgres, volt-server, volt-client and, under the enrolled profile, cluster-daemon. It builds each image from the checkout that VOLT_SOURCE_DIR points at. compose.images.yml is an overlay that swaps every build for a published image. The deploy CLI drives both; see Self-hosting.

Checks and tests

CI

.github/workflows/verify.yml runs on every push to main, on pull requests and on demand. A newer push cancels the run in progress on the same ref. Each job installs only its package and the workspace packages it depends on (pnpm install --frozen-lockfile --filter <name>...), then builds those dependencies.

The other workflows publish:

Other repositories

Everything outside the monorepo is under github.com/VoltLabs-Research, one repository each:

Native libraries describes the libraries in more depth.