Common questions & troubleshooting

On this device only. LLM keys and OAuth tokens sit in the AES-GCM vault (device password required). Chats and the audit ledger live in browser storage. Prompts, keys, and receipts stay on-device — policy evaluation, receipt signing, and key custody never require our cloud. What does reach our servers is your signed entitlement artifact refresh (and, on Team plans, seat identity and a signed policy pointer). Set a password in Settings → Device to encrypt at rest and enable auto-lock.

Settings → Storage → Reset app data. Clears the vault, connectors, agents, and audit ledger on this device only. Other devices in your workspace are untouched.

Settings → Device → Export encrypted backup. The archive holds the vault, connector configs, agents, policy, and audit ledger — AES-GCM encrypted with your device password. Install Aarmos on the new device, Import, enter your password.

No. The local proxy uses hostname-only CONNECT tunneling — it sees which domain you called, not the payload. Rich payload receipts (prompt, tool arguments, model response) come from our client adapters (@aarmos/adapter-mcp, adapter-openapi, adapter-deeplink, and the LLM adapters), which capture data before encryption. Raw HTTPS calls that bypass the adapters produce hostname-level receipts only. No root CA is installed by default. See ADR-0001 for the full decision.

Aarmos defines a public conformance model so implementations can be validated consistently. See the [Conformance Specification](/docs/conformance/aarm) for per-requirement evidence, honest gaps, and how to reproduce the claims yourself. This is a self-attestation; no third-party assessor has reviewed us yet.

OpenAI, Anthropic, Google, Groq, OpenRouter, and local Ollama — plus any OpenAI-compatible endpoint (Azure, Mistral, Together, LM Studio, vLLM) via a custom base URL. Add keys under Settings → AI providers; the first healthy one handles each turn, with automatic failover.

Aarmos is protocol-agnostic. One consent, policy, and audit layer sits above MCP (hosted or local), OpenAPI 3, A2A (agent-to-agent, device-local tokens), Bearer APIs, SQL connectors, deep-links, and custom REST endpoints. Every governed call — regardless of protocol — routes through the same gate and lands in the same signed receipt.

Bring Your Own Storage. A2A tokens, connector OAuth refresh tokens, and API keys are stored in the on-device AES-GCM vault by default. Point Settings → Storage at an external secret backend (system keychain, HashiCorp Vault, 1Password CLI, AWS/GCP Secrets Manager) and Aarmos will read/write there instead — the gate and receipt path are unchanged.

Three options: (1) Settings → Custom REST APIs to wire any HTTP endpoint (bearer, API-key, basic, OAuth); (2) Settings → Discover tools by URL to probe for /.well-known/mcp.json or an OpenAPI spec; (3) Settings → MCP servers to attach any hosted or self-run MCP catalog.

Open Registry and tap Install on a starter — Web researcher, PR review helper, API endpoint tester, Prod-DB explainer, Log grepper, and more. Each ships pre-scoped with connectors and a system prompt wired in. Edit, uninstall, or clone anytime.

A gate decision is per tool call: the policy gate returns allow / ask / deny in microseconds, and that outcome is recorded on the receipt step. A Decision (capital D) is the business action above it — "issue this refund", "deploy this release". You name it, declare the inputs it depends on, and bind the participants that must weigh in; Aarmos composes their answers into one verdict and records it as evidence. One Decision usually spans several gate decisions. See /docs/concepts/decision-governance.

A participant is a party whose answer the decision depends on — a policy, an external oracle that owns a business invariant, or a human approver. Participants are always declared, never inferred: if a required participant did not answer, the runtime does not guess and does not silently proceed. Each participant's answer carries validity along four dimensions (freshness, expiry, revocation, and the execution window it is valid inside), and all of it lands on the receipt.

No. A decision identifier is a permanent governance identity — renaming it would silently orphan every past receipt that cites it. Schema evolution can add fields and bump the version, but the identifier stays fixed for the life of the decision. Retire the old decision and declare a new one instead.

Every in-flight call aborts and every new call is denied at the gate — including sub-agents and scripted replays. The DENY is recorded as a first-class decision step in the receipt (actor, timestamp, policy-bundle fingerprint) so an auditor can prove device state. Persists across reloads until you (or a fresh signed bundle) resume.

Press Esc three times in under a second — the global kill switch engages and every in-flight and new call is denied. A 10-second Undo toast appears in case it was accidental. Ignored while typing in an input, textarea, or contenteditable field. Also available from Admin.

