Skip to content

Install Provon

Choose a path:

View as Markdown Open the plain-text version of this page.
Path Best for
Hosted Provon Fastest start, no infrastructure
Self-hosted installer Running the server on your own machine or Linux host
Source development Contributing to or customizing Provon

Hosted Provon#

Fastest start:

  1. Open https://app.provon.dev and sign in.
  2. Complete the Workbench onboarding.
  3. Copy the project API key shown during onboarding; it is displayed only once.

No local installation is required.

Self-hosted installer#

Two installers download a release archive, place the CLI and Node server under an install prefix, create the data directories, and generate a ready-to-source env file.

Prerequisites#

  • macOS or Linux for install.sh; Windows for install.ps1. The shell installer rejects other operating systems.
  • Node.js major version 22 or newer. If no suitable Node is found, the installer downloads Node 22.11.0 into <prefix>/node automatically.
  • curl, tar, and openssl on macOS/Linux; PowerShell 5.1 or newer on Windows.

Install#

bash
curl -fsSL https://provon.dev/install.sh | sh

What the installer does#

  1. Resolves the latest release (or the pinned --version / -Version), unless --tarball / -Tarball points to a local archive.
  2. Downloads the platform archive from GitHub Releases and verifies its SHA256 checksum unless --skip-checksum / -SkipChecksum is set.
  3. Extracts provon and provon-server into <prefix>/bin.
  4. Ensures Node 22+ is available, downloading Node 22.11.0 to <prefix>/node when needed.
  5. Generates <prefix>/env (<prefix>/env.ps1 on Windows) with a random auth secret and local paths; the shell env file is written with mode 600.
  6. Creates <data-dir>/logs and <data-dir>/blobs.
  7. Prompts to append <prefix>/bin to your shell startup file (macOS/Linux) or user PATH (Windows); --yes / -Yes accepts automatically.

Installer options#

install.sh install.ps1 Environment variable Default
--version <v> -Version <v> PROVON_VERSION Latest GitHub release
--prefix <path> -Prefix <path> PROVON_PREFIX ~/.provon / %USERPROFILE%\.provon
--data-dir <path> -DataDir <path> PROVON_DATA_DIR <prefix>/data
--tarball <path> -Tarball <path> PROVON_TARBALL Download from GitHub
--skip-checksum -SkipChecksum PROVON_SKIP_CHECKSUM=1 Checksum verified
--dry-run -DryRun PROVON_DRY_RUN=1 Execute changes
-y, --yes -Yes PROVON_YES=1 Interactive confirmation
--daemon — PROVON_DAEMON=1 Off (manual start)

--daemon exists only on macOS/Linux: it registers and starts a service. The Windows installer has no daemon option.

Installed layout#

Item Path
CLI binary <prefix>/bin/provon
Server binary <prefix>/bin/provon-server (provon-server.cmd on Windows)
Environment file <prefix>/env; Windows also writes <prefix>/env.ps1
Data directory <data-dir>; logs in logs/, blobs in blobs/
Bundled Node <prefix>/node (when downloaded by the installer)

Start the server#

Manual foreground start (default).

bash
source ~/.provon/env
~/.provon/bin/provon-server

Background service (--daemon, macOS/Linux only).

  • macOS: a launchd agent dev.provon.provon-server; manage it with launchctl.
  • Linux: a systemd user unit provon-server.service; manage it with systemctl --user. Run loginctl enable-linger <user> so the unit survives logout.

The installer registers no provon-server stop subcommand; stop the manual process with Ctrl+C, or stop the service with launchctl unload / systemctl --user stop.

The production installer binds a single origin on http://127.0.0.1:3000 by default (PROVON_HTTP_PORT); open the Workbench URL printed in the logs.

See Self-hosting overview for architecture, configuration, and operations.

Success Check#

bash
~/.provon/bin/provon --version
curl -fsS http://127.0.0.1:3000/ >/dev/null && echo "Workbench reachable"

The Workbench loads at the logged URL and you can create an organization and project.

Troubleshooting#

Symptom Likely cause Fix
provon: command not found after install PATH not updated in this shell Reopen the shell, or source ~/.provon/env and use <prefix>/bin/provon
Node major version below 22 System Node too old Re-run the installer so it provisions <prefix>/node; or upgrade Node 22+
Installer exits on an unsupported OS install.sh only supports macOS/Linux Use install.ps1 on Windows
Port 3000 already in use Another process occupies the port Set PROVON_HTTP_PORT to another free port in the env file before starting
systemctl --user unit stops after logout Linger not enabled Run loginctl enable-linger <user>
Checksum failure on manual tarball Archive incomplete or tampered Re-download without --skip-checksum; never bypass checksum on untrusted tarballs

Source development#

Use this path when contributing to Provon or customizing the source.

Prerequisites#

  • Node.js 22 or newer.
  • pnpm 10.33.0 (the repository pins packageManager: pnpm@10.33.0; corepack provisions it).

Clone and install#

bash
git clone https://github.com/provon/provon
cd provon
pnpm install

Start the development server#

bash
pnpm dev

Default ports:

Component Default port Override
Workbench dev server 3000 pnpm dev -- --port 3100 or PROVON_HTTP_PORT
API server 3001 (Workbench port plus one) PROVON_DEV_API_PORT

Local data under the repository root: metadata and related SQLite databases in .provon/data/, telemetry in DuckDB, blobs in .provon/blobs/. Read .env.local automatically when present.

Seed a demo product tour#

Inspect the Workbench without generating your own workload by seeding an empty database before starting the server:

bash
pnpm seed:demo
pnpm dev

The seed command refuses to write into non-empty metadata, metering, or telemetry databases. Sign in with demo@provon.dev and password provon123.

Use The CLI Against A Deployment#

The self-hosted installer already includes the CLI. If you only need the CLI:

bash
# macOS / Linux
curl -fsSL https://provon.dev/install.sh | sh

# Or build from the repository
pnpm --filter @provon/cli build
node cli/dist/bin.js --help

Authenticate with user delegation or a project API key:

bash
# Project API key (environment variables)
export PROVON_API_KEY="your_project_api_key"
export PROVON_API_URL="https://api.provon.dev"   # no /v1 suffix; the CLI adds it

# Or open a browser sign-in flow
provon auth login

See CLI authentication and CLI overview.

Verify The Installation#

Run:

bash
provon --version

For a self-hosted or source install, confirm the Workbench loads and you can create a project. The next step is the Quickstart.