Server

Architecture and data dictionary

Evaluation server components, request flow, durable tables, and privacy-safe audit field reference.

This page is the operator-facing map of a self-run Limetry evaluation server: how an action intent moves through evaluate → decision → audit (and optional approval), which Postgres tables hold durable state, and which fields belong in audit storage versus logs.

Source of truth for the HTTP contracts is the OpenAPI document shipped with @limetry/server (packages/server/public/openapi.yaml). Schema versions are tracked under versions/.

System architecture

  1. 01ClientAgent, SDK, CLI, MCP, or adapter drafts an ActionIntent
  2. 02EvaluateAuth, policy registry, and action evaluator on the server
  3. 03Decideallow, deny, or approval_required with a signed receipt
  4. 04EnforceYour middleware runs or skips the tool, then records outcome

Inside the evaluation server

  • Policy registryDurable ActionPolicy per tenant
  • Approval storePending rows bound to payload hash
  • Audit storePrivacy-safe policy.evaluated / action.recorded

Full intent is used for policy matching. Audit stores a scrubbed projection (minimal by default). Optional Redis covers nonce, throttle, and JWT revocation across instances.

ComponentRole
Agent / adapterDrafts ActionIntent, enforces allow / deny / approval_required
Evaluation APIPOST /v1/policy/evaluate, POST /v1/actions/record, GET /v1/audit
Policy registryDurable ActionPolicy documents per tenant
Approval storePending rows bound to a payload hash until a reviewer resolves them
Audit storeAppend-only privacy-safe events (policy.evaluated, action.recorded, …)
Optional RedisNonce / replay window, throttle helpers, JWT revocation across instances

Policy matching uses the full intent. Audit persists a projected intent after secret scrubbing. Default audit_mode is minimal. See Minimize audit data.

Request flow

  1. Authenticate — static bearer, JWT, or scoped API token.
  2. Evaluate — load policy by policy_id, match action type / resource / cost / approval knobs, return decision + reasons (+ signed receipt when DECISION_HMAC_SECRET is set).
  3. Approve (optional) — if approval_required, persist a pending approval keyed by decision_id and payload_hash; adapters resume only after an approve that matches the hash.
  4. Enforce — your loop or middleware skips or executes the tool.
  5. Record — POST /v1/actions/record with executed / skipped / blocked.
  6. Audit — both evaluate and record append privacy-safe rows; operators tail them with limetry audit tail or MCP.

Tenancy and identity

ConceptMeaning
tenant_id / organization_idIsolation boundary for policies, tokens, audit, and users
agent_idLogical agent or automation identity the policy governs
policy_idStable policy document id (UUID in most setups)
intent_idCaller correlation / idempotency key for one proposed action
decision_idServer-issued id tying evaluate → approval → record

Tokens are scoped (policies:read, audit:read, and related scopes). Prefer scoped API tokens over a shared admin bearer in production. See Run production operations.

Durable store (Postgres)

When USE_POSTGRES_STORE=true, the server migrates these tables on startup (packages/server/src/services/postgres-store.ts).

limetry_policies

ColumnTypeDescriptionSensitive
tenant_idtextTenant scopeno
policy_idtextPolicy document idno
policy_jsonjsonbFull ActionPolicy documentlow
created_attimestamptzInsert timeno
updated_attimestamptzLast upsertno

Primary key: (tenant_id, policy_id).

limetry_audit_log

ColumnTypeDescriptionSensitive
idbigserialMonotonic event idno
tenant_idtextTenant scopeno
event_typetexte.g. policy.evaluated, action.recordedno
subject_idtextDecision id, intent id, or related subjectno
detailsjsonbPrivacy-safe projection (see below)maybe
created_attimestamptzEvent timeno

Retention: LIMETRY_AUDIT_RETENTION_DAYS (purge job when Postgres is enabled).

limetry_governance_state

ColumnTypeDescriptionSensitive
tenant_idtextTenant scopeno
agent_idtextAgent identityno
policy_idtextPolicy idno
state_jsonjsonbPer-agent governance counters / windowslow
updated_attimestamptzLast writeno

limetry_users / limetry_access_tokens / limetry_rules

