codex-remote

List Codex CLI sessions on your Mac, start tasks in local projects, and read results from a remote MCP client such as Grok Bot. A small HTTP helper listens on 127.0.0.1:47322; a Cloudflare quick tunnel provides HTTPS access protected by a bearer token.

Unofficial community project. Not affiliated with, endorsed by, or supported by OpenAI. Inspired by claude-remote.

Current state: Quick-tunnel installer and eight tools; privacy and documentation review completed. See the review record.

Requirements

• Node.js 20 or newer; no npm dependencies or build step.

• macOS for the LaunchAgent installer.

• Codex CLI on your shell's PATH (or CODEX_REMOTE_CODEX_BIN), signed in for running tasks.

• cloudflared, or Homebrew so the installer can install it.

• An MCP client supporting HTTP JSON-RPC and a bearer auth header.

Related MCP server: wingman

Install

git clone https://github.com/artisbisers/codex-remote.git
cd codex-remote
node src/index.js install --dry-run   # preview; writes nothing
node src/index.js install             # session browsing only
node src/index.js status

To enable starting tasks and sending follow-ups, run:

node src/index.js install --allow-launch --allow-send

Run installation from the shell where Node and Codex are available. It pins their absolute paths and creates two LaunchAgents, com.codex-remote.http and com.codex-remote.tunnel, under ~/Library/LaunchAgents/. Both start at login and use KeepAlive. Reinstalling keeps the token and leaves an unchanged, loaded tunnel running. Pass the desired capability flags each time you install.

The default port is 47322. Override it with --port=47322 on install or http, or with CODEX_REMOTE_HTTP_PORT. For foreground debugging, run node src/index.js http with a token already created; this uses the current shell's environment flags rather than the LaunchAgent's settings.

Auth token

install creates ~/.codex-remote/http/token if missing. install and status print its path, never its value. Read the single-line value locally and enter it only in your connector's private auth configuration.

node src/index.js rotate-token

Rotation takes effect on the next request without restarting the helper. Update the connector's stored token afterwards. The token file uses mode 0600; runtime directories use 0700.

MCP client setup — Grok Bot

In Grok Bot's custom connector configuration, supply:

Connect and refresh the tool list after changing capability flags. Try list_sessions first. Enabled task tools return a ticket; poll get_result until its status is done, failed or stopped.

Quick-tunnel URLs change when the tunnel restarts, including after a reboot. Run status again and update the connector URL. Status reads the last URL from the log; it does not test that public endpoint. The Mac must be awake, online and logged in. Named tunnels, fixed hostnames and a watchdog are roadmap ideas, not implemented features. See troubleshooting.

Tools

The install flags set CODEX_REMOTE_ALLOW_LAUNCH=1 and CODEX_REMOTE_ALLOW_SEND=1 for the helper. Set those variables yourself for foreground mode. Task options include model, reasoningEffort, sandbox and skipGitRepoCheck; new_session also accepts worktree. These are passed to the installed Codex CLI, which must support the requested options. waitMs controls only how long the helper waits for the session ID before returning (default 10 seconds).

Safety

• Launch and follow-up tools default to off. Sandbox choices are workspace-write (default) and read-only; sandbox/approval bypass flags are refused. Commands use argument arrays, not a shell, and prompts go through stdin.

• The listener binds only to loopback, checks Host and Origin headers, and requires a bearer token. The tunnel rewrites Host to 127.0.0.1:47322 (or the selected port). A client forwarding a non-local Origin will be rejected.

• Anyone with the URL and token can read exposed session data, including local paths, prompt-derived titles and assistant messages. With task flags enabled, they can run tasks with your Codex access. Only connect trusted clients.

• Session discovery reads ${CODEX_HOME:-~/.codex}/sessions. The helper does not open auth.json or config.toml; the Codex CLI uses its own auth and configuration when executing tasks.

• Set CODEX_REMOTE_ALLOWED_ROOTS=/Users/me/code:/Users/me/work before installing to restrict the folders accepted by new_session. This does not filter session browsing or restrict send_followup to those roots.

• Run events, results and stderr live under ~/.codex-remote/runs/ and may contain sensitive content. Old, inactive runs are cleaned up on helper startup after seven days. Keep runtime files, tokens, status output and raw diagnosis logs out of commits. .gitignore covers copies inside this checkout; the actual home runtime directory lives outside it.

Projects under Desktop, Documents, Downloads or iCloud Drive may need macOS privacy permissions for the LaunchAgent's Node/Codex processes. A folder such as ~/code avoids those protected locations.

Uninstall

node src/index.js uninstall --dry-run  # preview
node src/index.js uninstall            # remove agents, token, port file and tunnel log

Normal uninstall keeps run history. To also remove the entire ~/.codex-remote/ runtime directory, use node src/index.js uninstall --purge. The repository and Codex CLI installation remain in place.

Development

Run npm test. The smoke test uses a temporary home and does not require Codex or Cloudflare. No application behavior changed in the privacy/documentation cleanup.

License

MIT.