<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#0a1018">
<meta name="description" content="Install Tempus DDB, run a local demo, provision an executor and connect MCP. Practical integration steps and protocol reference.">
<link rel="canonical" href="https://julio-patron.github.io/tempus-ddb/docs.html">
<meta property="og:title" content="Documentation · Tempus DDB">
<meta property="og:description" content="Install Tempus DDB, run a local demo, provision an executor and connect MCP. Practical integration steps and protocol reference.">
<meta property="og:type" content="website">
<meta property="og:url" content="https://julio-patron.github.io/tempus-ddb/docs.html">
<meta property="og:image" content="https://julio-patron.github.io/tempus-ddb/og.png">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="Documentation · Tempus DDB">
<meta name="twitter:description" content="Install Tempus DDB, run a local demo, provision an executor and connect MCP. Practical integration steps and protocol reference.">
<meta name="twitter:image" content="https://julio-patron.github.io/tempus-ddb/og.png">
<link rel="icon" type="image/png" href="assets/logo.png">
<link rel="stylesheet" href="assets/site.css">
<script type="module" src="assets/site.mjs"></script>
<title>Documentation · Tempus DDB</title>
</head>
<body class="page-docs">
<a class="skip-link" href="#main-content">Skip to content</a>
<header class="site-header">
<div class="shell header-inner">
<a class="brand" href="./" aria-label="Tempus DDB home"><img src="assets/tempus-logo-mineral.png" alt="Tempus — The Decision Database" width="1024" height="318"></a>
<button class="menu-toggle" type="button" aria-expanded="false" aria-controls="main-nav" hidden>Menu <span aria-hidden="true">☰</span></button>
<nav class="site-nav" id="main-nav" aria-label="Main navigation"><a href="./">Overview</a><a href="docs.html" aria-current="page">Documentation</a><a href="trace.html">Trace playground</a><a class="nav-source" href="https://github.com/Julio-Patron/tempus-ddb">GitHub <span aria-hidden="true">↗</span></a></nav>
</div>
</header>
<main id="main-content"><div class="shell"><header class="page-hero"><p class="eyebrow">Documentation / v0.5.4 beta</p><h1>From first install<br>to a verified action.</h1><p class="lede">Start with the local demo, then provision identities and an executor for your integration.</p><div class="meta-row"><span>Python 3.10+</span><span>Self-hosted</span><span>MIT licensed</span></div></header></div>
<div class="shell doc-layout"><aside class="doc-aside"><nav aria-label="On this page"><strong>GET STARTED</strong><a href="#install">01 Install</a><a href="#demo">02 Run a local demo</a><a href="#flow">03 Understand the flow</a><a href="#integration">04 Provision an executor</a><a href="#mcp">05 Connect through MCP</a><strong>REFERENCE</strong><a href="#contracts">Stable schemas</a><a href="#audit">Inspect traces</a><a href="#checkpoints">Checkpoints & recovery</a><a href="#boundary">Security boundary</a></nav><a class="aside-demo" href="trace.html">Just exploring?<br><strong>Try the playground →</strong></a></aside><div class="doc-content">
<article class="doc-card" id="install"><p class="eyebrow">01 / Install</p><h2>Install the Python package.</h2><p>Use Python 3.10 or newer. A virtual environment keeps the installation separate from your other projects.</p><div class="code-block"><div class="code-bar"><span>Terminal</span><button type="button" class="copy-button" data-copy hidden>Copy</button></div><pre><code>python -m venv .venv
# macOS / Linux
source .venv/bin/activate
# Windows PowerShell
# .venv\Scripts\Activate.ps1
python -m pip install tempus-ddb
tempus --help</code></pre></div><p>Download the package from <a href="https://pypi.org/project/tempus-ddb/">PyPI</a> or inspect the artifacts on <a href="https://github.com/Julio-Patron/tempus-ddb/releases">GitHub Releases</a>. For source development, follow <a href="https://github.com/Julio-Patron/tempus-ddb/blob/main/CONTRIBUTING.md">CONTRIBUTING.md</a>.</p></article>
<article class="doc-card" id="demo"><p class="eyebrow">02 / First verification</p><h2>Run the local security demo.</h2><p>With the package installed, clone the release source to get its examples. This demo uses a simulated downstream API and temporary local state.</p><div class="code-block"><div class="code-bar"><span>Terminal</span><button type="button" class="copy-button" data-copy hidden>Copy</button></div><pre><code>git clone --branch v0.5.4 --depth 1 https://github.com/Julio-Patron/tempus-ddb.git
cd tempus-ddb
python examples/commercial_demo.py</code></pre></div><div class="callout"><strong>What to look for</strong><p>An authorized execution and a verified trace, plus rejected bypass, replay, expired-permit, tamper and cross-tenant attempts. The local simulation does not require a real GitHub token.</p></div><p>Prefer to explore without installing? <a href="trace.html">Verify the browser sample</a>.</p></article>
<article class="doc-card" id="flow"><p class="eyebrow">03 / Request flow</p><h2>Four steps. Separate responsibilities.</h2><ol class="doc-steps"><li><strong>Sign the intent.</strong> The requesting agent signs the exact action, resource, input and idempotency key.</li><li><strong>Evaluate policy.</strong> Tempus checks identity and policy, then returns <code>ALLOWED</code> or <code>BLOCKED</code>.</li><li><strong>Execute through the boundary.</strong> The isolated executor verifies the permit, consumes it once and calls the external service.</li><li><strong>Verify the receipt.</strong> The executor signs its outcome; the gate records linked evidence for later inspection.</li></ol><p>The gate and executor remain trusted components. A signature verifies who signed an outcome; it does not make an external event independently observable.</p></article>
<article class="doc-card" id="integration"><p class="eyebrow">04 / Provisioning</p><h2>Establish the executor boundary.</h2><p>Run setup in a separate working directory for your integration. These commands create local development keys and register the two identities; they do not yet configure a production deployment.</p><div class="code-block"><div class="code-bar"><span>Terminal</span><button type="button" class="copy-button" data-copy hidden>Copy</button></div><pre><code>tempus init
tempus keygen --output agent.keys.json
tempus keygen --output executor.keys.json
tempus register-agent --alias demo-agent --agent-keyfile agent.keys.json --metadata '{"tenant_id":"acme"}'
tempus register-agent --alias demo-executor --agent-keyfile executor.keys.json --metadata '{"tenant_id":"acme"}'
tempus doctor --json
tempus conformance --signer</code></pre></div><p>Next, install a signed policy for your tenant, identities, supported action, resource and executor. See the <a href="https://github.com/Julio-Patron/tempus-ddb/tree/main/config">configuration examples</a> and <a href="https://github.com/Julio-Patron/tempus-ddb/blob/main/docs/blueprints/devops-mcp/product-blueprint.md">DevOps blueprint</a> for the complete setup.</p><div class="table-scroll"><table class="contract-table"><caption>Packaged executor commands</caption><thead><tr><th scope="col">Executor</th><th scope="col">Supported actions</th></tr></thead><tbody><tr><td><code>tempus-github-executor</code></td><td>Create issues and pull requests</td></tr><tr><td><code>tempus-http-executor</code></td><td>HTTPS POST, PUT and webhooks</td></tr><tr><td><code>tempus-slack-executor</code></td><td>Messages and alerts</td></tr><tr><td><code>tempus-payment-executor</code></td><td>Reference payment adapter; mock transport included</td></tr></tbody></table></div><p>Use each command's <code>--help</code> for its required permit, gate, tenant and executor options. Keep real downstream credentials in the executor environment. For workload signing, read the <a href="https://github.com/Julio-Patron/tempus-ddb/blob/main/docs/VAULT_TRANSIT_SIGNER.md">Vault Transit guide</a>.</p></article>
<article class="doc-card" id="mcp"><p class="eyebrow">05 / MCP connection</p><h2>Expose the autonomous tool surface.</h2><p>After provisioning, add Tempus to your MCP client's configuration. Replace the absolute paths below with the database and gate key created during setup.</p><div class="code-block"><div class="code-bar"><span>MCP configuration · JSON</span><button type="button" class="copy-button" data-copy hidden>Copy</button></div><pre><code>{
"mcpServers": {
"tempus": {
"command": "tempus",
"args": ["mcp", "start"],
"env": {
"TEMPUS_MODE": "autonomous",
"TEMPUS_GATE_KEYFILE": "/absolute/path/keys.json",
"TEMPUS_DB_PATH": "/absolute/path/tempus.db"
}
}
}
}</code></pre></div><p>The client must be able to find the installed <code>tempus</code> executable. The default tools accept signed payloads; connecting the server does not sign requests or route every other tool automatically.</p><p><a href="https://github.com/Julio-Patron/tempus-ddb/blob/main/cookbooks/mcp_cursor_claude_quickstart.md">Claude / Cursor recipe ↗</a> · <a href="https://github.com/Julio-Patron/tempus-ddb/tree/main/cookbooks">All framework recipes ↗</a></p></article>
<article class="doc-card" id="contracts"><p class="eyebrow">Reference / Contracts</p><h2>Versioned evidence schemas.</h2><div class="table-scroll"><table class="contract-table">
<caption>Core protocol schemas</caption><thead><tr><th scope="col">Evidence</th><th scope="col">Schema</th></tr></thead>
<tbody>
<tr><td>Agent intent</td><td><code>tempus.action-intent.v1</code></td></tr>
<tr><td>Signed permit</td><td><code>tempus.authorization-receipt.v1</code></td></tr>
<tr><td>Executor outcome</td><td><code>tempus.action-outcome.v1</code></td></tr>
<tr><td>Execution receipt</td><td><code>tempus.execution-receipt.v1</code></td></tr>
<tr><td>Complete trace</td><td><code>tempus.action-trace.v1</code></td></tr>
<tr><td>Verification result</td><td><code>tempus.trace-verification.v1</code></td></tr>
<tr><td>Event stream item</td><td><code>tempus.event-stream-event.v1</code></td></tr>
<tr><td>Signed checkpoint</td><td><code>tempus.checkpoint.v1</code></td></tr>
<tr><td>Checkpoint verification</td><td><code>tempus.checkpoint-verification.v1</code></td></tr>
</tbody>
</table></div><p>Read the <a href="https://github.com/Julio-Patron/tempus-ddb/blob/main/COMPATIBILITY.md">compatibility policy</a> before upgrading a deployed integration.</p></article>
<article class="doc-card" id="audit"><p class="eyebrow">Reference / Audit</p><h2>Inspect and verify a real trace.</h2><p>Use the action ID returned by your runtime. Run these commands against the corresponding gate database.</p><div class="code-block"><div class="code-bar"><span>Terminal</span><button type="button" class="copy-button" data-copy hidden>Copy</button></div><pre><code>tempus trace --action-id <action-id>
tempus verify-trace --action-id <action-id>
tempus list-agents
tempus list-policies
tempus identity-events</code></pre></div><div class="callout"><strong>Verified does not mean succeeded.</strong><p>A failed execution can have authentic, correctly linked evidence. Verification and business outcome are separate results.</p></div></article>
<article class="doc-card" id="checkpoints"><p class="eyebrow">Reference / Durability</p><h2>Retain checkpoints independently.</h2><p>Create a signed checkpoint and export the event stream. Store trusted checkpoints outside the database host so that a valid older snapshot can be recognized as a rollback.</p><div class="code-block"><div class="code-bar"><span>Terminal</span><button type="button" class="copy-button" data-copy hidden>Copy</button></div><pre><code>tempus checkpoint create --tenant-id acme --out checkpoint-acme.json
tempus checkpoint export --tenant-id acme --from-seq 1 --out stream-acme.json
tempus checkpoint verify --checkpoint checkpoint-acme.json --stream stream-acme.json</code></pre></div><p>Follow the <a href="https://github.com/Julio-Patron/tempus-ddb/blob/main/docs/BACKUP_AND_DISASTER_RECOVERY.md">backup and disaster recovery procedures</a> for retention and reconciliation.</p></article>
<article class="doc-card" id="boundary"><p class="eyebrow">Reference / Security</p><h2>Know the current limits.</h2><ul><li>Agent access to downstream credentials makes the executor boundary bypassable.</li><li>Multi-instance executors need shared transactional consumption state; the current local guarantees do not establish distributed replay safety.</li><li>Raw evidence is not automatically confidential. Plan how you handle sensitive payloads.</li><li>The payment adapter requires your own real provider integration; Tempus does not supply custody or transaction reversal.</li></ul><p><a href="https://github.com/Julio-Patron/tempus-ddb/blob/main/THREAT_MODEL.md">Full threat model ↗</a> · <a href="https://github.com/Julio-Patron/tempus-ddb/blob/main/ROADMAP.md">Roadmap ↗</a> · <a href="https://github.com/Julio-Patron/tempus-ddb/blob/main/SECURITY.md">Security reporting ↗</a></p></article>
</div></div></main>
<footer class="site-footer"><div class="shell footer-grid"><div><a class="footer-brand" href="./">Tempus DDB</a><p>Authorization before action.<br>Evidence after execution.</p><span class="small">Open source · MIT · v0.5.4 beta</span></div><nav aria-label="Resources"><strong>Build</strong><a href="docs.html">Documentation</a><a href="trace.html">Trace playground</a><a href="https://github.com/Julio-Patron/tempus-ddb/tree/main/cookbooks">Cookbooks</a><a href="https://pypi.org/project/tempus-ddb/">Python package</a><a href="https://crates.io/crates/tempus-ddb">Rust crate</a><a href="https://docs.rs/tempus-ddb">Rust API docs</a><a href="https://github.com/Julio-Patron/tempus-github-app">GitHub App</a></nav><nav aria-label="Project"><strong>Project</strong><a href="https://github.com/Julio-Patron/tempus-ddb">Source code</a><a href="https://github.com/Julio-Patron/tempus-ddb/blob/main/ROADMAP.md">Roadmap</a><a href="https://github.com/Julio-Patron/tempus-ddb/blob/main/THREAT_MODEL.md">Threat model</a><a href="https://github.com/Julio-Patron/tempus-ddb/blob/main/SECURITY.md">Report a vulnerability</a></nav></div><div class="shell footer-bottom"><span>Python 3.10+ · Rust native extension · MCP</span><a href="#main-content">Back to top ↑</a></div></footer>
<p class="sr-only" id="copy-status" role="status"></p>
</body>
</html>
