Grok Codex Gateway

Ask a Bot in the Grok Bot app to work on a project on your Mac, and let Codex carry out the task in that project's directory. This gateway connects the conversation to the local Codex command-line program, tracks the task, and returns its result to the Bot.

For example, you can ask:

Review the uncommitted changes in example-app. Use Codex, report any bugs, and do not edit files.

The Bot finds the project through the gateway, starts a read-only Codex job, and brings the findings back to your conversation. You can then ask a followup in the same Codex session.

The gateway and Codex process run on your Mac; model inference uses the corresponding online service. Each new task starts a separate Codex session. Followups resume sessions created through the gateway; they do not insert messages into an already-open Codex or ChatGPT UI conversation.

The pieces involved

The Codex proxy is the gateway's on/off switch for delegating project tasks to Codex. When it is disabled, the Bot can instead work through Grok's approved local Shell, which runs commands on your Mac. That fallback is chosen by the Bot; the gateway does not execute it.

Related MCP server: webgpt MCP

Quick start

1. Prepare the local tools

You need macOS/POSIX, nvm, and an installed, authenticated codex CLI. The project pins its Node.js version in .nvmrc. Sign in to Codex locally using its supported login flow before requesting Codex work.

Run these commands from this checkout:

source "$HOME/.nvm/nvm.sh"
nvm install
nvm use
npm ci
npm run setup

Setup creates two private files outside the source checkout:

Setup does not replace existing files or print the token. It creates the files with mode 0600, meaning only their owner can read or write them. Keep credentials and private configuration outside Git. GATEWAY_CONFIG_DIR can select a different private configuration directory outside a repository.

2. Check which projects are available

The initial configuration searches your home directory. For a smaller search, edit roots in the private config.json to point to your project directories, for example ["~/work"].

npm run projects

This prints the eligible projects, their IDs, and discovery warnings. A project needs its own AGENTS.md or a matching Ganglia project entry. Project discovery explains both routes; Ganglia is optional.

3. Start the gateway

In the same Terminal window:

caffeinate -dimsu npm start

Leave this running. caffeinate keeps the Mac awake while the gateway runs; Control-C stops it. The default MCP endpoint is:

http://127.0.0.1:8765/mcp

4. Connect Grok Bot from this Mac

Enable Execution on Local Computer in Settings → General → Bot. For accounts with registered computers, this setting moves to Settings → Computer → Computers → Execution on this computer. Shell execution follows your local-computer approval policy and any stricter team policy. See Grok's local-computer permissions.

The Bot's approved local Shell must use an MCP client to call the endpoint above. The client reads mcp.token from its private file at call time and sends its contents in the Authorization: Bearer … header. It must keep the token out of command output, chat, and saved task files. This repository provides the server; it does not install a Grok plugin or a local client command.

Verify the connection with MCP initialize, tools/list, and a harmless projects_list call. A health check alone does not verify authentication or tool access.

Because the Shell and gateway run on the same Mac, this route needs no tunnel. Grok's cloud connector cannot reach your Mac's localhost; use the optional remote connection if the caller cannot run local Shell commands.

Worked example: review a local project

Suppose your project is at ~/work/example-app, it contains an AGENTS.md, and ~/work is one of your configured roots. Ask the Bot:

Review the uncommitted changes in example-app. Use Codex, report any bugs, and do not edit files.

The following JSON blocks are MCP tool arguments, not shell commands. The Bot sends them through its MCP client.

1. Call proxy_status with {} to check whether Codex delegation is enabled.

2. Call projects_list with {}. Find example-app in the returned projects array and use its id. The gateway supplies the path; the start request takes an ID, never a filesystem path.

3. Call codex_start, replacing the project placeholder with that returned ID:

{
  "project": "PROJECT_ID_FROM_PROJECTS_LIST",
  "prompt": "Review the uncommitted changes and report bugs with file references. Follow AGENTS.md. Do not edit files.",
  "mode": "read-only",
  "requestId": "review-example-001"
}

