⚠️ This feature is a security nightmare by design. The goal is to make it a manageable security nightmare.

• A compromised AutoGPT platform account — if someone has your OAuth token, they can use your shim. Protect your account with 2FA.
• Physical access to the machine running the shim.
• A malicious Claude response that the user explicitly approved.
• Root-level operations — the shim runs as the user, not root. Don't run it as root.

The public shim client receives the existing USE_TOOLS OAuth permission. Individual local capabilities are a separate, shim-enforced boundary: shell, computer use, clipboard access, local models, and hardware are only advertised when their local configuration gates are enabled and their runtime dependencies are available. Recording is stricter: it remains a design preview, is never advertised, and causes startup to fail closed if enabled. The platform's grant cannot turn on a locally disabled capability.

All FILE_* operations are jailed to the per-chat allowed_root. In normal control mode the user selects it through one-level remote directory browsing; legacy --session-id mode still reads it from startup configuration. The full algorithm is in CROSS_PLATFORM.md → Path Jail Strategy; a naive path.startswith(allowed_root) check is not enough and the shim must use the prescribed algorithm. Violation → PATH_OUTSIDE_ALLOWED_ROOT error, no execution.

This jail is not a shell sandbox. When the user explicitly enables shell execution, both shell strings and direct argv processes run with the shim user's normal OS permissions. Validating the subprocess working directory does not stop a command from reading, writing, executing, or making network requests outside allowed_root. Treat --enable-shell as user-account-level access.

Recommended: create a dedicated workspace directory, not your home dir.

~/.autogpt/workspace/   ← good
~/                      ← bad, don't do this
/                       ← extremely bad

The platform cannot submit a path to the host browser. Navigation uses random, five-minute opaque references bound to the current control connection. A selection consumes the browse and produces an HMAC-signed root grant bound to machine, session, revision, canonical path, and filesystem fingerprint. Every control reconnect invalidates all outstanding references. Restoring a session requires the grant and revalidates the live directory identity.

Directory browsing exposes immediate directory names and canonical paths to the paired platform. It never returns files, content, sizes, timestamps, permissions, symlinks/junctions, inaccessible directories, or recursive data. Control connections cannot execute data-plane operations; activated children use copied configuration and immutable session-bound audit contexts.

Every wire operation (EXECUTE_COMMAND, FILE_*, INPUT_ACTION, SCREENSHOT_REQUEST) plus shim-internal events (start/stop, WS connect/disconnect, JAIL_VIOLATION, TOKEN_REFRESHED) is appended to a JSONL audit log in the per-OS state directory (see CROSS_PLATFORM.md → Audit log location). Each record carries an HMAC-SHA256 chain so truncation, record deletion, or field tampering breaks verification at the first modification. Full format, per-op fields, the tamper-evidence algorithm, and the autogpt-shim audit CLI are spec'd in AUDIT_LOG.md. The audit key never leaves the machine; the user provides it out-of-band when uploading a log for support. Audit initialization is mandatory: if the key or writer cannot be created, daemon construction fails and the CLI exits with EX_CONFIG rather than running in an unaudited degraded mode.

Shim enforces:

• Max 60 commands per minute across all child chats on the machine
• Max 10 concurrent commands across all child chats, additionally bounded by the machine-wide negotiated max_concurrent
• Max 10 MiB per file read/write by default; text responses reserve JSON framing headroom
• Max 10 screenshots per minute across all child chats (computer use)

Exceeding limits → SHIM_OVERLOADED error returned to platform.

Future: shim can be configured to require local confirmation (system notification + user click) before executing commands matching certain patterns (e.g., rm, sudo, any write to paths outside a sub-directory). Useful for cautious users who want human-in-the-loop.

Shim can optionally run commands inside a network namespace that blocks outbound internet while allowing localhost. Useful for preventing data exfiltration via executed commands. Requires Linux + root for namespace setup, or a bubblewrap wrapper.

• Tokens stored in OS keychain (never in dotfiles or env vars)
• Access token short-lived (1 hour); refresh token used for renewal
• Refresh token stored encrypted in keychain
• autogpt-shim revoke posts both access and refresh tokens to POST /api/oauth/revoke as the public client, and only then clears the OS keychain. A network/server error preserves local tokens so revocation can be retried instead of falsely reporting success.
• A successful platform revocation also pushes session revocation to connected shims.
• Tokens carry USE_TOOLS; the WebSocket additionally checks session ownership, client identity, and local capability gates.

Encrypted-file fallback: when the OS keychain is unavailable, the shim stores tokens in $XDG_STATE_HOME/autogpt-local-executor/tokens.enc (Linux/WSL2) using AES-256-GCM. The key is derived (Argon2id) from a passphrase that must be supplied via the AUTOGPT_SHIM_KEYCHAIN_PASSPHRASE env var on every shim start. No passphrase = no shim start. This is deliberately friction-heavy so users on capable systems install a real keyring instead.

Security note: an attacker with read access to the file AND the env var can decrypt the tokens. This is no worse than dotfile-based storage but no better either — the keychain backends remain the recommended path.

If you believe your shim was compromised:

1. Stop the foreground daemon with Ctrl+C, or stop its launchd/systemd/Task Scheduler entry.
2. autogpt-shim revoke — revokes all OAuth tokens
3. Review the audit log at the per-OS location (see AUDIT_LOG.md) with autogpt-shim audit tail / verify
4. Change your AutoGPT account password and re-enable 2FA
5. Report to security@autogpt.net with the audit log

• No command allow/deny lists yet (after opt-in, shell commands have the shim user's normal access and are not confined to allowed_root)
• No local confirmation prompts yet
• No network isolation
• Audit records are HMAC-chained; protect the audit key in the OS keychain.
• Computer use has no "sensitive region" masking (entire screen captured)
• Shim crash does not guarantee in-flight commands are cancelled

These are tracked as issues. PRs welcome.