Yes. Aarmos ships ASP — a readable YAML policy DSL. Version rules in git, lint and unit-test them with `aarmos policy lint` and `aarmos policy test`, then compile signed bundles with break-glass overrides. Budget guardrails, delegation caps, scoped panic, and per-tool consent all compile down to the same gate. Spec at /docs/asp-spec.

Policy bundles expire. Rather than flip an offline device to hard-DENY the moment the clock crosses the boundary, a bundle invalid only because it expired in the last 7 days keeps enforcing while the posture card flags it — refresh proactively. Signature failures and tampered bytes still fail closed immediately; no grace for integrity issues.

The gateway caps delegation depth at 4 and intersects allowlists at every hand-off — a callee can never invoke a tool outside its caller's allowlist. Both bounds are hard-denies, hash-chained in the receipt alongside the tool call they replaced.

Tool arguments are size- and shape-checked before the consent prompt. Strings that look like credentials (bearer tokens, sk-* keys, JWTs) are redacted from prompts, UI, logs, and ledger entries. The same scrubber runs on knowledge-base output. Reduces accidental leakage; not a substitute for keeping secrets out of prompts.

Yes. Sliding-window call caps (per-minute and per-day) on every tool and agent, plus a daily USD spend ceiling evaluated on LLM turns. Warning at 70% of budget; 100% engages the kill switch automatically. All trips are receipted. Tune defaults in Settings.

Every governed tool call resolves to one of eight actions: read, write, delete, execute, communicate, delegate, transact, control. Scopes are set per-connector, per-agent, and per-workspace as allow/ask/block. Write implies read; delete implies write; higher verbs never silently gain lower ones without an explicit grant. Full vocabulary at /docs/actions.

Nested parallel tree. A parent agent can delegate sequentially (step 1 → step 2) or fan out to N children in parallel, and children can do the same up to a hard depth cap of 4. There is no mesh — no peer-to-peer discovery, no back-channels. Every hand-off intersects allowlists (a callee is capped by its caller), inherits budget, and hash-chains into the same receipt. Deny at any node aborts that branch, not the whole tree.

Optional decoy strings (fake API keys, tagged file paths, honeytoken URLs) that Aarmos injects into the vault and knowledge base. If one appears in a prompt, tool argument, or egress body, the gate emits a critical AVAR entry and — if configured — engages the kill switch. Turn them on in Settings → Safety → Tripwires.

`aarmos activity` prints a human-readable log of recent governed actions straight from the local receipt directory (.aarmos/avar) — no web app, no network. Narrow it with `--since 24h`, `--status denied`, `--op <substring>`, or `--agent <substring>`; `--runs` gives one line per run, `-f` tails live activity, `--json` is machine-readable. It's strictly read-only; `aarmos verify` is still the step that checks signatures and the hash chain.

A Governed Action names one class of consequence — model calls, external communications — and binds it to the facts a decision needs, every path where that consequence can occur (each one either enforced or a named bypass), and a fixed evidence budget. It changes nothing about receipts: no new fields, and `aarmos verify` plus the open `avar` verifier read the same records as before. Enabling is shadow-first — enforcing is refused until a shadow review has actually been recorded, and promotion is refused if the definition changed after that review. Browse the installed definitions at /docs/governed-actions, or run `aarmos ga list`.

AVAR (Aarmos Verifiable Action Record) is an open, hash-chained receipt format. Every agent turn produces one signed, canonicalised record — inputs, decisions, tool calls, outcomes. The spec is CC-BY-4.0, and the open reference verifier @avar-standard/verify is Apache-2.0-licensed with zero dependencies. That means your proof of governance outlives Aarmos the company: any auditor can re-verify a receipt years from now without our servers, license servers, or continued existence.

Two paths, bit-identical results. In the browser: drop an .avar.zip on /trust/verify — the page runs the verifier client-side and reports signature checks, chain reconciliation, and any tampering. From the terminal: `aarmos verify bundle.zip` (or `npx @avar-standard/verify`). Zero network. Works with Aarmos uninstalled and the daemon stopped.

Given an .aarmos bundle (receipts + policy + tool catalog hashes), Aarmos re-runs every gate decision offline and confirms the same allow/deny/verdict at every step. Same inputs → same decisions, byte-for-byte. Drop the bundle on /trust/verify or run `aarmos replay <bundle>`; a divergence report flags any receipt that wouldn't reproduce under the pinned policy.

Audit → Export incident bundle produces a signed .aarmos archive: the receipt window you selected, the policy bundle in force at the time, the tool catalog fingerprints, kill-switch state transitions, and pre-flight/attestation receipts. Hand it to an auditor, an incident responder, or your future self — they can `aarmos verify` and `aarmos replay` it without any Aarmos install talking to our servers.

