All docs.

Command and provider reference Detailed command, provider and service notes for the gateway CLI (formerly the long README). Read when: Looking up a gateway command, provider option or service behavior · Changing installation, login, discovery, service or uninstall behavior GateFox for macOS Install the native fox app and manage the gateway using its existing settings. Read when: Installing or changing the native macOS app · Changing app configuration discovery, setup, status, or packaging Setup and connections Native setup wizard, account connections, model selection, and the private app-management protocol. Read when: Changing first-run setup or connection management in the macOS app · Changing account sign-in, API-key storage, model selection, or app configuration writes · Testing the wizard against an isolated gateway Gateway permissions on macOS Optional Full Disk Access invitation and macOS permissions used by GateFox. Read when: Changing the native app permission invitation or privacy settings · Investigating protected-file access, Automation, or Local Network grants Speed controls Speed (service tier) handling for gateway and native rows in the Codex desktop adapter: session start versus mid-chat, Flex, unknown tiers and the private tier store. Read when: Changing service tier handling in the desktop adapter or the Responses providers · Investigating a Fast, Flex or Standard mismatch in a gateway chat · Changing the private thread tier store or its 0.4.0 compatibility Execution activity Gateway-owned, read-only execution snapshots and recorded turn outcomes; no Codex client changes. Read when: Checking whether work continued after closing a viewing laptop · Changing the Gateway Activity screen or gateway activity command · Investigating missing completion or failure indicators after reconnect Background command completion Opt-in command completion receipts resume gateway agents without Goal mode. Read when: Running finite background commands or watching an existing tmux job · Investigating a command that finishes after the agent ends its turn · Changing executor background completion delivery or stop behavior

Messages clients Native Anthropic Messages ingress and Claude Code client settings for the shared gateway model catalog. Read when: Connecting Claude Code or an Anthropic-compatible client to the gateway · Changing Messages parsing, streaming, tool replay, or client configuration Claude Desktop Opt-in Claude Desktop model aliases, isolated account catalogs, setup, and tested limits. Read when: Adding Claude Desktop as a gateway client. · Showing multiple GPT accounts or local models in Claude's model picker. · Installing or updating the Claude-only adapter without changing Codex. Codex app-server adapter Experimental Codex desktop adapter: additive model catalog, per-chat routing, and the index of the guides that hold its detail. Read when: Connecting the gateway to the Codex desktop app · Changing app-server routing, model selection, or configuration writes · Looking for which app-server guide holds one section Native relay, remote control and native sharing How the desktop adapter decides whether to use the native relay, shares the native engine, trims SDK features and guards native configuration writes. Read when: Deciding whether a Mac needs the native relay or its remote control · Changing shared native engines, private native-home leases or the desktop fallback · Reviewing the refused native configuration writes or the gateway preference file · Debugging CODEX_CLI_PATH, the desktop wrapper or a fresh desktop launch Desktop login environment The login race that can start ChatGPT without the gateway, the managed login agent that closes it, and what desktop status reports about it. Read when: ChatGPT starts at login without CODEX_CLI_PATH · Registering, rolling back or removing the desktop login environment agent · Reading gateway desktop status for the login environment or API mode Model catalog, picker and usage counters Native picker selection, Codex subscription counters, model changes inside a loaded chat, and how Codex 2 rows borrow the native catalog. Read when: Changing the native model picker, its placement or hidden rows · Investigating a missing Codex counter or a rejected configuration write of a model · Changing model selection for a loaded or running chat · Changing how Codex 2 rows copy native model metadata or node_repl policy Chat and executor lifecycle Sub-agent hydration, executor re-attach, shared acquires, chat notification order and queued messages for gateway chats. Read when: A sub-agent fails to open or a gateway chat loses its executor · Many sidebar requests reach unloaded chats at once · A prewarmed chat shows empty or message order looks wrong · Queued messages (Cmd+Enter) pause, resume or fail on a gateway turn API mode API mode: the Codex app runs its own signed engine and uses the gateway only as a model provider, so its app tools work on gateway models. Read when: A gateway model needs create_thread, automation_update or another codex_app tool · Choosing between the desktop adapter and API mode for one machine · Changing the native configuration API mode writes, or its register/unregister guard Client tool reachability Client tool discovery on gateway models, deferred-tool fallback, and the desktop scheduling boundary. Read when: Investigating a missing desktop tool or unavailable automation tool · Changing gateway SDK dynamic tool registration, tool search, or Code Mode · Testing client tool visibility after resume or model switching node_repl on gateway rows node_repl (browser, Chrome and computer use) on gateway rows: native evidence, how auto review runs in gateway executors, rules, model switching and the check script. Read when: Changing node_repl, auto review or guardian fields on gateway or native catalog rows · Changing the reviewer route, the auto_review catalog field or autoReview telemetry · Investigating why browser, Chrome or computer use is on or off in a gateway chat · Investigating a rejected model switch during a running turn Harness identity How gateway chats identify themselves to each harness: Codex records them as gatefox by default (subscription_gateway before 1.8.0, still read) and as openai on an opted-in Mac, Claude Code stores no provider, and the checklist for adding another harness. Read when: Changing which provider id gateway chats are saved with, or the chatIdentity setting · Changing the gateway SDK patch, the executor marker, or the executor launch settings · Investigating why a gateway chat is missing from the phone or the native chat list · Investigating "Model provider gatefox not found" or "Model provider subscription_gateway not found" when ChatGPT opens a chat · Adding a harness, or a client that lists or resumes gateway chats Compaction and model changes Compaction policy and model changes for gateway chats in the desktop adapter. Read when: Changing compaction overrides, context windows or model switching for gateway chats · Investigating compaction or a refused model switch in a gateway chat Processes and prediction forks How the desktop adapter forwards process requests and composer prediction forks on connected machines, and how throwaway chats stay memory-only. Read when: Changing how the adapter forwards process/*, thread/fork or ephemeral chats · Investigating rpc_error rejections from remote hosts Native Claude picker experiment Version-pinned, isolated experiment for Claude Desktop native reasoning metadata. Read when: Testing native reasoning or Fast controls for opaque Claude Desktop gateway routes. · Changing the isolated Claude app trial or its archive patch. Offline unread dots: guarded client candidate Guarded, version-pinned client candidate for offline unread receipts; not installed or window-verified. Read when: Investigating missing blue unread dots after laptop sleep or remote chat completion · Testing the experimental desktop unread receipt bridge

