Configuration

Configuration

IronVise is configured with environment variables, optionally from a .env file. Start from .env.example in the repository. The complete list, including rate limits, enclave settings and GUI-only variables, is docs/guides/configuration.md.

Running securely

The demo paths are insecure by design. For anything real, these three matter most:

Variable	Demo value	Hardened value	Why
GUARD_REQUIRED	false	true (the CLI default)	When false the semantic guard never runs. When true, GUARD_LLM_BACKEND and GUARD_LLM_MODEL are required.
ECTO_DEV_MODE	true	unset or false	When true, an unset DATABASE_URL falls back to well-known development credentials.
ECTO_BIND_HOST	0.0.0.0	127.0.0.1 (the default)	Binding to all interfaces makes the bearer token the only protection.

export GUARD_REQUIRED=true
export GUARD_LLM_BACKEND=ollama
export GUARD_LLM_MODEL="your-review-model"     # a different model from the agent's
unset  ECTO_DEV_MODE
export ECTO_BIND_HOST=127.0.0.1
export DATABASE_URL='postgres://<user>:<pass>@<host>/<db>'
export OBSERVER_TOKEN="$(openssl rand -hex 32)"
ironvise serve

Also worth setting:

• Leave ECTO_SANDBOX_PERMISSIVE unset. When true, actions run even when the sandbox fails.
• Configure an isolation tier: ECTO_DOCKER_IMAGE (any platform) or ECTO_FC_BINARY (Linux with KVM). See Sandboxing.
• Leave ECTO_CORS_ALLOWED_ORIGINS empty unless a browser client on another origin needs access.
• Set AGENT_ALLOWED_DOMAINS (or the Tripwire screen) to restrict http_get.
• Point WEBHOOK_URL at your SIEM and set WEBHOOK_HMAC_SECRET.

When the server runs with demo-grade settings it logs WARN INSECURE DEMO MODE at startup. Details: docs/getting-started/running-securely.md.

Core settings

Variable	Default	Purpose
DATABASE_URL	none (required)	sqlite://ledger.db or postgres://.... An unreachable local PostgreSQL URL starts an embedded PostgreSQL.
ECTO_DATA_DIR	.ectoledger	Data directory. Encrypted session keys live in its keys/ folder, the issuer key in issuer.key.
ECTO_KEY_PASSWORD	none	Session key password, to skip the prompt
OBSERVER_TOKEN	generated and printed	Bearer token for the dashboard and API
ECTO_BIND_HOST / ECTO_BIND_PORT	127.0.0.1 / 3000	Where the Observer listens
ECTO_TRUSTED_PROXIES	empty	Reverse proxies allowed to set the client IP for rate limiting
AGENT_MAX_STEPS	20	Steps per session
AGENT_GUARD_DENIAL_LIMIT	3	Consecutive guard denials before the session aborts
AGENT_LLM_ERROR_LIMIT	5	Consecutive model errors before the session aborts
AGENT_KEY_ROTATION_STEPS	disabled	Steps between signing-key rotations
AGENT_ALLOWED_PROGRAMS	none	Extra programs for the executor allowlist
SCANNER_SENSITIVITY	medium	Output scanner: low, medium or high
ECTO_LLM_TIMEOUT_SECS	300	Per-request timeout for every model call
ECTO_SANDBOX_PERMISSIVE	false	Leave false: sandbox failures abort the action

Model providers

LLM_PROVIDER selects the agent's model provider (default ollama). LLM_BACKEND still works as a deprecated alias.

