Skip to content

Concepts and Architecture

EctoSpace edited this page Nov 13, 2026 · 1 revision

Concepts and Architecture

The short version

IronVise sits between an AI agent and the things it does. Every proposed action is checked before it runs, executed inside a sandbox if allowed, and recorded in a ledger that anyone can verify later. Recording an action and preventing it are different things, and IronVise always says which one happened.

The cognitive loop

IronVise's own agent loop is a strict pipeline: Perceive, Propose, Verify, Commit, Execute.

flowchart LR
  Perceive[Perceive State] --> Propose[Propose Intent]
  Propose --> Policy[Policy Engine]
  Policy --> Guard[Guard Process]
  Guard --> Tripwire[Tripwire]
  Tripwire -->|allowed only| Commit[Commit to Ledger]
  Commit --> Execute[Execute Side Effect]
  Execute -->|observation scanned| Ledger[(Ledger: PostgreSQL or SQLite)]
  Commit -->|hash chain + Ed25519| Ledger
Loading
  1. Perceive. Restore agent state from the ledger (latest snapshot plus replayed events).
  2. Propose. The primary model returns a single JSON intent: run_command, read_file, http_get or complete.
  3. Verify. Policy engine, then guard, then tripwire. Any of them can refuse.
  4. Commit. Check the goal hash and append the action to the ledger, hash-chained and Ed25519-signed.
  5. Execute. Run the side effect under the sandbox, scan the output, and append it. Repeat until complete or the step limit.

The agent is the database. The Rust process is a transient worker; all durable state lives in the ledger and is restored on each run. Nothing is updated or deleted: the schema enforces append-only writes.

The four checks

Layer What it does
Policy engine TOML policy packs: allowed and forbidden actions, command rules, observation rules, approval gates. See Configuration.
Semantic guard A second model, in a separate guard-worker process, reviews each intent against the session goal. On by default for the CLI (GUARD_REQUIRED), off by default in the desktop app. Fails closed.
Strict schema A sealed intent schema with deny_unknown_fields; anything outside the four allowed keys is rejected.
Tripwire Structural rules: path traversal and symlink checks, domain allowlist and HTTPS, banned command patterns, shell metacharacter rejection, minimum justification length.

Outputs pass an output scanner (Unicode normalisation, regex, structural JSON extraction, base64 decoding) before they reach the ledger. SCANNER_SENSITIVITY sets how broad it is.

No model-based check is absolute. The guard raises the cost of prompt injection; it does not eliminate it. The deterministic layers have documented bypasses, listed in the threat model.

Enforce or record: the integration surfaces

Surface Can block Records
Native cognitive loop (ironvise audit) Yes Intents, actions, observations, refusals
Claude Code, Codex and Antigravity CLI hooks (ironvise hook) Yes, for mapped tools Allowed actions, refusals and (Claude Code, Codex) data receipts
MCP proxy (ironvise mcp-proxy) Yes Allowed calls, refusals, data receipts
SDK verify_intent / verifyIntent Yes, if the caller honours the verdict Nothing
NVIDIA OpenShell import (ironvise import-openshell) No (OpenShell enforces) Every imported decision, signed
Recording proxy (ironvise proxy) No Prompts, completions, flagged patterns
SDK event append No Caller-reported observations, unsigned

Details per surface: Agent Integrations.

The ledger

  • Backends. PostgreSQL (production, multi-agent) or SQLite (local, CI, desktop). Chosen with DATABASE_URL.
  • Hash chain. Each event's content_hash covers the previous hash, its sequence number, its payload, its session and its timestamp, so changing or removing an event breaks every link after it.
  • Signatures. Each session has its own Ed25519 key. Server-written events are signed; events a client appends through the API are hash-chained but unsigned, and verification reports them as such.
  • Snapshots are derived from the log for fast restarts.
  • Older ledgers keep verifying. Verification falls back through earlier hash layouts, so ledgers written by older versions verify without rewriting rows.
Feature SQLite PostgreSQL
serve, audit, replay, verify-session, report (including certificates), anchor-session, webhooks, verify-certificate, verify-vc Yes Yes
orchestrate, diff-audit, red-team No Yes
Several server instances on one database No Yes (scaling guide)

Evidence you can hand to someone else

  • .elc audit certificates, verified offline by verify-cert or in the browser. See Verification and Certificates.
  • W3C Verifiable Credentials: an Ed25519-signed VC-JWT per completed session, did:key based.
  • Reports: JSON, SARIF, HTML, GitHub Actions and GitLab Code Quality.
  • Timestamps: the ledger tip hash submitted to public OpenTimestamps calendars. Only the hash leaves the machine.
  • Data receipts: SHA-256 of what each tool returned, never the data itself, so whoever holds a file can later show it is exactly what the agent read.
  • Webhooks / SIEM: signed deliveries in JSON, CEF or LEEF.

Receiver binding

Nothing private leaves IronVise valid for whoever finds it:

  • Providers' encrypted reasoning never reaches the ledger; only its SHA-256 does.
  • Webhooks are signed for one receiver; the SDK verifiers refuse other receivers' deliveries, stale ones and replays.
  • Hook and SDK requests are bound to their token, and a replay is refused.
  • Receipts (.elc, VCs) stay public on purpose.

Honest limits

  • IronVise governs only what runs through it. An agent or attacker acting outside its loop is invisible to it.
  • The ledger is tamper-evident, not tamper-proof. Someone with database access who rewrites history can also swap the session key and re-sign; a kept certificate, an expected key obtained separately, an issuer key, and timestamp anchoring are what defend against that.
  • A certificate proves the file was not altered and who signed it. It does not prove that everything that happened was recorded.
  • Certificates and credentials are supporting evidence for your compliance process, not a legal guarantee. Software cannot be "ISO 42001 certified"; organisations are.

Repository layout

Crate Role
crates/core Pure logic with no I/O: hashing, Merkle tree, intents, policy
crates/host The application: ironvise, guard-worker, verify-cert, the server, agent loop, ledger backends
crates/elc The .elc format and its offline verifier
crates/elc-wasm The same verifier compiled for the browser
crates/ledger-api The pluggable ledger backend trait
crates/compliance OpenTimestamps anchoring and Verifiable Credentials
crates/llm Model provider backends
crates/sandbox OS sandboxes, Docker and Firecracker tiers
gui/ The Tauri 2 desktop app
sdk/python, sdk/typescript The client SDKs

Full map: docs/reference/architecture.md. Event layout and hash scheme: docs/reference/schema.md.

Clone this wiki locally