# 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](https://github.com/itsthecsguy/claude-remote).

**Current state:** Quick-tunnel installer and eight tools; privacy and documentation review completed. See the [review record](docs/jobs/2026-11-04-privacy-readme.md).

## 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.

## Install

```bash
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:

```bash
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.

```bash
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:

| Setting | Value |
| --- | --- |
| Server URL | `https://<tunnel>.trycloudflare.com/mcp` — use the URL from `node src/index.js status` |
| Auth header | `Authorization: Bearer <token>` — replace the placeholder with the token file's single line |
| Transport | HTTP JSON-RPC; requests return JSON, notifications return an empty HTTP 202; no SSE stream |

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](findings.md).

## Tools

| Tool | Purpose | Available when |
| --- | --- | --- |
| `list_sessions` | Session IDs, project paths, first-prompt titles, activity and status | Always |
| `get_session` | Session status, final answer and recent assistant messages | Always |
| `continue_command` | Return a local `codex resume` command without running it | Always |
| `new_session` | Start a headless task from `cwd` and `prompt` | `--allow-launch` |
| `send_followup` | Resume a session with a prompt; requires `confirm: true` | `--allow-send` |
| `get_result` | Read a run ticket's status and result | Either flag |
| `queue_status` | List recent runs or inspect one ticket | Either flag |
| `stop_session` | Stop a run started by this helper | Either flag |

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

```bash
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](LICENSE).