How ORBIT works

ORBIT sits at the boundary between an agent's intended tool call and the runtime that has been wired to execute that call. A useful analogy is a badge reader on a secure door: it can check the door where it is installed, but it cannot claim to guard every door in the building. ORBIT's hook and adapters govern the action classes they observe.

That position is what makes the receipt meaningful. ORBIT signs the decision before the observed action is allowed to continue; the receipt binds the authorization decision to the operation shape ORBIT saw. If a tool path is not connected to ORBIT, the architecture should be described as uncovered, not as silently enforced.

An Agent Policy is your governance policy in machine-readable form. It says what the agent is allowed to do, what gets blocked, and what needs human approval at the moment of action. Agent Policy data lives on ORBIT's side, is signed by ORBIT's key, and is referenced by hash in receipts for governed calls. That makes later edits or swapped policy artifacts detectable in the evidence trail; it is not a claim that ORBIT can control tools or runtimes that were never wired through ORBIT.

The design invariant for policy modifications is that they are themselves governed actions and go through the same approval gate as any other change. That self-protection is the target model. The current Agent Policy editor surface is a preview build: rule mutations update local state only, and the approval step is simulated. The signed-policy and hash-in-receipt half of this model is live today; the approval-gated mutation half lands with the live escalation API.

Policy rules read like sentences: When agent tries to: Run a Bash command. Matching: any sudo command. Decision: Ask me first. The UI presents the rules as plain English; the underlying engine record is a structured tuple of tool, pattern, verdict, fallback, description, and timeout. Users edit Agent Policy; the signed policy artifact is what the receipt hashes.

orbit-hookis a small native binary that runs through the supported agent hook system. It observes tool calls before the configured runtime executes them. It does not proxy the LLM. It does not see the LLM's output, the user's prompt, or earlier conversation context. It sees the structured payload the agent passed to the tool runtime for the adapters it is installed on.

For each governed call, orbit-hook issues a Decision Record request to the ORBIT gateway with the tool name, the payload, and session metadata. The gateway evaluates against the active Agent Policy and returns a verdict (Allow / Ask me first / Block). The hook then returns that decision to the runtime path it is governing.

For routine operations (normal Read/Write/Edit, common Bash commands, git/npm work) the evaluation is designed to be fast enough for an agent loop. The latency is real and intentional: the round-trip is what produces the signed decision record. For configured governed calls, the gateway is the signing authority; the local hook can observe and relay, but it cannot mint an ORBIT receipt on its own.

For sensitive matches, the gateway returns “Ask me first” and the agent pauseswhile ORBIT surfaces the approval in the approver's ORBIT browser session and, if notifications are enabled, alerts them there. The agent does not see the alert; it sees a wait. When approval arrives, the gateway returns the final verdict and the agent proceeds. Approval delivery is out-of-band on purpose so an agent running overnight with no one at the keyboard is still gated.

Every governed decision produces a cryptographic receipt. The receipt binds together:

• The hashed Agent Policy that was active at decision time (so the policy is auditable)
• The canonical action that was evaluated (tool name + payload hash)
• The verdict (Allow / Block / approval-with-decision-trace)
• The principal (which ORBIT account, which agent session)
• A digital signature from ORBIT's signing key (current receipt algorithm: Ed25519 / EdDSA; the algorithm identifier travels in the receipt and published JWK so verifiers know which primitive to use)
• The timestamp and the signing-key identifier (so rotation is traceable)

The receipt does NOT contain raw execution artifacts (file contents, command output, HTTP response body). It can carry reported or verified outcome fields (the receipt-tier model distinguishes authorization-only, authorization + reported outcome, and authorization + verified outcome), but never the raw payload the action produced. A receipt also does not prove that every surrounding action in the session was governed, only that this observed decision record was signed under the named policy. The action's consequences live wherever the action wrote them; ORBIT's job is to make the decision itself tamper-evident.

Receipts are independently verifiable. The ORBIT public key is served at /api/public-key. The web verifier at /verify is live today and uploads the parsed receipt to ORBIT for a server-side signature check. The offline orbit-verify CLI is on the roadmap and not yet published; see /docs/verify for the planned install and pinned-key flow. Fetching the key from /api/public-key does contact ORBIT. Once a verifier has a pinned or archived copy of the public key, anyone with a .orbitprooffile will be able to confirm the signature offline without contacting ORBIT's infrastructure (via the CLI, once shipped).

That property is important for audit and dispute resolution: a receipt presented as evidence months later remains verifiable without depending on ORBIT being available. Customers can archive .orbitproof files in their own systems and reverify them through /verify today, or through the offline CLI once it ships.

Receipts are owner-only at the access layer. The web verifier accepts a file upload and returns the verdict; it does NOT expose receipts by URL. Sharing happens by exchanging the file through whatever secure channel the parties already use.

For a configured governed call, if orbit-hook cannot reach the gateway, the hook returns a block-style failure rather than minting a local allow receipt. In plain language: for the path where ORBIT is actually installed, an ORBIT outage pauses governed work instead of silently permitting it.

Same principle on approval timeouts: if you do not respond to the approval alert within the configured window (default 120 seconds), the approval request resolves to denied. This is not a claim that ORBIT can stop unrelated uninstrumented processes on the same machine; it is the behavior of the governed hook/adapter path.

Guardian is the first ORBIT module shipping. Payments, trading, agentic apps, creator ops, and enterprise exception routing share the same action-boundary primitives: Agent Policy, runtime evaluation, signed receipts, and the verifier path. Adding a control view means adding an adapter that normalizes the surface's requested action into ORBIT's canonical action shape, plus the policy content for that surface. The trust model and the receipt format stay stable across views.

Our patents cover these core mechanisms across all modules.