Self-hosting Architecture

Logical Planes#

flowchart LR
  users["Users"] --> workbench["Workbench"]
  apps["Agent applications"] --> gateway["Gateway"]
  apps --> otlp["OTLP ingest"]

  workbench --> api["Control API"]
  gateway --> providers["Model providers"]
  gateway --> evidence["Evidence pipeline"]
  otlp --> evidence

  api --> meta["Metadata store"]
  evidence --> blobs["Blob / staging store"]
  evidence --> telemetry["Telemetry store"]
  evidence --> jobs["Background execution"]
  jobs --> telemetry
  jobs --> meta
  jobs --> connectors["External connectors"]

The planes are logical ownership boundaries. Node runs them in one process. Cloudflare maps them to separate deployable surfaces and managed services.

Node Mapping#

reverse proxy
  -> node-server
       -> Workbench + API + Gateway + OTLP
       -> in-process background loops
       -> libSQL/SQLite metadata
       -> DuckDB or MotherDuck telemetry
       -> local blobs and persistent runtime state

The Node entrypoint is services/node-server. It composes the shared API and Node runtime, applies metadata migrations at startup, serves the built Workbench, and starts local background loops.

Node is intentionally a single-instance architecture with the default adapters:

• metadata can be local SQLite or remote libSQL;
• telemetry can be local DuckDB or MotherDuck;
• blobs, ingest queues, Gateway telemetry queues, summary queues, and other runtime state remain in the configured local data directory;
• local model process lifecycle is owned by the Node runtime.

Remote metadata or telemetry alone does not make the runtime horizontally scalable. Multiple active processes would have independent local queues and duplicate schedulers.

Cloudflare Mapping#

Cloudflare Pages -> Workbench
API Worker       -> identity, control API, reads
Gateway Worker   -> model traffic and policy
OTLP Worker      -> ingest acceptance and staging
Jobs Worker      -> queue consumers and scheduled work
Warehouse Worker -> organization-routed telemetry mutations
Container        -> Iceberg table writes and retention deletes

D1               -> metadata
KV               -> Gateway runtime cache
Queues           -> ingest, summaries, and workflow jobs
Durable Objects  -> Gateway usage and target state
R2               -> blobs, staged payloads, and Iceberg data
R2 SQL           -> telemetry reads

The split runtime keeps hot request paths independent:

• Workbench availability does not sit on the Gateway request path.
• OTLP acceptance can queue work before telemetry projection completes.
• the Jobs Worker owns queue consumption, diagnostics, summaries, retention, and scheduled maintenance;
• telemetry mutation runs behind an internal Service Binding and organization-scoped warehouse execution.

All resources live in the operator's Cloudflare account. There is no Provon-hosted administration plane that must be reachable for the deployment to function.

Request And Data Flow#

Gateway Request#

1. The application authenticates with a project API key.
2. Gateway loads project routing, provider, usage, and guardrail policy.
3. Gateway decrypts the selected project provider credential inside the runtime.
4. The request is sent to the selected model provider.
5. The response returns through Gateway while trace evidence is queued.
6. Background processing projects the evidence into telemetry and updates derived summaries.

Prompts and responses leave the deployment when the selected provider is external. A private Provon deployment does not make an external model provider private.

OTLP Ingest#

1. The exporter sends OTLP/HTTP with a project API key.
2. Provon validates authentication, body size, and signal support.
3. The accepted payload is staged and queued.
4. A worker decodes, normalizes, and writes spans, logs, or metrics.
5. Trace summaries become visible and can trigger workflows or diagnostic Rules.

Acceptance and visibility are asynchronous. A successful ingest response proves durable acceptance for that runtime; trace visibility is a separate verification gate.

Control And Connector Flow#

Workbench sessions call the Control API. Provider keys, connector credentials, and OAuth tokens are encrypted before they are stored in metadata. Connector actions and OAuth handshakes create outbound requests to the configured external systems.

Storage Boundaries#

Back up metadata independently from telemetry. Metadata contains the tenant model and encrypted credentials; telemetry contains the evidence those records reference. Restoring only one can leave links incomplete even when both stores are individually valid.

Network Boundary#

Required inbound paths depend on enabled features:

Potential outbound paths include:

• configured model providers;
• sign-in identity providers;
• Connector OAuth and API endpoints;
• MotherDuck when selected by the Node runtime;
• package registries and Cloudflare APIs during build or deployment.

The core runtime can remain on a private network when all callers are private, model execution is local, and external identity and connectors are disabled. Document each enabled egress dependency instead of assuming an air-gapped deployment.

Failure Boundaries#

Design health checks and alerts around these boundaries. /healthz reports runtime liveness and version; it is not a complete dependency or end-to-end evidence check.

Next Steps#

• Deploy Node
• Deploy on Cloudflare
• Configure self-hosting
• Secure the deployment
• Operate the deployment