API providers Grok/xAI, OpenCode Console and Go, OpenRouter, and custom API connections behind GateFox. Read when: Connecting Grok, OpenCode or another API model service · Changing named API presets, upstream protocols or conversation headers Live Claude sessions Live Claude CLI sessions per client conversation: when they continue, reseed or fall back. Read when: Changing the Claude provider, its live sessions, relay or ledger · Turning claudeSessions on or off, or investigating Claude cache spend Live Copilot sessions Live Copilot CLI sessions per Codex thread (the default): why they exist, how requests continue, reseed or fall back, and what stays on disk. Read when: Changing the Copilot provider, its live sessions or its cleanup · Turning copilotSessions on or off, or investigating Copilot credit spend Grok subscription Grok subscription inference through the official Grok Build CLI: live ACP sessions per conversation, private Grok home, tool handoff, fail-closed checks and limits. Read when: Changing the grok-subscription provider, its live sessions or its Grok home · Turning grokSessions on or off, or investigating a refused Grok conversation · Signing the gateway in to Grok, or investigating a failed Grok request Automatic latest models Opt-in automatic updates for selected model families, bounded catalog polling and historical chat routes. Read when: Enabling or changing automatic latest-model selection. · Changing model discovery, family matching, timestamps or picker visibility. · Investigating the service's five-minute model refresh or a model that stayed disabled. Managed worker routing Opt-in code-enforced worker routes with fresh capacity checks, durable provider affinity and explicit context budgets. Read when: Configuring automatic worker model selection or fallback. · Investigating managed worker context budgets or provider affinity. Availability Read-only availability facts per provider: local model health, load, subscription quota and paid balance. Read when: Changing /v1/availability, gateway availability or the availability settings · Connecting Spendwatch quota or a local model server to availability reports · Investigating why a provider reports unknown, busy, limited or unavailable Upstream capacity discovery Opt-in runtime admission discovery from authenticated local inference capacity snapshots. Read when: Changing local worker concurrency or Gateway admission limits · Investigating Local AI busy status or stale capacity discovery · Adding or draining a local inference worker without editing every Gateway Large-context cache safety Shared cache-reuse safety stops for large contexts across every Gateway provider and client. Read when: Investigating subscription drain, repeated uncached contexts or a cache safety stop · Adding a provider, ingress protocol or partial usage observation Conversation reuse Provider session reuse, cache affinity, final replay refusals, and explicit unsupported paths. Read when: Auditing cache efficiency or unexpected subscription consumption across clients · Adding or changing a provider transport, CLI fallback, or conversation identity · Investigating a session_continuity_unavailable refusal Provider updates Local stable-provider maintenance: isolated candidates, generated Codex pins, CLI protocol checks, and safe source promotion. Read when: Updating Codex, Claude or Copilot compatibility · Changing SDK source pins, feature schemas or provider update scheduling · Investigating a blocked provider maintenance run Responses support Responses ingress overview and index: what the gateway translates, plus the anchors and links into the three Responses guide pages. Read when: Changing Responses request parsing, tools, replay, or SSE output · Looking for which Responses guide page covers a behavior Responses protocol, streaming, and failures Responses wire contract: collaboration transport, response ids, item replay, stream terminals, failure classes, retry budgets, capacity, and request hardening. Read when: Changing Responses SSE events, terminals, heartbeats, or failure classification · Debugging a stalled, retried, throttled, or rejected Responses request · Changing response ids, collaboration transport, cache-affinity headers, or service tiers Responses tools across routes Caller and hosted tools on Responses routes: Claude tool identity, Chat Completions tool-call shapes, repeated declarations, the tool search bridge, and hosted web search. Read when: Changing tool declarations, tool search bridging, or hosted tool forwarding · Debugging a garbled, duplicate, undeclared, or refused tool call · Adding a route that must drop or bridge a tool type Responses provider adapters and images Per-provider Responses behavior: Claude failures and CLI prompt cache, Codex subscription login refresh, Copilot live sessions, the Anthropic API route, and image inputs. Read when: Changing the Claude CLI adapter, its prompt cache, or its failure classes · Investigating a Codex login refresh, a Copilot cancellation, or an Anthropic API request · Changing image inputs, model modalities, or per-route image handling

