Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

Human Approvals via Dashboard and CLI

When a policy evaluates to APPROVAL_REQUIRED, Dmint persists one PENDING record and halts. A human reviews the exact request, approves or rejects it, and — if approved — gives the protected host a signed assertion for the retry.
The approval itself does not execute the tool. Execution happens only when the host calls engine.retry(...) (or MCP retries with an assertion argument) and Core verifies and consumes that assertion.

Approval Lifecycle

APPROVAL_REQUIRED │ ▼ PENDING ── reject ──► REJECTED │ approve │ ▼ APPROVED ── download/issue assertion ──► host retry │ │ │ verify + consume │ │ │ ▼ │ CONSUMED └── policy changed / expired ──► POLICY_INVALIDATED / EXPIRED
The record is bound to the full request envelope. An approval for arguments A cannot be used for arguments B; a consumed assertion cannot be replayed.

Method 1: Web Dashboard

The dashboard is a local FastAPI application. It accesses approvals exclusively through dmint.dashboard.CoreClient and Core public APIs; it never issues SQL directly.

Start the dashboard

dmint dashboard \ --db-path ./approvals.sqlite3 \ --approver-id alice@example.com \ --authority-issuer dmint-authority \ --port 8080
For PostgreSQL:
dmint dashboard \ --database-url "postgresql://user:pass@localhost:5432/dmint" \ --deployment-epoch production \ --approver-id alice@example.com \ --authority-issuer dmint-authority
Defaults:
  • bind: 127.0.0.1:8080;
  • signing key: ~/.config/dmint/signing.key (override with --key-file or DMINT_KEY_FILE);
  • authority issuer: dmint-dashboard (this example sets dmint-authority so the host verifier can use the issuer printed by dmint init-keys);
  • approval audience: dmint/dashboard/v1.
A non-loopback bind is refused unless --allow-public-bind is explicit, and it still requires authentication. Prefer loopback behind a reverse proxy.

Authentication

Set a token inline or from a permission-restricted file:
export DMINT_DASHBOARD_TOKEN="$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')" dmint dashboard --db-path ./approvals.sqlite3 # Or: dmint dashboard --db-path ./approvals.sqlite3 --token-file /etc/dmint/dashboard.token
Token files must be mode 0600. If no token is configured, the dashboard generates a one-time token and prints it in the startup banner. The dashboard also enforces host/origin checks, CSRF tokens, session timeouts, and login rate limiting.

Approver identity attribution

The dashboard distinguishes three identity sources:
SourceMeaning
self-assertedThe label was typed into the login form. It is an audit label, not proof of identity.
trusted_proxyThe label came from a configured trusted reverse-proxy header.
shared-tokenAPI access with the shared bearer token; no individual human was authenticated.
To use a trusted reverse proxy, configure both the proxy mode and the header name. Configuring DMINT_DASHBOARD_IDENTITY_HEADER without enabling trusted-proxy mode is rejected at startup rather than silently ignored. For example:
export DMINT_DASHBOARD_TRUSTED_PROXY=1 export DMINT_DASHBOARD_IDENTITY_HEADER=X-Auth-User dmint dashboard \ --db-path ./approvals.sqlite3 \ --trusted-proxy
The reverse proxy must strip any client-supplied X-Auth-User header and set it from the authenticated session. If the header is configured and missing at login, the dashboard fails the login with 401 and does not create a session. It never falls back to the form value in trusted-proxy mode. If the header disappears from an existing session, approval, rejection, and assertion-download requests fail with 401 instead of being attributed to an unauthenticated label.
The form label is displayed with a self-asserted badge. Do not describe it as independently verified identity.

Review and decide

  1. Open http://127.0.0.1:8080 and sign in.
  2. Open the pending approval. The detail page shows tool/action, agent, resource, canonical arguments, timestamps, expiry, and policy provenance.
  3. Click Approve or Reject. Approval records the session identity and transitions PENDING → APPROVED.

Download the retry assertion

