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"]
  api --> metering["Metering store"]
  evidence --> blobs["Blob / staging store"]
  evidence --> telemetry["Telemetry store"]
  evidence --> jobs["Background execution"]
  jobs --> telemetry
  jobs --> meta
  jobs --> metering
  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#

flowchart TD
  proxy["Reverse proxy"] --> node["node-server"]
  node --> app["Workbench + API + Gateway + OTLP"]
  node --> loops["In-process background loops"]
  node --> meta["libSQL / SQLite metadata"]
  node --> telemetry["DuckDB or MotherDuck telemetry"]
  node --> blobs["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;
• model process lifecycle is owned by the Node runtime, which controls optional standalone Python services for inference (services/python-inference) and fine-tuning (services/python-fine-tuning) over HTTP.

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#

flowchart TD
  pages["Cloudflare Pages<br/>Workbench"] --> api["API Worker<br/>identity, control API, reads"]
  gateway["Gateway Worker<br/>model traffic and policy"] --> kv["KV<br/>Gateway runtime cache"]
  gateway --> queues["Queues<br/>ingest, summaries"]
  otlp["OTLP Worker<br/>acceptance and staging"] --> r2["R2<br/>blobs and staged payloads"]
  otlp --> queues
  queues --> jobs["Jobs Worker<br/>queue consumers, diagnostics, summaries, cron"]
  jobs --> d1["D1<br/>metadata"]
  api --> d1
  jobs --> durable["Durable Objects<br/>Gateway usage and target state"]
  jobs --> warehouse["Warehouse Worker<br/>deterministic telemetry shard routing"]
  warehouse --> container["Bounded Container pool<br/>Iceberg writes and retention deletes"]
  container --> catalog["R2 Data Catalog / Iceberg"]
  container --> r2
  api --> r2sql["R2 SQL<br/>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 deterministic warehouse shards while preserving organization-scoped data isolation.

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#

flowchart LR
  app["Agent application"] --> auth["Authenticate project API key"]
  auth --> policy["Load routing, provider, usage, and guardrail policy"]
  policy --> credential["Decrypt selected provider credential"]
  credential --> provider["Model provider"]
  provider --> response["Provider-compatible response"]
  response --> evidence["Queue trace evidence"]
  evidence --> telemetry["Project telemetry and 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#

flowchart LR
  exporter["OTel exporter"] --> validate["Validate auth, body size, and signal support"]
  validate --> stage["Stage accepted payload"]
  stage --> queue["Queue ingest job"]
  queue --> worker["Decode and normalize"]
  worker --> store["Write spans, logs, or metrics"]
  store --> summaries["Trace summaries and 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, metering, and telemetry independently at a coordinated recovery point. Metadata contains the tenant model and encrypted credentials; metering contains billing facts; telemetry contains the evidence those records reference.

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