Operating Modes

ProvenLog operates in two modes. Both provide the same hash-chained audit trail — the difference is where events are stored and how they’re accessed.

Embedded mode (default)

The SDK writes events directly to a local SQLite database. No server, no network, no infrastructure.

from provenlog import ProvenLogClient

# Writes to ~/.provenlog/events.db
client = ProvenLogClient(agent_id="my-agent")

Characteristics:

Zero setup — works immediately after pip install provenlog
Hash chain computed in-process
Database at ~/.provenlog/events.db (configurable)
No network dependency
Per-process isolation

Best for: Development, single-agent deployments, CI/CD pipelines, getting started.

Server mode

The SDK sends events to a plog serve instance via HTTP. The server coordinates hash chains, aggregates events from multiple agents, and serves the web dashboard.

# Start the server
plog serve

# Connect from Python
client = ProvenLogClient("http://localhost:7600", agent_id="my-agent")

# Connect from TypeScript
const client = new ProvenLogClient("http://localhost:7600", { agentId: "my-agent" });

Characteristics:

Multi-agent aggregation on a single server
Web dashboard at the server URL
WebSocket live streaming
REST API for queries and verification
Server-authoritative hash chain sequencing
Optional API key authentication

Best for: Production, multi-agent systems, team visibility, compliance workflows.

Choosing a mode

Consideration	Embedded	Server
Setup effort	None	Start `plog serve`
Infrastructure	None	One process
Multi-agent visibility	No	Yes
Web dashboard	No	Yes
Network dependency	No	Yes
Hash chain authority	In-process	Server

Switching modes

Switching is a one-line change — pass a URL to enable server mode, or omit it for embedded:

# Embedded (default)
client = ProvenLogClient(agent_id="my-agent")

# Server
client = ProvenLogClient("http://localhost:7600", agent_id="my-agent")

You can also control the mode via environment variables:

# Embedded with custom path
export PROVENLOG_DB_PATH=/tmp/audit.db

# Server mode
export PROVENLOG_SERVER_URL=http://localhost:7600

Getting Started

Core Concepts

SDKs

Integrations

Zero-Code Adapters

Features

Embedded mode (default)

Server mode

Choosing a mode

Switching modes

​Embedded mode (default)

​Server mode

​Choosing a mode

​Switching modes

Embedded mode (default)

Server mode

Choosing a mode

Switching modes