01 / Install
Install the verified PyPI release.
Python 3.10+ is required. Tempus DDB is published to PyPI with Trusted Publishing and Sigstore attestation on every artifact — verify the provenance before you trust the binary, not just the package name.
python -m pip install tempus-ddb
The new guided commands below are in the current source revision and have not been released yet. From a checkout containing these changes, install with:
git clone https://github.com/elbuilder77/tempus-ddb.git
cd tempus-ddb
python -m pip install -e ".[dev]"
After installing the updated package, the walkthrough needs no checkout or examples directory. Continue to your first action.
02 / First action
Complete your first action
Start in a new directory. This single command creates identities, installs a policy restricted to one action/resource/executor, checks configuration, writes a local issue through the executor and verifies the signed result.
tempus quickstart --directory tempus-first-action
Expected: Authorization ALLOWED · Execution SUCCEEDED · Integrity VERIFIED. Open tempus-first-action/issue.json for the issue and result.json for its action ID and result. This local example makes no GitHub request.
Then create one real GitHub issue
Use a test repository and configure GITHUB_TOKEN in the executor environment with Issues: write for that repository. First prepare the trial; this makes no external request:
tempus quickstart --directory github-trial --github-repository YOUR_OWNER/YOUR_TEST_REPO
Inspect github-trial/policy.json. The next command explicitly creates one real issue and prints its URL and verification command:
tempus first-action --directory github-trial --execute-github
These are operator-run development trials. Production requires separate agent, Gate and executor environments. Existing directories are preserved and an existing permit is never executed again by the walkthrough.
Full recipe and recovery · Connect MCP using the generated mcp.json.
03 / Basic flow
Request and execution flow
- The agent signs an exact
tempus.action-intent.v1 request.
- Tempus verifies identity and deterministic policy, then returns
ALLOWED or BLOCKED.
- An executor with the downstream credential consumes an allowed permit once.
- The executor signs an outcome; Tempus records a linked receipt and a reader can verify the trace.
The requesting agent must not hold the executor's environment, credential or signing key. That separation—not a human approval click—is the security boundary.
04 / Stable contracts
Stable schemas
| Evidence | Schema |
|---|
| Agent intent | tempus.action-intent.v1 |
| Signed permit | tempus.authorization-receipt.v1 |
| Executor outcome | tempus.action-outcome.v1 |
| Execution receipt | tempus.execution-receipt.v1 |
| Complete trace | tempus.action-trace.v1 |
| Verification result | tempus.trace-verification.v1 |
| Event stream item | tempus.event-stream-event.v1 |
| Signed checkpoint | tempus.checkpoint.v1 |
| Checkpoint verification | tempus.checkpoint-verification.v1 |
Read the compatibility policy before changing a deployed integration.
05 / Trace inspection
Inspect and verify records
Enter the trial directory. Recover IDs from the action history or result.json, then verify the selected action:
cd tempus-first-action
tempus --keyfile gate.keys.json actions
tempus --keyfile gate.keys.json verify-trace --action-id <action-id>
tempus --keyfile gate.keys.json trace --action-id <action-id>
Filter history with --resource, --agent or --since; use --json for automation. A recorded ALLOWED decision, a recorded SUCCEEDED outcome and VERIFIED evidence answer different questions.
If something goes wrong
- Configuration pending: register identities and install a workload policy before doctor. A baseline policy is insufficient. doctor --github checks credential presence only.
- BLOCKED: inspect permit.json reason codes and the policy; the guided executor was not called.
- Expired: check executor state before requesting a new permit. Never edit an old permit.
- UNKNOWN or missing receipt: an effect may exist. Reconcile the executor and GitHub before another request; never automatically retry.
- INVALID: preserve evidence and investigate. Recorded authorization/execution values are untrusted.
The interactive trace demo verifies a synthetic browser fixture. It is not connected to a Tempus database, and it does not replace tempus verify-trace for a real action.
06 / Durability & DR
Checkpoints & Disaster Recovery
Restore the Gate and every executor database as a coordinated set, with issuance and dispatch stopped. Retrieve the latest independently trusted checkpoint, then export fresh events from the restored Gate:
# Replace range placeholders with values from the trusted checkpoint.
tempus --db /recovery/gate.db --keyfile /secure/gate.keys.json checkpoint export --tenant-id acme --from-seq FIRST_SEQUENCE --limit TOTAL_EVENTS --out /recovery/restored-events.json
tempus --db /recovery/gate.db --keyfile /secure/gate.keys.json checkpoint verify --checkpoint /independent/checkpoint-acme-latest.json --stream /recovery/restored-events.json
Verifying two compatible external files does not prove the restored database is current. This check covers the checkpoint's event range, not later events or the executor's consumed permits. Reconcile executor state and signed outcomes separately; missing consumption or UNKNOWN results must never trigger automatic replay.
See docs/BACKUP_AND_DISASTER_RECOVERY.md for full procedures.
07 / Security boundary
Current limits
v0.5.0 features durable local operations with external checkpoints. Distributed multi-container gate deployment with OpenTelemetry metrics and tenant quotas is targeted for Milestone 0.6.
Review the threat model before high-impact use, report issues through the security policy, and use the contribution guide to participate.
