How-to

Observe a local runtime

The Aarmos runtime runs on your machine, and so does its evidence. The Operations UI can render a read-only view of that activity without any of it leaving the machine. The CLI and the browser are equal clients of the same local observation service — neither one owns it.

How it works

  your machine                                 your browser
  ────────────                                 ────────────

  aarmos observe
     │
     ├─ starts the local observation service (loopback only)
     ├─ prints an 8-digit pairing code        ──── you read it ────┐
     └─ prints the destination URL            ──── you open it ──┐ │
                                                                 ▼ ▼
                                                        Operations UI
                                                                 │
                                        code exchanged over loopback
                                                                 │
                                    short-lived read-only session
                                                                 │
   signed receipts on disk  ──derived──▶  read-only projection ◀──┘
   (authoritative)                        (non-authoritative)

1. Start the observation service

Run this inside the workspace you want to observe. Nothing starts automatically: discovery is always something you ask for, so a CI job never prints a code.

aarmos observe

The command prints the observation source, the destination URL, and an 8-digit pairing code. Press Enter at any time for a fresh code. Add --open if you want the browser opened for you — the CLI never does that on its own, and never in CI.

The observation service listens on loopback port 7682 by default — a convention, not a reservation, and separate from the governance endpoint on 7681. Change it with --port; the printed destination follows whichever port you choose.

2. Open the destination and enter the code

The terminal prints the exact address to open. It contains the loopback address of the service and nothing else — no credential is ever placed in a URL, where it would leak through history, referrers, screenshots and crash reports.

Enter the code within two minutes. It is single-use with a five-attempt budget: the browser exchanges it over loopback for an opaque, read-only session that lives in that tab. Pairing establishes identity; the session establishes access.

3. Optional: remember this browser

Tick Remember this browser and the runtime registers it as a known observation client, so later sessions reconnect without transcribing a code. This is a convenience over an introduction you already made — it grants nothing on its own and is redeemable only over loopback.

A registration ends at the earliest of: 30 days, the runtime rotating its local session, a change of workspace or observation source, or you revoking it.

aarmos observe status
aarmos observe --forget-clients

Operators who want no durable client records at all can set AARMOS_OBSERVE_TRUST=disabled; every session then requires a code.

Self-hosted Operations

Point the CLI at your own deployment. The same value drives both the printed destination and which origin is permitted to pair, so the two can never drift apart.

export AARMOS_OPERATIONS_URL=https://ops.example.com/observe
aarmos observe

What this does not do

  • It is not remote access. The service binds to loopback and refuses anything else. There is no remote observation mode.
  • It is not authoritative. Everything shown is derived from the signed receipts on your disk and can be re-derived from them. If retention pruned part of the window, the UI says so rather than showing a number that cannot be reproduced.
  • It is not control. The grant carries a single read capability. The browser cannot evaluate policy, sign anything, or write evidence.
  • It is not storage. No observation is persisted by the browser. Closing the tab ends the session.
Pair a runtime nowOperational IntelligenceSecurity model