> ## Documentation Index
> Fetch the complete documentation index at: https://docs.provenlog.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Operating Modes

> Embedded mode vs Server mode

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.

```python theme={null}
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.

```bash theme={null}
# 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:

```python theme={null}
# 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:

```bash theme={null}
# Embedded with custom path
export PROVENLOG_DB_PATH=/tmp/audit.db

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