Skip to main content
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

ConsiderationEmbeddedServer
Setup effortNoneStart plog serve
InfrastructureNoneOne process
Multi-agent visibilityNoYes
Web dashboardNoYes
Network dependencyNoYes
Hash chain authorityIn-processServer

​
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