1. Install and start
datris container to log Started Application, then confirm:
2. Turn on the governed defaults
These are off in a fresh install so that existing deployments are unchanged. Add them to./datris/.env:
admin with no password; you are asked to set one before anything else works.
3. Set one policy rule
Configuration → Agent Policy → Use recommended. That starting point pauses deletes, job kills, and destination-type migrations for approval and refuses secret and configuration writes. Add one rule for this walkthrough: settap:run to Approve. From now on, any agent that tries to run a tap waits for a person.
4. Issue a scoped key for your agent
Configuration → API-Keys → Issue new key. Label it after the client (claude-desktop, cursor), pick the rag-builder template — it can create pipelines and taps and run the ones it created, and nothing else — and copy the value; it is shown once.
5. Connect your agent
Add the Datris MCP server to your client with the key from step 4. Claude Desktop (claude_desktop_config.json), Claude Code (.mcp.json in your project root), and Cursor all take the same snippet — see Configuring Claude for the file locations and the no-Docker alternative.
6. Ask the agent to build a tap against a public source
The USGS earthquake feed needs no credentials, so nothing has to be stored before the first run. Ask your agent:“Create a Postgres pipeline calledWatch the Agent Monitor:earthquakesand a tap calledusgs-earthquakesthat fetches the USGS ‘all earthquakes, past day’ GeoJSON feed at https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_day.geojson and produces one row per event with its id, time, place, magnitude, longitude, latitude, and depth. Test the tap so I can see a sample, but don’t run it yet.”
create_pipeline, create_tap, test_tap. The agent shows you a handful of sample rows. Nothing has been landed.
7. Turn on provenance stamping
In the UI: Catalog →earthquakes → Edit → Destination step → “Stamp provenance on landed data” → save. From the next run on, every row this pipeline lands carries six extra columns naming the run, the time, the config version, the tap run, the script commit, and the source. (Do this before the run rather than after — an approval executes exactly what was proposed, and a pipeline changed underneath a pending approval is refused as stale.)
8. Run it — and watch it wait for you
“Run the usgs-earthquakes tap.”
The agent calls run_tap and gets back pending_approval with an approval id instead of a result, because of the rule from step 3. It tells you so, and can poll get_approval while it waits. Nothing has run.
Open Activity → Approvals. The card shows exactly what will execute — the method, path, and body of the agent’s request, with the reason the agent gave, if any. Click Approve. The platform performs the original request on your behalf; the agent’s next poll sees it executed and it follows the load to completion with get_pipeline_status. Ask it to confirm:
“Did the run land? How many rows?“
9. Ask where a row came from
“Pick one row from earthquakes and tell me where it came from — the run, the tap run, the script commit, and the source.”
The agent reads the row’s _datris_run_id and calls get_provenance, which walks the chain and returns the pipeline run with its status and record count, the tap run that fed it, the pipeline definition version in force, and the declared source. You can see the raw stamp yourself:
_datris_script_sha is populated when the tap’s script is stored in a git repository — see Tap GitHub Storage.)
10. Read the record
Configuration → Audit Log. Two linked entries tell the whole story: the agent’s queuedtap:run request under its key label, and your approval executing it under your login. The pipeline and tap creations from step 6 are there too, attributed to the same key. Everything you just watched happen is now something you can answer questions about next month.
What you just saw
- An agent with a scoped key could build and test, but its run was gated by policy — enforced by the platform, not by a prompt.
- A person approved exactly what was proposed, and the platform executed it on their behalf.
- Every landed row carries provenance, and the agent can resolve it back to the run, script, and source.
- The audit log holds the request, the decision, and the result.
Next steps
- Agent Policy — the full action list, per-resource overrides, and approval limits
- Provenance, Lineage & Discovery — lineage graphs, freshness, and
find_data - Taps — schedules, incremental state, secrets for sources that need them
- Security Architecture — the whole model on one page for your reviewer
- Pipeline Configuration — everything a pipeline can do