Self-Hosting

Run the full VOLT stack on your own machine with one command, or with the desktop app.

VOLT self-hosts as two layers, by default on one machine:

App layer — the VOLT server (users, teams, auth, REST + Socket.io APIs) and the web client.
Cluster layer — a ClusterDaemon that runs the heavy compute: trajectory preprocessing, plugin jobs, notebooks, and container operations.

Both must run for an end-to-end workflow. An app with no healthy cluster has no execution target — uploads and analyses queue but never run.

Requirements

The host needs docker, node, and curl, with the Docker daemon running (sudo systemctl start docker on Linux). The deployer checks this and stops early if Docker is unreachable.

Component	Minimum	Recommended
OS	Ubuntu 20.04+ / Debian 11+ / macOS	Ubuntu 22.04 LTS
Node.js	22.x	22.x
Docker	20.x+	Latest stable
RAM	4 GB	8 GB+
Disk	20 GB	Sized to your trajectory + artifact volume

Deploy

One command. It downloads a prebuilt CLI and compose file into ~/.volt-deploy (no git clone, no build toolchain), then prompts for host/domain, deploy mode, and your account, team, and cluster:

curl -fsSL https://raw.githubusercontent.com/voltlabs-research/volt/main/desktop/scripts/deploy.sh | bash

It builds and starts the full stack — MongoDB, Redis, MinIO, the server, the web client, and (unless you pick server-only) a ClusterDaemon. The account you enter also registers a VOLT Cloud ID at console.voltcloud.dev (best-effort; skipped if unreachable). When it finishes it prints the client and server URLs — open the client (default http://<host>:5273) and sign in.

Desktop app

For a one-click setup, the desktop app launches and manages the same local stack — no terminal needed.

Download the latest release

To connect another device to a stack you deployed elsewhere, install the desktop app there and enter your server URL (e.g. http://<host>:8100) when prompted.

Update

Re-run the script with --update to pull the latest release and rebuild. Your data (Mongo/Redis/MinIO volumes) is kept, and a deployed daemon is updated too. It runs headless, so it is safe under cron/CI:

curl -fsSL https://raw.githubusercontent.com/voltlabs-research/volt/main/desktop/scripts/deploy.sh | bash -s -- --update

Re-running the plain command on a machine that already has VOLT offers Update (keep data) or Reset (wipe and start fresh). Append flags after bash -s --:

Flag	Effect
`--update`	Update to the latest release, keeping data
`--check`	Report whether an update is available; change nothing (exit `10` if so)
`--with-cluster`	Run server + daemon (persists the mode)
`--server-only`	Run the server only; stop the daemon (persists the mode)
`--force`	Rebuild even if already on the latest release
`--data-dir <path>`	Target a deployment outside `~/.volt-deploy`

Set GITHUB_TOKEN to raise the GitHub API rate limit for --update/--check.

What gets deployed

Service	Role	Host port
volt-client	Web UI (nginx; proxies `/api` + `/socket.io` to the server)	5273
volt-server	REST `/api/*` + Socket.io	8100
volt-minio	Object storage (S3) — API / console	9100 / 9101
volt-mongodb	Metadata	internal
volt-redis	Queues, cache, runtime state	internal
cluster-daemon	Compute (cluster mode only)	18080

Ports are set via WEB_PORT, SERVER_PORT, MINIO_PORT, and DAEMON_PORT. MongoDB and Redis are not published to the host — they are reached over the internal Docker network. MinIO buckets are auto-provisioned; you never create them by hand.

Secrets

The deployer generates two keys on first run and stores them in ~/.volt-deploy/app-config.json:

SECRET_KEY — signs sensitive server-side tokens.
SSH_ENCRYPTION_KEY — encrypts credentials at rest, including the SSH access used to install and enroll the daemon on a remote cluster host.

Keep app-config.json out of version control. Losing these keys invalidates issued tokens and stored credentials.

The stack serves plain HTTP with default credentials. Keep it on a trusted network, or front it with your own TLS reverse proxy. If you do, forward the WebSocket Upgrade/Connection headers and allow long read timeouts on /socket.io — real-time collaboration and the live cluster channel break on an HTTP-only proxy.

Verify

Check the round-trip, not just that containers are up:

open the client URL and sign in,
confirm the cluster reaches connected with a fresh heartbeat (cluster mode),
upload a small trajectory and wait for it to complete,
run a lightweight analysis and open the result.

If the app is up but the cluster never leaves waiting, the daemon cannot reach the server — check the daemon logs, the VOLT Cloud URL, and network reachability.

For architecture, cluster internals, and contributor setup, see the rest of the VOLT documentation.