The gateway checks the project's eligibility and returns a jobId with state queued. When its turn arrives, it checks eligibility again and runs Codex in that project directory.

4. Call job_status with the returned job ID to check progress:

{
  "jobId": "JOB_ID_FROM_CODEX_START"
}

Once the state is completed, call job_result with the same arguments. Its result contains Codex's final text, which the Bot presents in your conversation. If the state is failed, cancelled, or timed_out, report that state and any error instead of claiming success.

5. To continue a completed, retained Codex job, call codex_followup:

{
  "jobId": "JOB_ID_FROM_CODEX_START",
  "prompt": "Explain the highest-impact finding and suggest a fix. Do not edit files.",
  "requestId": "review-example-002"
}

A followup returns a new job ID while retaining the original project's Codex session and sandbox mode. Check its status and result in the same way. To move from review to editing, start a new job with the appropriate write mode and explicit permission to edit.

Every start or followup needs a requestId. Retrying the identical request with the same ID returns the existing job while it is retained. Reusing that ID for different arguments is rejected. Use a new ID for intentional new work.

Project discovery

Configured roots are the directories the gateway is allowed to search for projects. A directory under a root becomes eligible through either of the following routes.

Discovery through AGENTS.md

A project's own AGENTS.md identifies it as a project. If the file is inside a Git checkout, discovery lists the nearest containing checkout. Codex still applies nested instructions only in their respective file scopes.

For example:

~/work/
└── example-app/
    ├── .git/
    ├── AGENTS.md
    └── src/

With "roots": ["~/work"], this project can appear in projects_list without Ganglia. A home-level AGENTS.md supplies global guidance; it does not enroll every directory in your home folder.

Optional discovery through Ganglia

Ganglia is a portable knowledge store made of Markdown files for AI agents. It keeps reusable lessons and decisions across projects, with private project notes under local/projects/. Its separately installed $remember skill saves knowledge, and $recall searches it. A skill is a set of instructions an agent follows to perform a task. See Ganglia's README for its setup and privacy boundaries; this gateway does not bundle or install it.

Ganglia provides a second way to identify projects, including projects without their own AGENTS.md. Consider this illustrative layout:

~/work/
└── example-app/                         Project source directory
    ├── .git/
    └── src/

~/ganglia/
└── local/
    └── projects/
        └── example/                    Ganglia project entry
            └── decisions.md            An existing Markdown knowledge file

Here, example is the project slug: the folder name used for that project's knowledge. It differs from the source directory name, example-app, so an explicit mapping connects them. Merge these values into the private config.json:

{
  "roots": ["~/work"],
  "gangliaRoot": "~/ganglia",
  "gangliaMappings": {
    "example": "~/work/example-app"
  }
}

gangliaRoot locates the knowledge store. gangliaMappings maps a knowledge folder's slug to its actual project directory. The mapping is valid only if the Ganglia entry contains an existing Markdown knowledge file and the target is a real, permitted directory under roots. A mapping alone does not create or enroll a project.

Without a mapping, discovery tries to match the slug to a Git checkout with the same directory name or a directory directly under a root. A container with one uniquely identifiable nested Git checkout can resolve to that checkout. Multiple possible matches require an explicit mapping. Entries containing only session transcripts or checkpoints do not qualify.

Discovery checks names and file metadata; it does not read the note text. In this example, the presence of decisions.md can establish eligibility, but its contents are not sent to the Bot or injected into Codex. To retrieve past decisions, Codex must use the installed $recall skill as a separate action. The gateway never writes to Ganglia or reads raw archives, credentials, or transcripts during discovery. Another system's memory index alone does not enroll projects.

If Ganglia is absent, AGENTS.md discovery still works; the project listing reports a Ganglia availability warning.

Search limits and validation

Hidden, dependency, build, raw-archive, and system directories are skipped. Symlinked project paths are rejected. Discovery scans breadth-first, with limits of 10,000 directories, 5,000 entries per directory, and the configured depth. Warnings report incomplete searches; use narrower roots to reach projects beyond a limit.