Remote gateway Share one gateway catalog across trusted SSH-connected machines. Read when: Connecting a MacBook or remote Codex client to a gateway on another host Native connected machines Native connected-machine adapter using the existing Codex Desktop registration. Read when: Changing Control other devices transport or native relay installation · Testing models through existing connected machines · Investigating remote stalls, sequence gaps, or native relay logs Native relay setup and builds Install, activate and build the native connected-machine relay without replacing its registration. Read when: Installing or building the native relay Native relay troubleshooting Diagnose native relay sessions, stream ends, lost requests, transport counters and logs. Read when: Investigating native relay stream failures or reading its logs Sleep, travel, and reconnects Keep executor ownership separate from laptop connections, and adopt native sharing without interrupting active work. Read when: Investigating a chat that stops after laptop sleep, travel, or a network change · Enabling native executor sharing or testing disconnected clients

One managed service Inventory and consolidate gateway processes under one macOS service. Read when: Changing daemon ownership, restart, or service cleanup · Consolidating gateway jobs or retiring test services Service ownership and consolidation Keep one signed GateFox background item and consolidate only proven-owned legacy jobs. Read when: Changing service ownership and consolidation Shared chat and native execution Shared gateway executors, native-home ownership and hosted model maintenance. Read when: Changing shared chat and native execution Service updates and release adoption Live controller updates, safe release adoption, retained components and release-skew recovery. Read when: Changing service updates and release adoption Health watchdog The watchdog: gateway health verdicts, alert pushes, scheduled runs, and the compatibility smoke. Read when: Investigating a Discord alert from a gateway push monitor · Changing what the watchdog checks, when it pushes, or how it schedules Diagnostics Local telemetry, gateway diagnostics, and scrubbed exception reports to GlitchTip. Read when: Investigating stopped turns, failures, restarts or cache behavior · Changing what the gateway logs or reports Provider failures and cache diagnostics Read fixed provider failure categories, cache observations and Claude continuity diagnostics. Read when: Investigating provider failures and cache diagnostics Runtime and execution events Read telemetry, executor outcomes, subagent startup checks, relay state and service recovery events. Read when: Investigating runtime and execution events Usage ledger and loaded releases Interpret the private usage ledger, real loaded release versions and scrubbed exception reports. Read when: Investigating usage ledger and loaded releases Engine exits and stream recovery Why desktop-adapter engine exits and dropped engine frames are recorded, and what each event means. Read when: Investigating "The Codex engine stopped while this turn was running" or an unexplained engine restart · Investigating "Shared executor host connection was lost" or a chat that keeps failing until its computer connection reconnects · Changing how the adapter reads native or gateway engine streams or when it stops an engine Recovery after a reboot Automatic recovery of managed SSH and executor sockets after a Mac reboots. Read when: Investigating SSH connection refusals or socket ownership failures after a reboot · Changing recovery of managed SSH listeners or executor socket identities Legacy service installation recovery Bounded teardown checks before replacing or restoring a legacy standalone service. Read when: Changing legacy macOS service installation or rollback · Investigating a bootstrap failure while a previous service is still exiting One app identity in Login Items Attribute the existing macOS gateway startup job to the signed fox app without restarting it. Read when: Changing macOS Login Items, background attribution, or the signed service launcher · Signing or notarizing the native app macOS app updates Daily signed macOS app updates from standard GateFox GitHub releases. Read when: Changing the macOS app updater or app release assets · Investigating an unavailable, deferred, or rolled-back app update MCP credentials on an unattended Mac Prevent interactive MCP OAuth Keychain prompts on an unattended Mac. Read when: Investigating a gateway-codex prompt for Codex MCP Credentials · Configuring MCP authentication on a headless gateway host ChatGPT update compatibility Keep desktop startup and pinned gateway execution independent of ChatGPT app-engine updates. Read when: Investigating desktop startup failures after ChatGPT updates itself · Changing app-server invocation classification or native sharing admission · Verifying a new signed ChatGPT engine against the connector Legacy FORCE_CLI cleanup How the gateway removes the CODEX_APP_SERVER_FORCE_CLI value older releases exported. Read when: Upgrading a Mac from a gateway release that exported CODEX_APP_SERVER_FORCE_CLI · Debugging durable chats or SSH rows that run as local app-servers, or repeated 409 remote-control errors Native launcher verification Verify native ownership through the real desktop wrapper and the app launcher. Read when: Changing native engine path resolution or desktop wrapper generation · Investigating organization-settings startup errors after enabling shared native execution · Verifying desktop startup after a gateway service restart