v2 adds an attestation block to every receipt: the CLI version, policy-bundle hash, tool-catalog hash, and platform fingerprint, all covered by the same Ed25519 signature. Verifiers can reject receipts written by an untrusted binary or against an unknown policy without loading any auxiliary manifest. v1 receipts still verify; v2 is emitted by current CLI builds (design partners receive the CLI directly — public npm distribution resumes at 1.0.0).

Aarmos ships the mechanisms these frameworks ask for — signed policy bundles, tamper-evident audit trails, delegation caps, kill switch, credential redaction — mapped to the relevant controls in our compliance-mapping docs. That's a mechanism claim, not a certification claim: Aarmos is not itself SOC 2 / ISO 42001 certified, and using it does not make your organisation certified. It gives you and your auditor a defensible evidence base.

We intercept at the Connector boundary — every fetch from MCP, OpenAPI, A2A, and deep-link Connectors is stamped with the initiating tool, protocol, and an AVAR receipt, and shows up in the Egress ledger at /posture. That's the honest scope: Connector fetch egress. XHR, WebSocket, SSE, sendBeacon, the CLI/Bridge daemon, and anything a subprocess opens directly against the OS are not observed here. Roughly 30–55% of the total agentic surface today; daemon instrumentation and OS-level detection-only tripwires are on the egress roadmap.

No. We explicitly reject TLS-MITM — it breaks certificate pinning, weakens the user's trust store, and is a moat we don't want. Enforcement lives at the Connector boundary before encryption, so we can allow/deny by FQDN, tool, and receipt without ever seeing ciphertext. Payload-level content rules (classification checks, size caps) run pre-encryption on the structured arguments, not on the wire.

Not as a blocker. The wall lives in the Connector; the kernel layer, if and when it lands, is a detection-only tripwire that flags calls which bypassed the gate — never a default packet dropper. That decision keeps zero-friction deployment intact and preserves user trust.

No — the gate runs in the hot path of every tool call, and tail latency is what we optimise for. Steady-state overhead: p99 ≈ 1µs, p999 < 15µs (warm cache, no rule changes). Under continuous policy updates: p99 ≈ 50µs, p999 well under 100µs. A CI benchmark tracks regressions on every push against a p99 ≤ 500µs / p999 ≤ 5ms budget; the harness is at src/lib/policy/__bench__/gate.bench.ts. Invisible next to a single LLM token (10–100ms).

Per-tool JSON-Schema files under `contracts/` that declare the expected argument and output shape for every tool an agent calls. The runtime gate validates each call against the matching contract; verdicts land on the AVAR step. Policy decides *whether* a call is allowed (the 8×8 matrix); contracts decide whether its *shape* is well-formed. Both fire on the same call. See /docs/contracts.

Three commands: `aarmos contracts init --from <receipt>` scaffolds from a real run; `aarmos contracts watch` drops proposals for new tools into `.aarmos/contracts/proposals/`; `aarmos contracts accept <tool>` promotes a proposal into `contracts/`. Lint with `aarmos contracts lint`, compare a run against them with `aarmos contracts diff --from <receipt>`. No auto-repair — every promotion is explicit.

Canonical sha256 over the promoted contract set (sorted keys, so two machines with the same contracts always compute the same digest). Receipts embed this fingerprint at runtime. Anyone with the receipt and the shipped contracts can re-compute it offline with the AVAR verifier — if the digest doesn't match, verification refuses. That's how you prove no contract drift between authoring and execution.

Each contract sets `mode: "warn"` or `"strict"`. In warn, the gate lets the call proceed and records a drift note on the receipt. In strict, the gate refuses the call before the tool sees it. Modes are per-contract so you can tighten one tool at a time — typical rollout is warn until diff is clean across a few runs, then flip to strict.

Optional. Run `aarmos dev` in a project folder to pair Aarmos with a localhost WebSocket (127.0.0.1:7423) so the agent can read files, watch git, and — with approval — propose edits and shell commands. Dry-run by default: writes and commands land in a review drawer with full diffs first. Workspace-jailed, origin-checked, per-session token. Aarmos works standalone without it.

Yes — `aarmos run --playbook <path>` runs a JSON playbook as a headless loop. Only steps marked `autoApply: true` execute; everything else is dry-run and logged as `needs-approval` for you to review in the PWA. Destructive verbs (kubectl delete/drain, git push --force, Jira DELETE /issue/{id}) force approval unless the step sets `acknowledgeDestructive: true` AND the playbook is Ed25519-signed with `--enforce-signatures --trusted-pubkey`. Rolling `--max-per-hour` ceiling, `--kill-switch` file, and a hash-chained JSONL receipt per action. `aarmos simulate` runs the same pipeline with zero side effects so you can see verdicts before scheduling.

