Skip to content

Installation and connect safety

Release artifacts

The canonical installer downloads a GitHub Release archive and verifies SHA-256 against the published *-manifest.json before extract.

Publication state: the public channel default is published v1.1.1 (runtimeLayout=self-contained-v1). Older channels remain available via explicit OCCAM_VERSION (for example 1.0.0-rc.3 or legacy Level B 1.0.0-rc.2).

1.0.0-rc.3+ contract (runtimeLayout=self-contained-v1):

  • The requested version, platform RID, and tarball name must match the manifest.
  • Archive-member preflight runs before extraction.
  • When the outer manifest declares signaturePolicy=required-cosign-v1, the installer verifies the Cosign bundle against the expected release-workflow identity and fails closed on missing, malformed, tampered, or wrong-signer material. Manifests without that policy (or with sha256-only) stay on the legacy SHA-256 integrity path — including published v1.0.0-rc.2.
  • Before replacing an existing install, the bootstrap validates the staged host binary, VERSION, inner release manifest, and the complete bundled runtime/helper set from that archive. Post-install steps use helpers from the verified archive; they do not fetch executable runtime/helper overlays from the mutable repository branch.
  • Bootstrap script delivery may still originate from raw.githubusercontent.com/.../main/... (mutable bootstrap delivery). That is separate from release runtime content, which for rc.3+ is closed inside the hashed (and, when required, Cosign-verified) archive.

Replacement is ownership-gated in both directions. The staged tree must pass the release checks above, and an existing OCCAM_INSTALL_DIR must be a real, non-linked Occam release with a consistent VERSION, inner manifest (layout: level-b markers), current RID host, and launcher markers. A source checkout, symlink/reparse point, malformed release, or arbitrary directory is refused before process preparation or any move. Legitimate older Level B releases remain updatable.

The previous release tree stays beside the new tree until doctor, self-check, launcher setup, and Connect complete. If a post-swap step fails, the bootstrap first stops processes launched from the new tree, then restores the previous tree; a failed first install is removed. If processes cannot be stopped, neither tree is deleted and both paths are printed for manual recovery. Post-install steps can also touch the user launcher, operator state, and host configuration; the tree rollback does not claim to undo every external mutation.

The user launcher follows the same rule: an existing occam, occam.cmd, or occam.ps1 is replaced only when its complete contents match a launcher generated by the current or previous Occam release. Unrelated collisions fail before any launcher is staged. Windows updates both launcher files as one temporary-file-and-rename transaction and restores the previous pair if either rename fails.

Authenticity honesty: Cosign verification (when signaturePolicy=required-cosign-v1) proves release archive authenticity / signer identity relative to the expected GitHub Actions workflow — not that page content is true, that Occam authored upstream web pages, or that fetched web content is trustworthy. Do not describe every historical release as Cosign-enforced; published v1.0.0-rc.2 remains on the SHA-256 path. Do not use unqualified “cosign-verified install” marketing.

npm honesty: npx @ff-occam/mcp is not a GA 1.0 install channel. Use the release tarball / bootstrap scripts documented in Install.

What install writes

Location Sensitivity
OCCAM_HOME install tree Product binaries, workers, scripts
~/.occam/onboard.json Operator env defaults (merged on every launch)
~/.occam/keys/signing-key.pem Critical — ECDSA signing key, minted on first host start
Host MCP configs + *.occam-bak Connect mutations
Playwright browser cache Large but not secret

Removing the install directory does not uninstall all Occam state. Session profiles, keys, watch/batch stores, and host configs may remain under ~/.occam/ and your AI host config paths.

Config changes (occam connect)

When Occam registers itself with an AI host it:

  • Never overwrites an existing ff-occam entry it did not create (unless you pass --force)
  • Backs up before writing
  • Writes atomically (no half-written config on interrupt)
  • Rolls back a broken registration it owns
  • Keeps registrations that only need a restart or trust prompt
  • Does not mutate desktop configs in CI by default

Connect makes no network calls for registration — it only touches local files and may start the local Occam server to verify it responds.

Disconnect and uninstall

Always preview first:

occam disconnect --dry-run
occam uninstall --dry-run

occam disconnect uses the same ownership rules as Connect. It removes an ff-occam registration only when the entry carries the managed marker or points at the Occam launcher/wrapper. An unmanaged, undecodable, malformed, or ambiguous entry is preserved; unsafe ambiguity blocks the operation.

occam uninstall performs these scopes in order:

  1. Disconnect managed host registrations. If this fails, install files stay in place.
  2. Stop only Occam host processes whose command path is under this OCCAM_HOME.
  3. Remove generated occam launcher files that point at this OCCAM_HOME.
  4. Remove OCCAM_HOME only when it is a recognized Occam release tree (inner layout: level-b markers; rc.3 archives are self-contained).
  5. Remove the narrow response cache only when --remove-cache was explicit.
  6. Remove ~/.occam/ last, and only when --remove-state was explicit and every earlier step succeeded.

The default command preserves:

  • source checkouts (.git present)
  • unmanaged host entries and host-side sibling settings
  • *.occam-bak config backups
  • ~/.occam/ operator settings, signing keys, sessions, watch/batch state
  • installed agent skills and the shared Playwright browser cache
  • the user ~/.local/bin directory and PATH entry (they may be shared by other tools)

The preview inventories both cache locations. --remove-cache can remove only the flat Occam response cache (OCCAM_CACHE_DIR, default {TEMP}/occam-cache) after path, symlink, overlap, and entry-shape checks pass. The shared Playwright browser cache is never removed automatically because other Playwright projects may use it.

occam uninstall --remove-state additionally removes the exact user-scoped ~/.occam/ directory. That deletes credentials and sessions and cannot be undone unless you made your own backup. Preview that scope with --dry-run --remove-state first.

Removal refuses relative paths, filesystem roots, the user home directory, symlinked targets, and directories that do not carry the expected release markers. Source checkouts are recognized and preserved. It does not guess.

Sessions and secrets

  • Session profiles are local JSON under OCCAM_SESSIONS_ROOT (default ~/.occam/sessions/)
  • They contain secrets (cookies, headers, Playwright storageState)
  • occam session import does not retain plaintext sources under _imports/ by default — use --keep-import only when intended
  • Do not commit profiles
  • Do not put LLM API keys in Occam's environment

Next