Project names and paths are returned only to authenticated MCP callers. The gateway validates eligibility when accepting a task and again before starting its worker.

Sandbox modes and permissions

A sandbox mode controls what the Codex job is allowed to do. Select it when starting the task:

workspace-write-git uses Codex's workspace-write sandbox, explicitly adds the selected project and its .git directory as writable roots, and enables outbound network access for that job. Only this mode receives the gateway's SSH_AUTH_SOCK, when set, so Git can use its SSH agent. Followups retain their selected mode.

Codex keeps its login, user/project configuration, AGENTS.md instructions, and execution rules. The gateway sets approval_policy="never": operations needing additional approval are denied. A request's write mode does not authorize a commit, deployment, or other action beyond the user's task. Perform approval-dependent work through an interactive local Codex session.

The gateway offers no full-access mode or arbitrary shell-command tool. Trusted Codex MCP integrations have their own permissions; the CLI filesystem sandbox does not govern every external tool. The listener binds only to 127.0.0.1, checks Host and Origin, and requires bearer authentication for MCP. All token holders share the same jobs and account access: this is a service for one trusted owner, not a multi-user service.

Codex proxy switch and direct Shell fallback

Read proxy_status to see enabled, the selected execution backend, and manual-only credit detection. Use proxy_set_enabled with:

{"enabled": false}

This stops accepting new Codex starts and followups. The Bot should then use Grok's approved local Shell directly in the selected project, following its AGENTS.md and the user's authorization. Switching does not launch Shell work or cancel accepted jobs. Queued and running jobs continue; retries of accepted requests, status, results, and cancellation remain available.

Call the same tool with {"enabled": true} to resume delegation. projects_list.backends.codex reflects the switch. Changes take effect without restart and persist in owner-only proxy-state.json beside the private configuration. Missing state defaults to enabled; invalid or unreadable state blocks startup. A failed persistence write leaves the current mode unchanged and returns an error.

The gateway cannot read subscription balances or reliably detect exhausted credits. Rate limits, network failures, login problems, and credit exhaustion can produce indistinguishable CLI errors. Check your account separately and switch manually when needed.

Suggested saved Bot instructions:

Check the Codex proxy status before project work. When enabled, use the local MCP gateway to discover the project, delegate to Codex, and retrieve the result. When disabled, use approved local Shell execution in the discovered project directory. Follow that project's AGENTS.md, preserve project eligibility checks and user authorization, and obtain Shell approval as required. Use the local endpoint without a tunnel. Read the bearer token from its private file at call time and never print or paste it into chat.

The gateway cannot change Grok account settings, save these instructions for you, or grant local Shell permission. If Codex is unavailable, switch the proxy off explicitly; there is no automatic failover.

Configuration reference

This is an example of the supported configuration keys with their default values. Setup omits maxDepth and codexBin; loading the configuration supplies those defaults.

{
  "roots": ["~"],
  "gangliaRoot": "~/ganglia",
  "gangliaMappings": {},
  "maxDepth": 6,
  "port": 8765,
  "allowedHosts": [],
  "allowedOrigins": [],
  "codexBin": "codex",
  "jobTimeoutMinutes": 30
}

Restart the gateway after editing config.json. Proxy switching is the exception: use its MCP tool without restarting.

MCP tool reference

One worker runs at a time across all projects and both backends. Up to 10 unfinished jobs are accepted, and up to 100 jobs are retained, with finished jobs removed first when capacity is needed. Prompts are limited to 32,000 characters, HTTP bodies to 128 KiB, and worker output to 1 MiB. Cancellation waits for the worker to close and terminates its process group; it does not undo edits already made.

Jobs and retry records live in memory. Restarting loses them, and graceful shutdown cancels unfinished work. Codex's own sessions may remain on disk under its retention policy, but the gateway does not replay lost jobs or adopt arbitrary existing sessions.

Optional OpenAI text backend

