The workspace database (.stencila/db.sqlite3) is a SQLite database that stores state for your Stencila workspace. It is organized by domain and currently holds:

Workflow run history — execution results, node metrics, context snapshots, artifacts, and logs.

Agent tool guard events — Warn and Deny verdicts from the tool guard system are recorded for post-hoc review. Each event captures the session, agent, trust level, tool name, input, matched segment, verdict, rule, and optional reason/suggestion. Allow verdicts are not recorded.

The database lives inside the .stencila/ directory and is excluded from git by default. This keeps your repository clean but means collaborators don't automatically get your database when they clone the project. The database sync system solves this by letting you push and pull database state through Stencila Cloud, with git tracking a small manifest file that describes how to reconstruct the database.

How sync works

The sync system splits storage into two parts:

Git tracks a small JSON manifest file (.stencila/db.json) that describes the database state: which base snapshot to use and which changesets to apply on top of it.

Stencila Cloud stores the actual data as content-addressed blobs: compressed database snapshots and incremental changesets.

The primary commands are push (upload local changes) and pull (download and apply remote changes). After pushing, you commit the updated manifest to git so collaborators can see it.

Getting started

See the syncing guide for step-by-step instructions on setting up sync, pushing your first database state, and keeping a team in sync.

How sync works

Getting started

Further reading