Docs
Reference
The complete surface of the open build: Cargo features, the CLI at a glance, every environment variable, the HTTP API, and API key scopes. Mirrors the repository; GitHub stays the authoritative copy.
Cargo features (iaga-sentinel-core)
| Feature | Default | Adds |
|---|---|---|
sqlite | on | SQLite backend for audit + receipts. |
postgres | off | Postgres backend. |
receipts | on | Ed25519-signed Merkle-chained receipts. |
dictum | on | Dictum policy parser + evaluator + iaga policy … |
reasoning | on | Reasoning plane scaffold + iaga reasoning info. |
ml | off | tract-onnx ML backend; opt-in, +~5 MB binary, +~2 min cold compile. |
kernel | on | Enforcement kernel + iaga run + iaga kernel status. |
linux-bpf | off | Linux eBPF/LSM scaffold + ringbuf API. The real Aya-rs loader lives in IAGA Sentinel Enterprise. |
cost-control | off | Local LLM spend metering, /v1/cost/*, iaga cost, session budgets, MCP response cache. The default build is byte-identical without it. |
plugin-attestation | off | Offline Sigstore bundle + CycloneDX SBOM verify + iaga plugins verify. |
dictum-wasm | off | Dictum to WASM codegen MVP + iaga policy compile. The Hindley-Milner type checker (iaga policy check) is always on, no feature needed. |
otel-receipts | off | Emit each signed receipt as an OpenTelemetry span on /v1/telemetry/spans and /v1/telemetry/export, with iaga.receipt.id, iaga.chain.head, iaga.policy.verdict, and iaga.is_authoritative. No new dependency. |
plugin-manifest-signing | off | Ed25519-signed plugin manifests verified at load against trusted keys, plus iaga plugins sign-manifest and verify-manifest. Orthogonal to plugin-attestation. |
default = ["demo", "sqlite", "receipts", "dictum", "reasoning", "kernel"]
The standalone verifier iaga-verify (crate iaga-sentinel-verify) is a separate, dependency-light binary and the artifact you hand an auditor. Build it reproducibly:
cargo build --release -p iaga-sentinel-verify --no-default-features --features verify-onlyCLI at a glance
| Command | What it does |
|---|---|
iaga serve [--seed-demo] [--port N] [--policy file.dictum] | Run the sidecar: API, dashboard, signer, audit store. |
iaga inspect <payload.json> | One-shot pipeline verdict from the CLI. |
iaga run --agent-id <id> -- <cmd> [args…] | Launch a child process under governance, with env scrubbing. |
iaga replay [--list] [<run_id>] [--verify-only] [--re-execute] [--export f.json] | Verify or replay signed receipt chains. |
iaga policy check/lint/test/compile <file.dictum> | Type-check, validate, dry-run, or compile Dictum. |
iaga gen-key --label <name> [--scope agent] | Mint an API key (admin by default). |
iaga audit [--limit N] [--format json] | Show the audit trail. |
iaga cost [summary|by-model|by-agent|by-tool|budget] | Spend views (requires cost-control). |
iaga proxy --agent-id <id> --command <cmd> [args…] | Transparent MCP governance proxy. |
iaga mcp-server | Expose governance tools over MCP stdio. |
iaga plugins list/validate/verify/sign-manifest/verify-manifest | WASM plugin lifecycle. |
iaga kernel status / iaga reasoning info | Honest posture reports. |
iaga import/export/migrate/validate | Policy config and database management. |
iaga-verify <chain.json> [--key <hex>] | Standalone offline receipt verification. |
Environment variables
| Variable | Effect |
|---|---|
IAGA_SENTINEL_OPEN_MODE | true disables auth (walkthroughs only). |
PORT | Listen port (default 4010); --port overrides. |
DATABASE_URL | postgres://… switches the backend (with --features postgres). |
IAGA_SENTINEL_SIGNER_KEY_PATH | BYOK: path to a 32-byte Ed25519 signer key file. |
IAGA_SENTINEL_RECEIPT_CAPTURE | 1 captures pipeline inputs for replay --re-execute. |
IAGA_SENTINEL_ENV_DENYLIST | TOML file extending the secret-scrub denylist for iaga run. |
IAGA_SENTINEL_ENV_DENYLIST_STRICT | 1 fails launches closed when the denylist TOML is unreadable or malformed (default: warn and use built-ins). |
IAGA_SENTINEL_PLUGIN_DIR | WASM plugin directory (default ./plugins). |
IAGA_SENTINEL_REASONING_MODELS | ONNX model paths for the ml feature. |
IAGA_SENTINEL_SESSION_BUDGET_USD | Per-session spend cap (with cost-control). |
IAGA_SENTINEL_PRICING_FILE | Override the built-in pricing table. |
IAGA_SENTINEL_LOG_LEVEL / _LOG_FORMAT | Tracing filter and text/json output. |
IAGA_SENTINEL_DEFAULT_MODE | Default governance mode for unmatched workspaces. |
IAGA_SENTINEL_NHI_MASTER_SEED | Deterministic seed for NHI identity keys. |
IAGA_SENTINEL_HOST | Interface the server binds to (default 0.0.0.0). |
IAGA_SENTINEL_CORS_ORIGINS | Comma-separated CORS allowlist (unset = permissive Any, the pre-1.5.2 behavior). |
IAGA_SENTINEL_AUTH_CACHE_TTL_MS | Verified-API-key cache TTL (default 60000; 0 disables and verifies every request). |
IAGA_SENTINEL_MAX_SESSIONS / _SESSION_TTL_MS | Session-graph store cap (default 10000) and TTL (default 30 min). |
IAGA_SENTINEL_BLOCK_COOLDOWN_MS / _MAX_BLOCK_COUNT | Blocked-session cooldown (default 60 s) and strikes before a permanent block (default 3). |
IAGA_SENTINEL_CLEANUP_INTERVAL_SECS / _CLEANUP_TTL_SECS | Background TTL-cleanup cadence (default 300) and age threshold (default 3600). |
IAGA_SENTINEL_COST_CACHE_TTL_MS / _COST_CACHE_MAX_ENTRIES | Response-cache TTL (default 5 min) and size cap (default 4096), with cost-control. |
HTTP surface
Everything below speaks the camelCase wire contract (agentId, toolName, actionType) and, outside open mode, requires Authorization: Bearer <key>.
| Endpoint | What it does |
|---|---|
POST /v1/inspect | Governance verdict for one action; the single endpoint everything integrates against. |
GET|POST /v1/auth/keys · DELETE /v1/auth/keys/{id} | API key management (admin scope). |
GET /v1/reviews · POST /v1/reviews/{id} | Review queue: list items, approve or reject. |
GET /v1/sandbox/pending | Sandboxed dry-runs with impact analysis, awaiting an operator. |
GET /v1/receipts · GET /v1/receipts/{run_id} | List runs; read one run's signed receipt chain. |
GET /v1/cost/summary · /by-model · /by-agent · /by-tool · /over-time?bucket= | Spend aggregation (cost-control). |
POST /v1/webhooks · GET /v1/webhooks/dlq | Register webhook endpoints; inspect and retry the dead-letter queue. |
GET /v1/events/stream | Server-sent-events live feed of every verdict, review creation, and resolution. |
GET /v1/policy/overlay | Loaded Dictum bundle hash and policy count. |
POST /v1/plugins/reload | Reload the WASM plugin registry (admin scope). |
GET /v1/telemetry/spans · /v1/telemetry/export | Signed receipts as OpenTelemetry spans (otel-receipts). |
POST /v1/risk/feedback · POST /v1/risk/weights/reset | Adaptive risk weights: feedback shifts them; reset restores defaults (admin). |
GET /health | Liveness; returns 200 within about 10 seconds of first Docker boot. |
API key scopes
API keys carry a scope since 1.5.2: admin (default — full access, identical to pre-1.5.2 keys) or agent (iaga gen-key --scope agent), which can drive the governance surface but not manage keys, webhooks, rate-limit config, threat intel, or plugin reloads.
Note that the adaptive-risk weights are process-global across all agents: feedback posted to /v1/risk/feedback shifts them for every agent on the instance, and POST /v1/risk/weights/reset (admin) restores the defaults.
Where to go next
- Tutorial: every surface above, walked end to end.
- Architecture: the crates behind these features.
- Architectural decision records: docs/adr on GitHub — 22 ADRs (0001 to 0023, no 0009), listed on the Architecture page.
- Project documents on GitHub: SECURITY.md (vulnerability reporting), DATA_HANDLING.md (data handling and privacy), CONTRIBUTING.md, and CHANGELOG.md (release notes).