# Self-host Provon

Self-hosting keeps the Provon application, control data, trace evidence, credentials, and operational
policy inside infrastructure that you operate. Provon does not require a hosted Provon control plane:
the Workbench, API, Gateway, OTLP ingest, diagnostics, and background jobs are part of the deployment.

This is different from running a [self-hosted model](./model-providers.md#local-and-private-models).
A `self/*` model is an inference target behind the Gateway; self-hosting Provon is about where the
Provon platform runs.

## Choose A Runtime

Provon has two self-hosting architectures.

| Runtime    | Choose it when                                                                | Operational shape                                                                    |
| ---------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| Node       | You want the shortest path to a private VM, container, or single-server setup | One process serves Workbench, API, Gateway, OTLP, local jobs, and local models       |
| Cloudflare | You want independently scalable edge surfaces in your own Cloudflare account  | Pages, Workers, Queues, D1, KV, R2, R2 SQL, Data Catalog, Durable Objects, Container |

Both runtimes use the same project, API-key, Gateway, trace, Rule, Run, and Finding semantics. The
choice changes deployment and storage responsibilities, not the product model.

### Start With Node

Use [Node self-hosting](./self-hosting-node.md) for:

- a first production deployment;
- a private network, VM, bare-metal host, or Docker platform;
- one public origin for the Workbench, API, Gateway, and OTLP;
- local DuckDB telemetry or a MotherDuck-backed telemetry service;
- Node-only local model execution.

The built-in Node queues and runtime state are local to one data directory. Operate one active Node
instance unless you replace those adapters with shared infrastructure. Running multiple replicas
against the same metadata database does not make local jobs or queues highly available.

### Choose Cloudflare For Split Surfaces

Use [Cloudflare self-hosting](./self-hosting-cloudflare.md) when:

- Gateway and OTLP traffic must scale independently from the Workbench;
- asynchronous ingest, summaries, diagnostics, and retention should use managed queues and cron;
- metadata belongs in D1 and telemetry belongs in R2 Data Catalog / Iceberg with R2 SQL reads;
- you can operate the required Cloudflare resources and deployment pipeline.

The Cloudflare runtime does not bundle the Node-only local model runtime. It can still route to
supported cloud and public provider targets.

## What You Operate

Self-hosting transfers the following responsibilities to your team:

| Area         | Responsibility                                                                   |
| ------------ | -------------------------------------------------------------------------------- |
| Availability | Runtime health, restart policy, capacity, queue lag, and dependency recovery     |
| Data         | Storage location, backups, restore tests, retention, and deletion policy         |
| Security     | TLS, network policy, identity providers, secret custody, and API-key rotation    |
| Upgrades     | Release selection, forward database migrations, rollout, verification, rollback  |
| Integrations | Provider credentials, OAuth applications, callback URLs, and outbound allowlists |
| Cost         | Compute, storage, telemetry growth, model-provider usage, and platform services  |

Provon applies project isolation and encrypts stored provider and connector credentials, but it
cannot choose your infrastructure controls, backup policy, or legal data boundary.

## Documentation Path

1. Read [Self-hosting architecture](./self-hosting-architecture.md) to understand planes, storage,
   and network flows.
2. Deploy either [Node](./self-hosting-node.md) or
   [Cloudflare](./self-hosting-cloudflare.md).
3. Set runtime, identity, storage, and connector values in
   [Configuration](./self-hosting-configuration.md).
4. Apply the [Security](./self-hosting-security.md) boundary before production traffic.
5. Define backup, monitoring, upgrade, and recovery procedures with
   [Operations](./self-hosting-operations.md).

For a local product walkthrough before self-hosting, use the [Quickstart](./quickstart.md).

## Production Gate

Do not send production evidence until:

- every public surface uses HTTPS;
- `AUTH_SECRET` is explicit, stable, backed up, and loaded from a secret manager;
- metadata, telemetry, blobs, and runtime state are on durable storage;
- backup and restore have been exercised;
- payload capture and retention match the data classification;
- sign-in, project API keys, Gateway, OTLP, diagnostics, and repair handoff are verified separately;
- logs and queue or background-job failures are monitored;
- the previous application version and a rollback procedure are available.

## Related Docs

- [Tracing in production](./tracing-production.md)
- [Production Gateway](./gateway-production.md)
- [Telemetry architecture](./telemetry.md)
- [Connectors](./connectors.md)
- [Troubleshooting](./troubleshooting.md)