# Install Provon

You can use Provon as a hosted service or run it yourself. This page covers all three paths.

| Path                                            | Best for                           | Model fine-tuning |
| ----------------------------------------------- | ---------------------------------- | ----------------- |
| [Hosted Provon](#hosted-provon)                 | Fastest start, no infrastructure   | No                |
| [Self-hosted installer](#self-hosted-installer) | Private data, local models         | Yes               |
| [Source development](#source-development)       | Contributing or customizing Provon | Yes               |

## Hosted Provon

The fastest way to start:

1. Open `https://app.provon.dev`.
2. Sign in and complete the [Workbench onboarding](./workbench-onboarding.md).
3. Copy the project API key shown during onboarding.

No installation is required. The hosted service does not support local model serving or fine-tuning;
for those capabilities, use a self-hosted runtime.

## Self-hosted installer

The official installers download a release archive, set up a local Node server, Python inference
environment, and data directories, and generate a ready-to-use `env` file.

### Requirements

- Node.js 22 or newer (the installer can download a private copy if needed)
- macOS, Linux, or Windows
- An empty directory for the Provon prefix and data

### macOS / Linux

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

### Windows

```powershell
irm https://provon.dev/install.ps1 | iex
```

### What the installer does

1. Resolves the latest Provon release (or use `--version` / `-Version`).
2. Downloads the platform-specific archive from GitHub Releases.
3. Verifies the SHA256 checksum.
4. Extracts the CLI, Node server, Python inference wheel, and fine-tuning wheel.
5. Ensures Node.js 22+ is available.
6. Creates a Python virtual environment and installs the wheels with the selected engine extras.
7. Generates `env` (and `env.ps1` on Windows) with random secrets and local paths.
8. Optionally adds the `bin` directory to PATH.

### Common installer options

| Shell (`install.sh`)         | PowerShell (`install.ps1`) | Default                               |
| ---------------------------- | -------------------------- | ------------------------------------- |
| `--prefix PATH`              | `-Prefix PATH`             | `~/.provon` / `%USERPROFILE%\.provon` |
| `--engine EXTRA`             | `-Engine EXTRA`            | `llama_cpp`                           |
| `--fine-tuning-engine EXTRA` | `-FineTuningEngine EXTRA`  | `none`                                |
| `--data-dir PATH`            | `-DataDir PATH`            | `<prefix>/data`                       |

Engine extras:

- Inference: `llama_cpp`, `vllm`, `sglang`, `all`, `none`
- Fine-tuning: `transformers`, `gguf`, `compressed`, `all`, `none`

### Start the self-hosted server

After installation, follow the installer output to source the environment file and run:

```bash
source /path/to/provon/env
provon-server
```

Then open the Workbench URL printed in the logs (defaults to `http://127.0.0.1:3000`).

See [Self-hosting overview](../self-hosting/index.md) for architecture, configuration, security,
and operations.

## Source development

Use this path if you are contributing to Provon or need to customize the source.

### Requirements

- Node.js 22 or newer
- pnpm 10.33.0 or newer
- Python 3.11+ if you plan to run local model services

### Clone and install

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

### Start the local development server

```bash
pnpm dev
```

This starts:

- the API server on `http://127.00.1:3001`
- the Workbench dev server on `http://127.0.0.1:3000`
- a TypeScript watch compiler for `services/node-server`

Local data is stored under `.provon/` in the repository root:

- metadata in libSQL/SQLite
- telemetry in DuckDB
- blobs on the local filesystem

Use a custom Workbench port when needed:

```bash
pnpm dev -- --port 3100
```

### Seed a local product tour

To inspect the Workbench without generating your own workload, seed an empty local database before
starting the server:

```bash
pnpm seed:local
pnpm dev
```

The seed command prints the test account, project API key, and inserted record counts. It refuses to
write into non-empty metadata, metering, or telemetry databases.

## Install the CLI only

The self-hosted installer already includes the CLI. If you only need the CLI against an existing
Provon deployment:

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

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

Authenticate with a project API key or with user delegation:

```bash
# Project API key
export PROVON_API_KEY="your_project_api_key"
export PROVON_API_URL="https://api.provon.dev/v1"

# Or log in through the browser
provon auth login
```

See [CLI authentication](../cli/authentication.md) and [CLI overview](../cli/index.md).

## Verify the installation

Run:

```bash
provon --version
```

For a self-hosted or source install, check that the Workbench loads and that you can create a
project. For any install path, the next step is the [Quickstart](./quickstart.md).