After approval, the detail page shows Download assertion artifact. The button calls:
GET /approvals/{approval_id}/assertion
The endpoint requires an authenticated session, issues a fresh signed assertion for the APPROVED record, and returns it as:
Content-Type: application/octet-stream Content-Disposition: attachment; filename="{approval_id}.assertion.json" Cache-Control: no-store
The artifact is a single-use credential. Treat it like a secret: do not place it in prompts, chat logs, agent memory, or dashboards. Download only after approval; a PENDING record returns 409 (assertion_not_available).
The first assertion created internally during approve_pending() is discarded. The download endpoint re-issues a fresh assertion for the same approved record, which avoids exposing a credential in the redirect response.

Method 2: Terminal CLI

List pending requests

dmint pending --db-path ./approvals.sqlite3
APPROVAL ID TOOL/ACTION RESOURCE/TARGET PRINCIPAL REQUESTED ---------------- --------------------- --------------- ---------------- --------- apr_... ledger.transfer_funds (none) finance-agent-01 2m ago
Use --database-url / DMINT_DATABASE_URL for PostgreSQL, and --deployment-epoch when the store uses a non-default epoch.

Approve and write the assertion

dmint approve apr_... \ --db-path ./approvals.sqlite3 \ --policy ./policy.json \ --approver-id alice@example.com \ --authority-issuer dmint-authority \ --reason "Verified ticket #1204" \ --output-assertion ./approval.json
✓ Approved 'apr_...' (ledger.transfer_funds) successfully. Reason: Verified ticket #1204
--policy makes the CLI re-verify the current policy file and fail closed if it no longer allows the request. If omitted, the CLI first uses the store’s authoritative policy, then a local policy.json if present. approve automatically persists the signed Ed25519 assertion inside the approval store so local hosts (Dmint.local(), dmint-mcp, and dmint hook run) can consume it automatically on retry. Pass --output-assertion ./approval.json if you also want to export the signed assertion file to a separate host.
The CLI never executes the protected tool. It only transitions the record and optionally writes the assertion.

Reject

dmint reject apr_... \ --db-path ./approvals.sqlite3 \ --reason "SQL targets an unapproved table"
Any retry after rejection fails closed. A rejected approval cannot be “un-rejected”; create and review a new request.

Executing the Approved Retry

Python host

from pathlib import Path # Option A: Automatic store lookup (when sharing the same SQLite/Postgres store): result = engine.retry(transfer_funds, "acc_100", 500.0) # Option B: Explicit assertion bytes (from --output-assertion or dashboard download): result = engine.retry( transfer_funds, "acc_100", 500.0, approval_credential=Path("./approval.json").read_bytes(), )
The callable and keyword/positional arguments must be the same as the original invocation. engine.retry verifies the signature and binding, re-evaluates the current policy, atomically consumes the approval, and then executes the function once.

MCP gateway

Add the assertion under one reserved argument key:
{ "method": "tools/call", "params": { "name": "update_database", "arguments": { "record_id": 42, "action": "archive", "_dmint_approval": "<assertion-json-string-or-object>" } } }
Aliases dmint_approval and approval_credential are also accepted. The gateway removes the reserved key before forwarding clean arguments downstream.

Deployment epochs

The runtime and approver must use the same deployment epoch. An assertion issued under one epoch cannot be consumed under another (DMT_APPROVAL_DEPLOYMENT_INVALID). Configure this on the engine/store, CLI, dashboard, and MCP gateway consistently.

Failure Semantics

SituationResult
Approval for $250, retry for $251DMT_APPROVAL_REQUEST_MISMATCH; no execution
Assertion replayed after consumptionDMT_APPROVAL_CONSUMED; no execution
Policy digest/version changed after approvalDMT_APPROVAL_POLICY_INVALID; no execution
Record expiredDMT_APPROVAL_EXPIRED; create a new request
Wrong issuer/public keyDMT_APPROVAL_ISSUER_INVALID or DMT_APPROVAL_SIGNATURE_INVALID
Trusted proxy identity header missingLogin fails closed; no session
Download requested for a non-approved record409; no assertion

Next Steps