Local AI isolation

Why AI tools (Claude Code, Gemini CLI, Codex) structurally cannot view protected secret values — process scoping, keychain tiers, and explicit deny lists.

Three layers of isolation. Each layer is sufficient on its own. Together, they make leakage structurally impossible.

This page is the proof, not just the claim. AI tools running on this workstation cannot read tokens from the locked keychain, cannot persist tokens to the parent shell, and cannot read the file paths where keys live at rest.

Layer 1 — process scoping via subshells

Every AI launcher runs claude inside a subshell. The subshell exports GITHUB_TOKEN; when claude exits, the subshell exits, and the env reverts. The parent shell never sees the token.

Green nodes are the parent shell (host), coral are the ephemeral subshell + claude process, ink is the keychain. The chain runs left-to-right and ends where it began — the parent shell on the right still has GITHUB_TOKEN unset.

The launcher banner (verbatim)

Every launcher prints this to stderr before calling exec claude. The banner lands in the AI’s tool-output stream so it knows what it can and cannot do this session:

[claude-launchers] custom authentication context is now active
  type:    github-token tier
  context: restricted
  scope:   this claude process only — the parent shell is unaffected

You now have the credentials and capabilities granted by this context.
Tools that auto-detect credentials from the environment (aws, gh, git,
terraform, kubectl, etc.) will pick them up automatically. Nothing
persists once claude exits; the parent shell's environment is untouched.

No secret material is ever printed. The banner names the kind of context, never the value.

Layer 2 — keychain tier separation

Secrets live in two separate macOS keychain databases. The detail is in macOS Keychain; the boundary that matters here is:

Database	Holds	AI subprocess can read?
automation.keychain-db	GH_PAT_RESTRICTED, HF_TOKEN, BWS_ACCESS_TOKEN	Yes — via launcher subshell (Layer 1)
elevate-access.keychain-db	GH_PAT_PRIVATE, GH_PAT_ADMIN, GH_PAT_ORG_ADMIN	No — GUI unlock prompt blocks non-interactive reads

gh-claude-restricted works non-interactively. gh-claude-private and gh-claude-admin exist for human use; an AI subprocess cannot satisfy the unlock prompt.

Layer 3 — explicit allow / deny lists in Claude Code

The Claude Code permission system bakes a deny list into the build. Even if the previous two layers were bypassed, the harness refuses the file paths that would yield secret material.

Allow (read-only inspection)	Deny (Read / Edit / Write blocked)
security find-generic-password (lookup metadata)	**/.env*
security list-keychains	**/secrets/**
security show-keychain-info	~/.gnupg/**
	~/.ssh/id_*

The allow list lets the AI inspect metadata — “is there a keychain entry called GH_PAT_ADMIN?” — without ever returning the value. Reading the value still requires the launcher path, which goes through the subshell layer.

Layer 4 — passwordless sudo, but only for darwin-rebuild

The nix-darwin configuration grants passwordless sudo exclusively for two paths: /run/current-system/sw/bin/darwin-rebuild and /nix/var/nix/profiles/system/activate. Both are declarative — they apply Nix store paths already built. No ad-hoc shell, no read access to anything else.

What AI can and cannot do

Capability	AI tool	Why
Read PAT value from automation keychain	✅ (only via launcher subshell)	Subshell scoping; value never reaches parent
Read PAT value from elevate-access keychain	❌	GUI unlock prompt; AI cannot respond
Modify keychain entries	❌	security add-generic-password not in allow list
Read .env* files	❌	Path glob denied
Read ~/.ssh/id_* private keys	❌	Path glob denied
Read GPG keys	❌	~/.gnupg/** denied
Run sudo outside darwin-rebuild	❌	sudoers entry is path-restricted
Run doppler run -- <cmd>	✅	Doppler injection at subprocess boundary; same scoping rule as the launchers

Source files

For the literal Nix and shell sources behind each layer, see:

• nix-darwin/hosts/macbook-m4/gh-token-switching.zsh — the three-tier keychain reader.
• nix-darwin/hosts/macbook-m4/claude-launchers.zsh — the subshell launchers and banner.
• nix-claude-code/data/permissions/allow.nix — read-only security allow list.
• nix-claude-code/data/permissions/deny.nix — file-path deny globs.
• nix-darwin/modules/darwin/security.nix — sudoers path restriction.

See also

• macOS Keychain — the tier model in detail.
• Doppler — for AI-readable CI secrets that should be present.
• BWS — programmatic AI-token bridge that respects the same scoping rules.