Getting Started with Occasio (5 minutes)

What you get: your AI coding agent (Claude Code, Cline, …) keeps working as usual — but it can't silently read your secrets or borrow your ssh / cloud / root access. You approve those, and everything the agent did is in a tamper-evident log you can verify offline.

Requires Node.js ≥ 18. Works on Windows, macOS, and Linux. No account, no cloud, no telemetry — Occasio runs entirely on your machine.

---

1 · Install

npm install -g @occasiolabs/occasio
occasio doctor          # checks Node, the claude CLI, Python — fix anything red

2 · Turn on the identity gate

occasio init --template strict

Writes ~/.occasio/policy.yml — the strict posture: deny secret / environment reads, and gate ssh / az / sudo behind your approval. (Want a lighter start? occasio init writes the dev-default policy instead.)

3 · Run your agent through Occasio

Zero setup — just prefix your normal command:

occasio claude "fix the failing test"

Everything the agent does now passes through the gate. To make it permanent so you can type plain claude, run occasio register once (it adds a shell alias — restart your shell afterwards).

4 · What happens when the agent reaches for something sensitive

It keeps working normally — Occasio only steps in at the dangerous moment:

• It reads .env or runs printenv → blocked. The secret never leaves your machine; the agent sees [REDACTED].
• It tries ssh deploy@prod (or az, sudo) → paused, with: Denied … requires human approval — occasio approvals approve apr_… --once.

You decide, from your own terminal:

occasio identity set --id you            # one-time: who you are (for the audit trail)
occasio approvals approve apr_… --once   # authorize this one command, once

The agent's retry now goes through once, and is consumed. A different command, or a second attempt, is blocked again. The agent cannot approve itself — that is the whole human-vs-agent point.

5 · See it, and prove it

occasio eyes          # live browser view: what's leaving your machine, secrets redacted
occasio audit verify  # cryptographic proof of everything the agent did and was stopped from

The audit chain is independently verifiable — a bundled Python walker (docs/audit_walker.py) re-checks it without trusting Occasio's own verifier.

Optional · Guard sessions that don't go through the proxy

occasio hook --install   # a PreToolUse hook in Claude Code, as a second line of defense

This catches identity-borrow commands even when the agent isn't run through the proxy. (See docs/hook-smoke-test.md to verify it end-to-end.)

---

Honest notes (so this is real, not marketing)

• Approval is out-of-band on purpose. You approve in your terminal; the agent cannot approve itself (the control plane is in its deny-zone, the token is HMAC-signed). That asymmetry is the human-vs-agent boundary.
• It's a deterministic policy + verifiable audit, not a sandbox. It stops the common, innocent mistakes (an agent "being helpful" and reaching for a secret or the server). A determined adversary using runtime tricks (encoded reads, a renamed binary) is a documented limit — the real boundary there is OS-level isolation. See docs/identity-gate.md for the full threat model.
• occasio register edits your shell profile. Restart the shell, or just use occasio claude … directly.

Every command above is verified against the published @occasiolabs/occasio@0.12.0.