Quickstart

Quickstart

Four short paths, from "nothing installed" to "a signed certificate of my first audit". Commands use cargo run -p ectoledger -- so they work from a clone; with an installed binary, write ironvise instead.

1. Verify a certificate first (no setup, no trust needed)

The fastest useful thing to do is check a certificate IronVise produced, and then fail to forge one. This needs Rust and nothing else: no Docker, no database, no model, no network.

git clone https://github.com/EctoSpace/IronVise.git IronVise
cd IronVise
cargo build --release --bin verify-cert

./target/release/verify-cert examples/verified-session/session.elc
#   CERTIFICATE VALID     exit 0

./target/release/verify-cert examples/verified-session/session-tampered.elc
#   CERTIFICATE INVALID   exit 1   (one hex character was changed)

No build at all: the browser verifier runs the same checks. Verification is explicitly allowed for any purpose under the licence. examples/verified-session/ explains what is in the certificate and which tampering attempts are worth trying.

2. Watch it refuse a command

make demo-hook

A Claude Code PreToolUse call for rm -rf / is denied before it runs, the refusal lands in the hash chain, and verify-session passes. Then one field of that record is rewritten in the database and verify-session fails. No PostgreSQL and no model are needed, and the script asserts every step.

Want to try breaking it instead? examples/challenge/ ships five ledgers, two genuine, and asks you to say which.

3. Open the dashboard

Command	What it does
make start	The desktop app, with its backend in-process
make demo	The Observer dashboard over a local SQLite ledger in demo mode, no model or Docker needed
.\ironvise-win.ps1 -demo	The Windows demo: embedded PostgreSQL on port 5433 and a small local model

make demo is exactly:

ECTO_DEMO_MODE=1 DATABASE_URL=sqlite://ectoledger-demo.db \
  cargo run --release -p ectoledger -- serve

The server prints an access token at startup. Open the printed URL, which looks like http://127.0.0.1:3000?token=<token>. Demo mode turns the semantic guard off; see Configuration before using it for real work.

Docker demo stack

git clone https://github.com/EctoSpace/IronVise.git IronVise && cd IronVise
docker compose -f docker-compose.demo.yml up
# open http://localhost:3000

This starts IronVise, PostgreSQL 17 and Ollama with a small model, with no Rust or Node needed. It is insecure on purpose (guard off, dev mode on, listening on all interfaces), so keep it on your own machine. Stop it with docker compose -f docker-compose.demo.yml down, or add -v to delete its data too.

4. Your first audit

Pick a ledger

DATABASE_URL has no default. Set it, or set ECTO_DEV_MODE=true to use an embedded PostgreSQL with development credentials.

Backend	Setting
SQLite (simplest)	DATABASE_URL=sqlite://ledger.db
PostgreSQL	DATABASE_URL=postgres://user:pass@host:5432/db

Pick a model

Copy .env.example to .env (make setup does this) and choose a provider, for example:

LLM_PROVIDER=ollama
OLLAMA_MODEL=mistral

Every supported provider is listed in Configuration.

Name the guard model

The semantic guard is on by default and reviews every step with a second model. Name it, and build the guard-worker program once:

export GUARD_LLM_BACKEND=ollama
export GUARD_LLM_MODEL=llama3.2      # ideally a different model from the agent's
cargo build -p ectoledger            # builds ironvise, guard-worker and verify-cert

For a first local try only, GUARD_REQUIRED=false runs without it.

Run, export, verify

DATABASE_URL=sqlite://ledger.db cargo run -p ectoledger -- audit "Read server_config.txt"
# prints: Session <id> started.

DATABASE_URL=sqlite://ledger.db cargo run -p ectoledger -- report <session_id> \
  --format certificate --output audit.elc

./target/release/verify-cert audit.elc

• The certificate is signed when audit saved the session's signing key, which it does when you give it a password at its prompt (or with --key-password-fd). report then asks for that password. Without one it is written unsigned, and the verifier reports it as internally consistent but unsigned.
• report submits the session's chain-tip hash, and nothing else, to a public OpenTimestamps calendar. Pass --no-ots to stay offline.
• For certificates that are always signed, create an installation issuer key once with ironvise issuer-key init. See Verification and Certificates.

Apply a compliance policy

cargo run -p ectoledger -- audit "Audit access controls" \
  --policy crates/host/policies/soc2-audit.toml

Built-in packs: soc2-audit.toml, pci-dss-audit.toml, owasp-top10.toml. iso42001.toml maps controls to ledger evidence and cannot govern a run.

Next steps

• Connect your own agent: Agent Integrations
• Call it from code: SDKs
• Harden it: Configuration