Observa help · Getting started

From npm install to your first shadow observation.

This is the whole path for Observa Local Node, the CLI that observes an n8n runtime. Every command below is the current shipped syntax for @mcpherson-ai/observa-local-node 0.1.6.

SHADOW_ONLY · AUTHORITY NONE · ENFORCEMENT OFF — Observa observes and reports. It has no authority to allow, deny, approve, block, retry, or change anything in your systems.

Before you start

Two packages are called `observa`. Pick the one that matches your runtime.

This guide

Observa Local Node — n8n

Published on npm as @mcpherson-ai/observa-local-node, currently 0.1.6. Installs a signed composition, observes n8n through n8n’s own global backend hook, and pairs with --base-url.

Separate package

McPherson Governance connector — OpenClaw

Published on ClawHub and GitHub as @mcphersonai/mcpherson-governance-openclaw, currently 0.7.3. It ships its own observa executable with a different command set and pairs with --api-url. See the OpenClaw section of the CLI reference.

Requirement for both: Node.js 22 or newer.

The path

Eleven steps, and nothing is skipped on your behalf.

Install the CLIFrom npm. Nothing is activated.
Inspect locallyOptional, offline, no account needed.
Request Hosted accessYou submit; nothing is granted yet.
Verify your emailOne-time code, 10 minutes.
Human reviewA person decides. This is not automatic.
Redeem your invitationSign in, accept the beta documents.
Obtain a pairing codeCreated by you, in Hosted Observa.
Pair this installationBinds this machine to your workspace.
Install the signed compositionVerified locally before anything is composed.
Configure the runtimeOne local secret, then the n8n hook.
Start, then observeActivity, evidence, and governance analysis.

Step 1

Install the CLI

npm install -g @mcpherson-ai/observa-local-node
observa --version

observa --version prints observa-cli 0.1.6 and the authority line. Installing the package activates nothing: it has zero dependencies, runs no install scripts, and contacts no network service until you explicitly pair.

observa --help prints the full usage and links back to these pages.

Step 2 — optional

Inspect a workflow offline, before you have any access

observa status
observa inspect-workflow --file ./workflow.json

Export a workflow as JSON from n8n and point at the file. The report counts recognized node types, nodes, connections, disabled nodes, isolated nodes and unresolved connections. It prints no node names, IDs, parameters, credentials or payloads, and unrecognized node types are counted without displaying their labels.

What this is not. inspect-workflow reads one file you chose. It does not observe execution, collect runtime evidence, classify capabilities, evaluate policy, establish trust, or grant Hosted access. Its own output says so: runtime_observed: false, evaluation_state: "UNEVALUATED", linkage: "UNLINKED", business_outcome: "UNVERIFIED".

Steps 3–5

Request access, verify your email, wait for a human

observa request-access --api-url https://governance-plane-observa.tailb473db.ts.net

The command prompts for your name and email, and optionally an organization and use case. It then shows you the exact record it is about to send and waits for you to type yes. Nothing leaves your machine before that confirmation. No runtime credentials and no workflow content are ever included.

A one-time verification code is emailed to you. Run the command again to enter it:

observa request-access --api-url https://governance-plane-observa.tailb473db.ts.net

Without --code-file, the code prompt hides your input. For unattended use, write the code to an owner-only file and pass --code-file <0600-file>.

Check where you stand at any time:

observa request-status

Verification is not approval. A verified email moves your request to PENDING_REVIEW. A person then approves or denies it. There is no self-service path from request-access to a working installation, and no amount of retrying creates one. The exact lifetimes, retry limits and states are on the pairing and access page.

Steps 6–7

Redeem the invitation and create a pairing code

Approval sends a single-use invitation to your verified email. Redeem it in a browser, sign in, and accept the beta documents. Then open Installations → Create pairing code and copy the code.

The pairing code is short-lived, single-use, and bound to your organization and workspace. It is not a credential and it grants nothing on its own. If the invitation email never arrives, run observa request-access --resend.

Steps 8–9

Pair, then install the signed composition

observa pair --base-url https://governance-plane-observa.tailb473db.ts.net --code-stdin

Paste the pairing code, then press Ctrl-D. The code is read from standard input so it never enters your shell history, and it is never accepted as a command-line argument. The credential that comes back is stored owner-only and is never displayed; the command prints only the installation id, credential id, fingerprint, deployment id and Hosted URL.

observa install

With no --manifest, install retrieves the signed installation manifest Hosted issued for this installation, verifies its Ed25519 signature locally against the public key shipped inside the package, checks the tenant and installation binding, and verifies every component artifact against its manifest-pinned SHA-256 — and only then composes. Transport is not trust: a hand-delivered manifest passed with --manifest <signed.json> goes through exactly the same verifier.

Step 10

Configure the n8n runtime

observa config set n8n_loopback_credential '<choose any local secret, 24+ characters>'
observa n8n-setup
observa start

That credential is yours. It authenticates n8n’s calls to Observa’s own loopback endpoint on this machine. It is stored owner-only, is never transmitted by the installer, and never appears in any Observa output.

n8n-setup writes an owner-only environment file for n8n’s supported global backend hook and prints its path. You must configure your own n8n service or container to load that environment file before n8n starts. Observa never restarts or reconfigures n8n for you.

The hook observes ordinary workflows automatically. Do not add an Observa node to a workflow. It reads execution metadata only, and never item data, node parameters, credentials or workflow static data.

Step 11

Observe, and read the results honestly

observa status
observa activity
observa decisions
observa diagnose

activity shows recent local observations. decisions shows only records that were actually evaluated, as counterfactuals: WOULD_ALLOW, WOULD_DENY, WOULD_REQUIRE_APPROVAL, ABSTAIN, INDETERMINATE, ERROR.

A counterfactual is not an action. WOULD_DENY means a policy would have said no. It does not mean Observa blocked or modified anything — nothing was blocked, because enforcement is off. Read the safety model before you act on any of these words.

An idle runtime produces nothing. That is normal, not a fault.

Where to go next

The rest of the help set.

Every command, flag and side effect → Access and pairing lifecycle, with exact timings → Ten common failures and their safe recovery → What Observa does and does not claim → How to get help without leaking anything →

Request Private Beta Access Open the CLI reference