`aarmos playbook keygen` writes an Ed25519 keypair; `aarmos playbook sign` seals a playbook so tampering invalidates the signature. `aarmos run --enforce-signatures` refuses unsigned playbooks; `--trusted-pubkey` narrows accepted signers. Packs (`aarmos pack install/list/verify`) are signed JSON bundles of playbooks + scope allowlists — installing a pack widens the shell/http/mcp allowlists for that workspace only. Same primitive as the on-device receipt signer.

A single JSON bundle: hash-chained receipts within a time window, the playbook hash, the policy config hash, installed pack hashes, and a sequential `rootHash`. Optionally Ed25519-signed. `aarmos verify` re-computes `rootHash` and checks the signature against embedded bytes — pure function, no network. It's evidence that the receipts in the file weren't edited after the fact; whether it satisfies a specific audit or regulation is up to your auditor.

Audit → Export downloads a signed bundle with the settings ledger and trace history, hash-chained so tampering is detectable. Turn on auto-export to write a local bundle after batches of settings changes. Home and Dashboard nudge you if it's been over a week.

A single command that runs before you commit or deploy: matrix lint (rules M1/D1), workspace sanity checks (branch, dirty tree, port usage), and a secret scan across staged files (respects .gitignore). Emits a signed `preflight.pass` or `preflight.fail` AVAR receipt into `.aarmos/preflight/` pinned by SHA-256, so the outcome is part of the same audit chain as runtime. Typically <20ms on a normal repo.

`aarmos preflight install-hook` prints a ready-to-paste pre-commit snippet — by design it does not overwrite `.git/hooks/` unless you pass `--force`. Add the snippet, or run `aarmos preflight --strict` in CI to fail the build on any lint, secret, or sanity finding. Same receipt shape either way.

Static checks on your access matrix and policy bundle: attenuation (rule D1 — no child scope exceeds a parent), tenant invariant (rule T1), obligation ordering (O3), and metering atomicity (M1). Non-zero exit on any violation; JSON output for CI. Runs offline against the files, no daemon required.

A signed, single-use JSON invite you hand to a teammate or sub-agent that grants only a named subset of tools + verbs, with an expiry and a call ceiling. Redeeming it installs the scope on the target device — nothing else changes. Revoke by rotating the workspace signing key or letting the expiry lapse. Used for onboarding, incident-response temporary grants, and CI service accounts.

`aarmos record` captures a live agent session (calls, verdicts, arguments) into a local trace. `aarmos synth <trace>` produces a candidate playbook + policy scope derived only from what was observed — never a wider grant. `aarmos promote` seals it with your signing key. The synth output is marked with rule S1 (Synth Provenance) so reviewers can see it came from replay, not hand-authoring.

Evaluation (free, one operator, one device): the full local runtime — kill switch, per-tool allow/ask/block scopes, workspaces, signed connector allowlist, encrypted vault + backup, unlimited agents, custom REST APIs, every protocol connector, the signed AVAR audit ledger with JSONL export and regex redaction, and the content-rule engine (classification, masking, deny-by-pattern). Team adds signed policy push, central audit relay, SIEM export (Splunk/Datadog/webhook), and fleet posture. Enterprise adds SSO/SAML, MDM deploy, white-label, and a co-signed roadmap. See Pricing.

Yes — a 14-day money-back guarantee on your first paid purchase, no questions asked. After that you can cancel anytime from Settings → Billing; you keep your plan through the end of the current billing period. Full policy at /refunds.

Four sink types are supported: Splunk HEC, Datadog Logs, a signed webhook, and syslog. Team can configure one destination (the cap is enforced server-side); Enterprise is unlimited and adds routing. Configure in Settings → Fleet → Audit relay; each AVAR receipt is mirrored (signature intact) to the sink in near-real time. On Evaluation there is no relay — read the same events locally with `aarmos activity --follow`. Event schema and starter Splunk/Datadog detections at /docs/integrations/siem.

Each seat's device generates an Ed25519 keypair on first launch and registers its public key with the workspace. Policy bundles, invites, and audit uploads must be signed by a trusted device. Rotate or revoke a device from Team → Devices; revocation propagates via the next policy pull, and receipts signed after the revocation timestamp fail verification.

Every device-local artefact (vault, policy, receipts, connector configs) is namespaced by workspace ID and encrypted with a workspace-scoped key derived from your device password. Switching workspaces reloads the gate with a different policy bundle; the audit chain, tool catalog, and rate-limit counters are scoped per workspace and never cross-referenced.