Kind	Presets	Settings
Ollama	ollama	OLLAMA_BASE_URL (default http://127.0.0.1:11434), OLLAMA_MODEL (default mistral)
Local OpenAI-compatible servers	lmstudio, llamacpp, vllm, mlx, localai, openai-compatible	OPENAI_BASE_URL (with or without /v1), OPENAI_MODEL
OpenAI	openai	OPENAI_API_KEY, optional OPENAI_MODEL
Anthropic	anthropic	ANTHROPIC_API_KEY, optional ANTHROPIC_MODEL
Other hosted APIs	gemini, azure-openai, mistral, groq, openrouter, deepseek, xai	Each reads its own key: GEMINI_API_KEY, AZURE_OPENAI_API_KEY, MISTRAL_API_KEY, GROQ_API_KEY, OPENROUTER_API_KEY, DEEPSEEK_API_KEY, XAI_API_KEY

Azure OpenAI and xAI need a model set explicitly; Azure, LocalAI and openai-compatible need a base URL. The provider table with default addresses and models is in the configuration reference.

Semantic guard

Variable	Default	Purpose
GUARD_REQUIRED	true	Require the guard. Startup fails if its model is not configured.
GUARD_LLM_BACKEND	none	Guard provider, same preset names as LLM_PROVIDER
GUARD_LLM_MODEL	none	Guard model. Prefer a different model from the agent's.
ECTO_GUARD_WORKER	guard-worker beside the binary	Path of the guard worker program

The desktop app's settings file

The desktop app saves its Settings screen to settings.json in its data folder (.ectoledger/settings.json, or $ECTO_DATA_DIR/settings.json). For eight keys that file wins over the environment: database_url, llm_backend, llm_provider, ollama_base_url, ollama_model, openai_base_url, guard_llm_backend, guard_llm_model.

GUARD_REQUIRED is the exception: most restrictive wins. If either the environment or the settings file requires the guard, it is required. The server logs the effective value and its source at startup, for example INFO guard_required = true (from: environment), and warns when the two disagree.

Policies

A policy is a TOML file saying what an agent may do. Start from audit_policy.example.toml; all keys are top level.

Key	Purpose
name, goal	Describe the audit
max_steps	Step budget
[[allowed_actions]], [[forbidden_actions]]	Restrict actions, paths, commands, domains
[[command_rules]]	Regex allow or deny rules for commands
[[observation_rules]]	Redact or flag patterns in tool output
[[approval_gates]]	Require human sign-off before high-risk steps
[[plugins]]	Third-party security tools the agent may run
[[required_checks]]	Checks you expect the audit to cover (stored with the policy, not enforced in 0.8)
[findings]	Evidence requirements per severity

Where	How to apply a policy
CLI	ironvise audit "<goal>" --policy path/to/policy.toml
Observer (hooks, MCP proxy, SDK verify-intent, REST runs)	ECTO_POLICY_PATH=/path/to/policy.toml before ironvise serve
Desktop app	Policy screen, Use for new runs

Built-in packs live in crates/host/policies/: soc2-audit.toml, pci-dss-audit.toml, owasp-top10.toml, and iso42001.toml (a controls mapping that cannot govern a run).

Tripwire

Tripwire rules are saved in tripwire.json in the data directory, edited on the desktop app's Tripwire screen or with PUT /api/tripwire: allowed paths, allowed HTTP domains, banned command patterns, minimum justification length, HTTPS requirement, and allowed_mcp_tools. AGENT_ALLOWED_DOMAINS only seeds the domain list the first time no saved configuration exists.

Webhooks and SIEM

Variable	Default	Purpose
WEBHOOK_URL	disabled	Where security events are posted
WEBHOOK_BEARER_TOKEN	none	Bearer header on every post
WEBHOOK_HMAC_SECRET	disabled	Sign each delivery for its receiver. Give each receiver its key from ironvise webhook-key --url <url>.
SIEM_FORMAT	json	json, cef or leef
WEBHOOK_INCLUDE_GUARD / WEBHOOK_INCLUDE_TRIPWIRE	true	Include guard denials / tripwire rejections
WEBHOOK_RATE_LIMIT_PER_SECOND	10	Deliveries per second per URL
ECTO_VC_AUDIENCE	unset	Bind session Verifiable Credentials to one audience

Webhooks can also be managed in the desktop app (Access screen) and through the API.

Isolation tiers

Variable	Default	Purpose
ECTO_DOCKER_IMAGE	alpine:3.19	Image for the Docker tier
ECTO_DOCKER_RUNTIME	auto	auto, docker or podman
ECTO_DOCKER_MEMORY / ECTO_DOCKER_CPUS / ECTO_DOCKER_TIMEOUT	256m / 1 / 30	Container limits
ECTO_FC_BINARY	/usr/local/bin/firecracker	Firecracker binary; setting it opts in
ECTO_FC_KERNEL / ECTO_FC_ROOTFS	/opt/ectoledger/vmlinux / /opt/ectoledger/rootfs.ext4	Guest kernel and root filesystem
ECTO_FC_VCPUS / ECTO_FC_MEM_MIB / ECTO_FC_TIMEOUT_SECS	1 / 128 / 30	microVM size and timeout

Build features

Feature	Adds
sandbox (default)	Landlock and seccomp on Linux
sandbox-firecracker	The Firecracker microVM tier (Linux with KVM)
sqlcipher	At-rest encryption for SQLite; set ECTOLEDGER_SQLCIPHER_KEY (at least 16 characters)
hash-blake3	BLAKE3 for new events' chain hashes
vc-ecdsa	P-256 Verifiable Credential signing
enclave, enclave-remote, sandbox-apple-enclave	Guard enclave IPC, AWS Nitro remote attestation, Apple Hypervisor guard

Example: cargo build --release -p ectoledger --features sandbox-firecracker.