Guide

Deployment

Choose the right deployment shape for desktop, node, Cloudflare, or CLI usage.

Provon Deployment

Provon uses the same domain, API, storage, and Workspace modules across multiple entrypoints. You can start locally on a laptop, run a self-hosted Provon Node server, split surfaces across Cloudflare Workers, or connect external supply nodes through provond.

Deployment Shapes

Shape	Entrypoint	Best for	Storage and runtime
Desktop	`desktop`	Single Workspace on a developer machine	Electron + shared Node runtime, libSQL/SQLite, DuckDB, filesystem blob storage
Self-hosted Provon Node	`services/node-server`	VM, Docker, bare metal, private cloud	Hono Node server, libSQL/SQLite metadata, DuckDB telemetry, SQLite-backed queues
Cloudflare Edge	`services/cloudflare-worker`	Edge API, Workspace, Gateway, OTel, Supply, and background jobs	Workers, D1 metadata, R2 blobs, Queues, R2 SQL/Data Catalog, Iceberg telemetry
Supply node	`provond`	Registering and forwarding external OpenAI-compatible endpoints	Endpoint registry, probing, manifest generation, tunnel forwarding
CLI	`cli`	Command-line automation around the API	API client and shared core primitives

Choosing A Shape

Desktop

Use the desktop shape when you want a local Workspace for development, experiments, or single-user agent review. It keeps the product close to your machine while reusing the shared Node runtime.

Best fit:

Local exploration of Gateway, traces, Playground, and workflows.
Developer machines that need filesystem-backed blobs and local DuckDB telemetry.
Trying local/private model providers without committing to server infrastructure.

Self-Hosted Provon Node

Use the Node server when you want the simplest server deployment for a team or private environment. It serves the API and Workspace from one Node process and uses injected storage/runtime adapters.

Best fit:

VM, Docker, bare metal, or private cloud deployments.
Teams that want SQLite/libSQL metadata with DuckDB telemetry.
A single HTTP surface for API, Workspace, Gateway, and OTLP during self-hosted Provon operation.

Cloudflare Edge

Use the Cloudflare shape when you want split edge surfaces and managed platform primitives. The Cloudflare entrypoint separates API, Workspace, Gateway, OTel, Supply, and jobs surfaces so hot paths can be deployed independently.

Best fit:

Edge-hosted API, Gateway, and Workspace workloads.
D1 metadata, R2 blob storage, Cloudflare Queues, and Durable Objects.
Cloudflare R2 SQL reads with R2 Data Catalog / Iceberg-backed telemetry writes.
Deployments where Gateway and telemetry ingest should scale separately from the Workspace UI.

Supply Node

Use provond when you want to expose external OpenAI-compatible endpoints to Provon without embedding them directly into the control plane. A supply node registers endpoints, probes health, submits manifests, and forwards requests over the supply tunnel.

Best fit:

Local or remote model servers managed outside the main Provon runtime.
Endpoint probing and manifest submission.
Supplying external OpenAI-compatible backends through a signed node identity and short-lived

tunnel lease.

CLI

Use the CLI shape for automation around the API. It is not a runtime surface by itself; it is a command-line companion for scripting and operational workflows.

Storage Model

Provon separates metadata from telemetry so production agent evidence can grow independently from workspace state.

Store	Purpose	Typical engines
Metadata	Users, sessions, API keys, organizations, projects, memberships, workflows, settings	libSQL/SQLite for Node, D1 for Workers
Telemetry	OpenTelemetry spans, logs, metrics, trace summaries, usage, dashboards, retention data	Node/local: DuckDB; Workers: R2 Data Catalog / Iceberg and R2 SQL
Blobs	Trace attachments, OTLP staging payloads, exported artifacts, local or cloud blob bodies	Filesystem, R2, S3-compatible providers

Local Start

For the default local Node development stack:

pnpm install
pnpm dev

The Workspace runs at http://127.0.0.1:3000 by default.

For detailed development and Cloudflare deployment commands, see CONTRIBUTING.md.

For the current telemetry write, read, search, summary, and retention mechanisms, see Telemetry.