Architecture Account routing, provider execution, live configuration, and desktop isolation. Read when: Changing account routing or configuration reload · Changing provider execution or desktop backend isolation Verification Verified subscription operations and remaining desktop checks. Read when: Testing subscriptions or remote clients · Assessing desktop readiness Transport and installer verification Connection recovery, native transports, direct tools, installers and SSH verification procedures. Read when: Reading historical transport and installer verification or choosing a matching verification script Desktop verification evidence Desktop settings and configuration checks, with their tested versions and remaining limits. Read when: Reading historical desktop verification evidence or choosing a matching verification script Subscription verification evidence Real subscription checks and recorded provider-specific verification limits. Read when: Reading historical subscription verification evidence or choosing a matching verification script Historical release evidence Version-specific release verification records and the limits of that evidence. Read when: Reading historical historical release evidence or choosing a matching verification script Release Build, verify, publish, install, and recover the Apple Silicon CLI release. Read when: Cutting a gateway release · Changing installation, desktop registration, or managed services Release validation checks Focused CLI, provider and desktop checks required before publishing a GateFox release. Read when: Preparing a release or choosing protocol and desktop verification scripts Rollout readiness Readiness evidence for an installed gateway release. Read when: Installing or publishing a gateway release · Investigating a stale desktop executor, missing tool runner, or failed chat resume Component origins How a release reuses two separately authenticated original component archives. Read when: Changing scripts/release-components.mjs or scripts/build-release.mjs reuse flags · Publishing a release that reuses the native relay or the gateway SDK · Debugging a gateway SDK that refuses to load after a component reuse · Changing the signed gateway executor selected for macOS Keychain access CI Manual-only hosted CI behind production opt-ins; local gates run every change. Read when: Changing CI runners or platform-specific tests · Checking the source validation gate CI cost policy Manual-only production opt-in CI for every hosted job to bound Actions spend. Read when: Changing GitHub Actions runners or release triggers. · Requesting a production build or investigating Actions charges. Availability and agent tasks Live agent task checks for availability consumption, local workers and subscription fallback. Read when: Testing whether an agent consults availability before choosing a worker · Changing availability client policy, worker roles or the live delegation check · Deciding whether a change is covered by these live checks or by the managed routing suites Gateway identity Gateway fox identity, documentation colors, and generated asset provenance. Read when: Changing the gateway logo or documentation design · Adding a surface that uses gateway brand assets Docs site How the gatefox.dev docs site is built from docs/ and published to GitHub Pages. Read when: Editing the guide, a doc page or the docs site builder · Publishing the docs site or changing its domain Roadmap Next steps for GateFox and where contributors can help: the Claude apps, DeepSeek, and more harnesses. Read when: Looking for something to work on in GateFox · Planning work on Claude Desktop or Claude Code support, DeepSeek, or a new client harness The GateFox rename Plan for 1.8.0: replace every Subscription Gateway and Harness Gateway name with GateFox, including the stored provider ID, without breaking installed Macs or saved chats. Read when: Working on the GateFox rename (1.8.0) · Changing a name that installed Macs, saved chats or the patched Codex SDK depend on

Changelog Published app releases, release notes and macOS downloads. Read when: Checking the latest published version or what changed