For standalone text requests, set openaiModel to a model available to your API account and supply OPENAI_API_KEY through the gateway process's local environment or secret manager. Restart after configuring it, then use openai_start and the usual job status/result tools.

This backend calls the OpenAI Responses API with store: false, no tools, no automatic retries, and a 4096-token output ceiling. It receives the prompt, not project files. It works independently of the Codex proxy switch, and its API key is not passed to Codex's child process.

API access and billing are separate from the Codex worker's login. The gateway does not read browser cookies, borrow a ChatGPT UI conversation, or implement the optional Sign in with ChatGPT OAuth integration.

Optional remote connection

Use a tunnel when the caller runs remotely and cannot use local Shell. A tunnel forwards a public HTTPS address to the gateway's local port. Grok's cloud connector cannot directly reach loopback or private-network addresses; see Grok's MCP tunneling documentation.

For example, after installing and configuring ngrok separately:

ngrok http 8765

Then:

1. Add the tunnel's actual Host to allowedHosts, without a scheme or path. Include a port only if the request's Host contains it.

2. If the client sends Origin, add its exact scheme, host, and port to allowedOrigins. Restart the gateway.

3. Set the remote MCP connector URL to https://YOUR_TUNNEL_HOST/mcp.

4. Configure bearer authentication through the client's secret/credential field, using the contents of mcp.token. Keep the token out of URLs, prompts, documentation, and Git.

5. Verify initialize, tools/list, and projects_list through the public endpoint. Keep the Mac, gateway, and tunnel running.

Use exact hosts and origins; do not disable authentication or use wildcards. This server uses a static bearer token rather than OAuth. A client that only supports OAuth needs an appropriate authenticating proxy. Custom remote MCP plugin access remains subject to Grok account and team policy.

Architecture

The two connection routes reach the same local server. Direct Shell fallback bypasses the gateway worker; OpenAI text is a separate backend.

flowchart TD
  you["You"] --> bot["Bot conversation in Grok Bot"]
  bot --> cloud["Grok Bot cloud computer"]
  cloud -->|"local execution enabled and approved"| shell["Local Shell on your Mac"]
  cloud -->|"optional remote MCP connector"| tunnel["Public HTTPS tunnel"]
  shell -->|"authenticated MCP calls"| gw["Gateway on 127.0.0.1:8765"]
  tunnel -->|"authenticated MCP calls"| gw

  gw --> choice{"Codex proxy enabled?"}
  choice -->|"yes: projects_list, codex_start / followup"| queue["One-worker job queue"]
  queue --> codex["Codex CLI in selected project"]
  codex --> project["Project files, AGENTS.md, selected sandbox"]
  project --> result["job_status and job_result"]
  result --> bot

  choice -.->|"no: Bot chooses approved Shell"| direct["Local Shell in selected project"]
  direct --> bot
  gw -->|"openai_start, independent of switch"| responses["OpenAI Responses API"]
  responses --> result

Verification

source "$HOME/.nvm/nvm.sh"
nvm use
npm run check
npm audit --include=dev

Tests cover authenticated MCP exchanges, project eligibility, retry deduplication, serialized jobs, cancellation and timeout, proxy switching, child-process boundaries, and mocked OpenAI requests. They use fixture projects and workers; they do not spend API credits, read real credentials, or inspect real project contents. Live model execution and access from a particular Grok account require separate verification.

License and credits

Original source, tests, and documentation in this repository are copyright 2026 Gezim Musliaj and licensed under the Apache License, Version 2.0. See LICENSE, NOTICE, and CREDITS.md for the terms and attribution for the author and every pinned third-party package.

Third-party packages retain the licenses in their own distributions. These files do not grant rights in Codex, Grok Bot, OpenAI, or their names.

Official integration references

• Grok Bot computer and local execution

• Grok Bot approvals and local-computer permissions

• Grok Bot custom MCP plugins

• Grok local MCP tunneling

• xAI API remote MCP

• OpenAI text generation and Responses

• Codex app-server and Sign in with ChatGPT integration

• Official MCP TypeScript SDK