Operator accounts, hashed passwords, scoped API tokens, and legacy rule rows for self-hosted JWT setups. Treat password_hash and raw token values as secrets. Never log them.

With USE_POSTGRES_STORE=true, pending approvals default to the in-memory approval store for that process. The SQLite file store persists approvals in limetry_approvals (see below). Plan multi-instance approval durability accordingly, or keep evaluate sticky to one instance until a Postgres approval table ships.

SQLite store extras

When Postgres is off, the server uses a SQLite file (see Self-run the server). In addition to the same logical tables, SQLite persists approvals:

limetry_approvals

ColumnTypeDescriptionSensitive
idtextApproval idno
tenant_idtextTenant scopeno
decision_idtextEvaluate decision idno
policy_idtextPolicy idno
agent_idtextAgent identityno
action_typetextIntent action typeno
resourcetextScrubbed resource stringmaybe
payload_hashtextSHA-256 of original intent JSONno
intenttext/jsonIntent snapshot for re-bindmaybe
reasonstext/jsonWhy approval was requiredlow
statustextpending / approved / denied / expiredno
reviewertextReviewer identity when resolvedlow
created_attextCreate timeno
expires_attextExpiryno
resolved_attextResolve timeno

API contracts (evaluate path)

ActionIntent (evaluate input)

FieldTypeRequiredNotes
intent_idstringyesCorrelation / idempotency
policy_idstringyesPolicy to load
agent_idstringyesMust match policy agent
action_typestringyese.g. http_post, shopify.refund
resourcestringyesURL, ARN, table, Shopify gid, …
cost{ amount_minor, currency }noCost caps / approval thresholds
metadataRecord<string, string>noDo not put secrets or transcripts
issued_atstring (ISO-8601)yesIssue time
noncestring | numbernoReplay protection when enabled

ActionPolicy (stored document)

FieldTypeNotes
policy_idstringStable id
versionnumberMonotonic policy revision
organization_idstringTenant / org
agent_idstringGoverned agent
allowed_action_typesstring[]Allow-list
denied_action_typesstring[]Always deny
allowed_resource_patternsstring[]Glob allow
blocked_resource_patternsstring[]Glob deny
max_cost_minor / currencynumber / stringCost ceiling
require_approval_action_typesstring[]Force approval by type
require_approval_resource_patternsstring[]Force approval by resource
approval_cost_minornumberForce approval by cost
audit_modeminimal | forensicsAudit projection depth
statusstringLifecycle
effective_from / expires_atstring | nullOptional window

Decision outcomes

OutcomeMeaning
allowAdapter may execute (still enforce locally)
denyAdapter must not execute
approval_requiredHold until approve with matching payload_hash

Audit details dictionary

Audit rows never intend to store raw credentials. Client helpers (redactActionIntent, projectIntentForAudit) and server-side scrubbing both run. Default mode omits open metadata bags.

policy.evaluated details

FieldminimalforensicsNotes
approvedyesyesBoolean evaluation result
reasonsyesyesHuman-readable reasons
policy_idyesyesPolicy id
agent_idyesyesFrom projected intent
action_typeyesyesFrom projected intent
resourceyesyesScrubbed (no userinfo / query / hash)
audit_modeyesyesMode used for this row
intentprojectedprojected + redacted metadataSee intent projection
legacyoptionaloptionalCompatibility flag

action.recorded details

FieldminimalforensicsNotes
outcomeyesyesexecuted | skipped | blocked
decision_idyesyesCorrelated decision, if any
agent_id / action_type / resourceyesyesFrom projected intent
audit_modeyesyesMode used for this row
intentprojectedprojected + metadataSame projection rules
detailsomittedredacted objectOpen bag only in forensics

Intent projection fields

Fieldminimalforensics
intent_idyesyes
policy_idyesyes
agent_idyesyes
action_typeyesyes
resourcescrubbedscrubbed
costyesyes
issued_atyesyes
metadataomittedredacted
nonceomittedomitted

Logging rules

Application logs should carry operational identifiers only:

  • Prefer: tenant_id, agent_id, policy_id, intent_id, decision_id, event_type
  • Avoid: passwords, API tokens, Authorization headers, full intent metadata, chat transcripts, raw webhook bodies

Audit storage is the place for decision history. Process logs are for operations. Keep them separate.