Repository navigation
Concepts and Architecture
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.
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
- Perceive. Restore agent state from the ledger (latest snapshot plus replayed events).
-
Propose. The primary model returns a single JSON intent:
run_command,read_file,http_getorcomplete. - Verify. Policy engine, then guard, then tripwire. Any of them can refuse.
- Commit. Check the goal hash and append the action to the ledger, hash-chained and Ed25519-signed.
-
Execute. Run the side effect under the sandbox, scan the output, and append it. Repeat until
completeor 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.
| 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.
| 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.
-
Backends. PostgreSQL (production, multi-agent) or SQLite (local, CI, desktop). Chosen with
DATABASE_URL. -
Hash chain. Each event's
content_hashcovers 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) |
-
.elcaudit certificates, verified offline byverify-certor in the browser. See Verification and Certificates. -
W3C Verifiable Credentials: an Ed25519-signed VC-JWT per completed session,
did:keybased. - 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.
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.
- 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.
| 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.
IronVise, by EctoSpace. Repository | Website | Releases | Report a vulnerability. The server is licensed under BUSL-1.1; the SDKs under Apache-2.0. Compliance mappings are aids, not legal advice or certification.
Get going
Understand
Use
Operate
Project