Last-owner guard (cannot remove the final workspace owner), invite-token rotation on the server side (tokens are single-use and expire), and destructive fleet actions (policy rollback, mass revoke) require a second admin's approval within 10 minutes. All admin actions are receipted like any tool call.

Aarmos doesn't host agents — it governs them wherever they run. That's the BYO-A (Bring Your Own Agent) model: your agent runs on your compute, uses your LLM keys and your storage, and routes through Aarmos for policy, receipts, and egress. What we can govern depends on where the agent's calls actually exit: any code that respects HTTPS_PROXY (LangChain, LangGraph, CrewAI, AutoGen, custom Python/Node, most SDKs) is fully governable — enroll the shell with `eval $(aarmos env)`, since local client authentication is required. Hosted closed-loop agents (Copilot Workspace, ChatGPT hosted actions, Bedrock Agents when the tool loop runs inside AWS) have no hook point — govern the client that calls them instead.

Fully governed: agents that make outbound HTTP through the OS proxy (LangChain.js, LangGraph, CrewAI, AutoGen, OpenAI/Anthropic SDKs, `curl`, any Python `requests` / Node `fetch`). Partially governed: hosted platforms you call from your machine (Bedrock, Vertex, Assistants API) — we govern your side of the call, not what the platform does after. Not governed: fully hosted closed-loop agents where the tool loop runs off your device (Copilot Workspace, ChatGPT with hosted tools, Bedrock Agent action-groups executing inside AWS). Workaround for the third row: run an open framework (LangGraph/CrewAI) on your own compute and put Aarmos in front — you keep vendor choice AND governance.

Run `aarmos doctor`. It verifies the local runtime is reachable, reports the active session, transport and exposure class, checks that your shell carries authenticated proxy credentials (`eval $(aarmos env)`), that LLM keys are present, and that the workspace has a valid policy bundle. Emits a signed AVAR receipt so the check is part of your audit trail. Add `--fix` for guided remediation. Add `--sovereignty` to print the sovereignty manifest — declared claims about local authority alongside the evidence observed on this machine — which is the artifact to attach to a procurement or audit review.

You almost certainly don't need it. Aarmos rejected TLS interception in ADR-0001 — the proxy tunnels HTTPS by hostname and never decrypts it, so no root CA is installed and none is required for the normal path. `aarmos trust` remains a dormant surface for local trust-store inspection (`aarmos trust status`); if a CA was ever installed, remove it with `aarmos trust uninstall`.

Yes — `aarmos resume` restores a snapshot of an agent's state (context, tool history, receipt chain head) and continues from the pause point. Snapshots are written to `.aarmos/snapshots/`, signed, and versioned so a resumed run's receipts chain cleanly onto the pre-pause chain. Useful for handing off between machines, resuming after a laptop reboot, or replaying from a saved checkpoint.

`aarmos eval --a config-a.json --b config-b.json --n 20` runs the same task N times against each config and prints per-run latency, cost, verdict counts, and receipt hashes. Configs can differ by model, system prompt, policy bundle, or connector set. Results are signed as AVAR entries so the benchmark itself is auditable.

Yes. Open any run in the Console and use Time Travel to step through each decision, tool call, and verdict in order — with the exact arguments, redacted values, policy that fired, and the receipt entry produced. Same data an auditor sees; no re-execution required.

Every released CLI build stamps its build fingerprint into the `origin` field of each receipt (AVAR 1.4). Verify with `aarmos verify release` or drop the CLI binary on /trust/release. Official builds sign to a hard-pinned Aarmatix release-signing key; unofficial forks fail the fingerprint check. Passive by default — the ProvenanceChip in the UI turns green on official builds without any user action.

Yes: `aarmos verify --require-origin=aarmos <bundle>` rejects receipts whose `origin` doesn't match a pinned Aarmatix release fingerprint. Opt-in — receipts from dev/self-built CLIs still verify chain and signature by default, they just carry `origin: { release: "dev" }` and won't pass the strict flag. Useful for supply-chain-sensitive auditors.

No — Aarmos source code is not published. What IS open is verification: the AVAR spec is public (CC-BY-4.0 at github.com/Aarmatix/avar-spec), and the verifier ships as Apache-2.0 licensed artifacts (`@avar-standard/verify` on npm and the standalone `avar` CLI binary) that anyone can run offline against nothing but the keys in the bundle. That split is deliberate: the receipts you produce are verifiable forever by anyone — no Aarmos server, no license lookup, no continued existence required — but the runtime, policy gate, adapters, and PWA source stay closed.