Technical questions & troubleshooting

On this device by default. LLM keys and OAuth tokens sit in the AES-GCM vault (device password required). Chats and the audit ledger live in browser storage. Policy evaluation, receipt signing, and key custody never require our cloud. If you explicitly configure a customer-controlled evidence destination, signed evidence copies can leave the device for that destination. Account services receive your signed entitlement artifact refresh and, where team features are in use, 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 the destination domain, not the encrypted payload. Structured evidence depends on the specific supported runtime integration and its visibility. Standalone MCP, OpenAPI and deep-link transport adapters do not produce governance receipts. Traffic outside the supported runtime path is not governed; a direct HTTPS call is not automatically recorded. No root CA is installed by default.

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, 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; each turn uses the first available one in your order; if it fails, the turn pauses and you choose whether to continue with the next.

Aarmos is protocol-agnostic, with interfaces for MCP, OpenAPI, A2A, Bearer APIs, SQL and deep-links. Interface availability is not enforcement qualification. Standalone transport adapters perform scope checks; governed execution requires the supported composed runtime path. The browser/PWA has separate policy controls, and Bridge has local permissions. Live enforcement qualification remains limited to governed email-send. Direct credentials or network routes can bypass the governed entry point; deployment controls must address that access. Receipts establish only the authorization, forwarding and observations within their stated boundary, not a downstream business outcome.

A2A token records are stored on-device by default. Server deployments can register another backend through the token-store interface; the shipped backends are browser storage, encrypted file, and memory for tests. 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 Consequence is the proposed business action — for example, issue this refund or deploy this release. Aarmos policy evaluates that Consequence and returns the Decision: allow, deny, step_up, or defer. Authority, Attempt, Effect, and Outcome remain separate, and the receipt preserves those distinctions.

A participant is an external system or authoritative evaluator that contributes a fact or evaluation about a proposed Consequence. Participants are declared, never inferred: if a required contribution is missing, Aarmos records the gap rather than guessing. Provenance, freshness, trust, and validity remain attached to each contribution; Aarmos policy returns the Decision.

No. A Consequence identifier is a durable reference used by receipts. Schema evolution can add fields and increment the version, but changing the identifier would break continuity with earlier evidence. Retire the old definition and declare a new one instead.

In-flight governed calls abort and new governed calls are denied at the gate — including sub-agents and scripted replays on those paths. The DENY is recorded as a gate outcome in the receipt (actor, timestamp, policy-bundle fingerprint) so a reviewer can inspect device state. It 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 new governed call is denied at the gate; calls already dispatched are marked aborted on a best-effort basis. 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. The spend ceiling is client-enforced and non-atomic — concurrent calls can exceed it before it engages, so it is not a hard cap. 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. 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 open AVAR verifier library (`@avar-standard/verify`, Apache-2.0) is on public npm, and the in-browser verifier runs on-device. Retained receipts verify from their files and independently pinned trust material — no Aarmos server or license lookup is needed during the check. The specification text is not currently publicly published; it is available to evaluators on request.

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`. Zero network. Works with Aarmos uninstalled and the daemon stopped.

Given an .aarmos bundle (receipts + policy + tool catalog hashes), Aarmos re-evaluates each recorded gate outcome offline against the pinned inputs and policy. Drop the bundle on /trust/verify or run `aarmos replay <bundle>`; a divergence report identifies any recorded step that does not reproduce.

On a Decision page, Export incident package produces an .avar.zip: the selected receipt plus its delegation lineage, each entry signed with the device key that recorded it, and an incident summary listing the policy fingerprints in force. Anyone you give it to can check signatures and hash chain offline with `aarmos verify` — no call to Aarmos servers. The public keys travel inside the archive, so confirming whose device signed it needs that key confirmed separately.

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. The current Preview line is distributed directly to authorized workspaces as a signed artifact and is not published through npm; a historical npm version remains publicly resolvable and is not the current customer distribution path.

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.

The gate evaluates governed tool calls over local state, with no network call on the evaluation path, and regressions are tracked by an automated benchmark. Overhead depends on policy size, workload, and hardware; this FAQ does not publish latency figures.

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; Decisions 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-bridge 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 Decisions 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.

On this device, Audit → AVAR bundle downloads your run history as an .avar.zip — each entry signed with this device's key and hash-chained, verifiable offline with `aarmos verify`. The settings ledger is backed up separately from the backup reminder, with optional auto-export after batches of settings changes. The hosted team audit export is a different, unsigned artifact.

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, Decisions, 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.

Configure a customer-controlled evidence destination under Audit → SIEM / audit forwarding. The local runtime sends signed receipts to a customer-controlled HTTPS signer endpoint for S3, GCS, R2, or custom storage after explicit consent; Aarmos-operated evidence storage is not used. Without a destination, read the same events locally with `aarmos activity --follow`. Destination limits depend on plan; see /pricing. Event schema and starter detections are 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 the calls that route through it, on your compute. 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) can be routed onto a governed egress path — 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.

Enforcing on these paths: agents that make outbound HTTP through the OS proxy (LangChain.js, LangGraph, CrewAI, AutoGen, OpenAI/Anthropic SDKs, `curl`, any Python `requests` / Node `fetch`) — the named egress path is enforced, which is not a claim about paths Aarmos does not sit on. Enforced on your side only: hosted platforms you call from your machine (Bedrock, Vertex, Assistants API) — the outbound request from your machine is evaluated; what the platform does afterwards is not observed and is not claimed. No enforcement path: 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) — Aarmos asserts nothing about those executions. Workaround for the third row: run an open framework (LangGraph/CrewAI) on your own compute and put Aarmos in front of its egress path.

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 does not intercept TLS — 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, Decision 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 Consequence, Decision, Attempt, and available Effect observation in order — with redacted arguments, the policy that applied, and the receipt entry produced. No re-execution is required.

Check the package before you install it. Each preview release comes with a signature from the Aarmatix release-signing key, and the release verifier offered with the download confirms that the exact file you received is the one Aarmatix signed; altered or renamed files are refused. Receipts also carry an `origin` label naming the build that wrote them. That label is self-declared metadata: it helps sort receipts, but it does not prove which build ran. A receipt's own signature shows whether the receipt is intact and which key signed it; whether you trust that key is a separate check. Aarmos does not currently provide cryptographic proof of which build executed an operation.

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-standard/verify` library (Apache-2.0) is on public npm, and the in-browser verifier runs on-device. A bundle's keys establish integrity of each record; attributing a signer requires independently pinned trust material, and unsigned or incomplete evidence is not proven complete. The AVAR specification text is not currently publicly published. That split is deliberate: retained receipts remain independently verifiable from their files and trust material — no Aarmos server or license lookup required during the check — but the runtime, policy gate, adapters, and PWA source stay closed.