FAQ and Troubleshooting

FAQ and Troubleshooting

FAQ

Is IronVise a sandbox? No. It decides whether a command should run at all and keeps a signed record of what was proposed, allowed, refused and returned. A sandbox limits what a command can reach once it runs. Use both: IronVise in front, a sandbox underneath. IronVise also applies its own OS sandbox to the commands it runs; see Sandboxing.

Does it use a blockchain? No. The ledger is an append-only hash chain in SQLite or PostgreSQL. Optional OpenTimestamps stamps commit only a hash to Bitcoin through public calendars.

Recording or blocking: which integrations can stop an action? The Claude Code, Codex and Antigravity hooks, the MCP proxy, and the agent loop (ironvise audit) can stop an action before it runs. SDK verify_intent / verifyIntent answers before the action, but your code must honour the verdict. The OpenAI-compatible proxy, the OpenShell import and plain SDK event appends do not block. See Agent Integrations.

SQLite or PostgreSQL? SQLite for one machine, CI and the desktop app. PostgreSQL for several servers sharing one ledger and for the preview commands orchestrate, diff-audit and red-team.

Do I need a model to try it? No. make demo-hook and the browser verifier need no model and no database server.

Is it free? The server is BUSL-1.1: free for non-production use; production needs a commercial licence. Verification is permitted for any purpose. The SDKs are Apache-2.0. The licence converts to Apache-2.0 on the Change Date in LICENSE.

Has it been audited? No. It is a prototype and has not had an independent security audit. Known limits are in the threat model.

Where did prove-audit go? SP1 proving was withdrawn in 0.8 because of an upstream security advisory. Export an .elc certificate instead.

Why do some names still say EctoLedger? IronVise was called EctoLedger. Environment variables, the .ectoledger/ data directory, ectoledger.db, key files and webhook headers keep their names so existing installations keep working. See Migrating from EctoLedger.

Troubleshooting

Startup and database

Symptom	Fix
A command prints three database options and exits	DATABASE_URL has no default. Set it (sqlite://ledger.db is simplest), or set ECTO_DEV_MODE=true for the embedded development PostgreSQL.
Embedded PostgreSQL: port 5432 already in use	IronVise does not kill the process holding the port. Point DATABASE_URL at your existing server, switch to SQLite, or stop the other process.
Startup fails because the guard model is missing	GUARD_REQUIRED defaults to true for the CLI. Set GUARD_LLM_BACKEND and GUARD_LLM_MODEL. For development only, set GUARD_REQUIRED=false.
Guard is required although .env says GUARD_REQUIRED=false	Most restrictive wins: the desktop settings.json may require it. The startup log names the source.
WARN INSECURE DEMO MODE at startup	Demo settings are active (guard off, dev mode on, or bound to all interfaces). Fine on your own machine; see Configuration for real use.
A hosted provider refuses to start	Azure OpenAI, LocalAI and openai-compatible need OPENAI_BASE_URL; Azure OpenAI and xAI need OPENAI_MODEL. Each hosted preset reads its own key variable, such as GEMINI_API_KEY.
Local OpenAI-compatible server not reached	Set OPENAI_BASE_URL to the URL your server prints. The trailing /v1 is optional.
Model calls time out with a large local model	Raise ECTO_LLM_TIMEOUT_SECS (default 300).

Installing

Symptom	Fix
Linux binary fails with a glibc error	Release builds need glibc 2.35 or newer (Ubuntu 22.04, Debian 12 or later). On older systems, build from source or use Docker.
Windows: ironvise is not recognised	The .msi and .exe install the desktop app only and do not add ironvise to PATH. The CLI is in ironvise-x86_64-pc-windows-msvc.zip.
Desktop app asks for keychain access on macOS	Expected once after installing a new build. Allow it, or enter the key again.

Running commands

Symptom	Fix
Every action is aborted with a sandbox error	Fail-closed by design. On Linux, check the kernel supports Landlock (5.13 or newer, enabled). Use ECTO_SANDBOX_PERMISSIVE=true only for development.
git fails under the macOS sandbox	/usr/bin/git is an Xcode shim the Seatbelt profile cannot run. Install Homebrew git (/opt/homebrew/bin).
ls .. is refused on macOS	By design: parent folders of the workspace can be stat'ed, not listed.
Firecracker tier produces no output and the action aborts	The root filesystem does not implement the IronVise guest protocol. Run scripts/provision-firecracker.sh --rootfs busybox, or use the Docker tier. See Sandboxing.
orchestrate, diff-audit or red-team fail on SQLite	These need PostgreSQL.
The session stops after a few refusals	AGENT_GUARD_DENIAL_LIMIT (default 3) consecutive guard denials abort the session. A guard error counts as a denial.
Hook calls fail	Check ECTOLEDGER_TOKEN has the agent or admin role (not auditor) and ECTOLEDGER_URL reaches the server.

Verifying

Symptom	Fix
Certificate passes but is reported "internally consistent", not valid	It is unsigned. Use --strict or --expected-key to require a signature. Run ironvise issuer-key init so exports are countersigned.
--require-anchor fails on a fresh certificate	A new OpenTimestamps stamp is only a calendar's promise. Export it with --export-ots, run ots upgrade once a block has confirmed it, then verify with --ots.
verify-ledger reports failures after upgrading from EctoLedger	0.8 verification is stricter. Keep the database and report what it prints; do not delete data.
report exits 1	Expected when any finding is high or critical, so it can gate CI.

Still stuck? Security problems go to Security and Reporting. For everything else, check the docs index.