Codex Remote

A lightweight local HTTP bridge for controlling Codex from applications, scripts, and internal services.

Codex Remote runs beside the Codex desktop app and exposes a small authenticated API for starting tasks, streaming events, using Skills, and invoking Computer Use. It includes a native macOS menu bar app, a TypeScript CLI, and support for multiple isolated service profiles.

Highlights

• One primary endpoint: POST /v1/tasks
• Native macOS menu bar app built with Swift/AppKit
• Node.js and TypeScript service with no Electron dependency
• Multiple profiles with independent ports, API keys, workspaces, and logs
• Codex Skills, attachments, Computer Use, and full-control permission profiles
• Synchronous responses or asynchronous execution with SSE events
• Shared Codex app-server daemon, so API tasks can appear in Codex Desktop
• Built-in API documentation and OpenAPI schema

Architecture

Business service
      │
      │ HTTP / SSE
      ▼
Codex Remote Profile
      │
      │ JSON-RPC over WebSocket / Unix socket
      ▼
Local Codex app-server daemon
      │
      └── Codex Desktop

Each profile runs as a separate local service:

frontend  →  http://127.0.0.1:8787  →  ~/Projects/frontend
backend   →  http://127.0.0.1:8788  →  ~/Projects/backend
ops       →  http://127.0.0.1:8789  →  ~/Projects/infra

Requirements

• macOS 13 or later for the menu bar app
• ChatGPT/Codex installed and signed in on the same machine
• Node.js 20+ and pnpm for source development

The packaged macOS app includes the Node.js runtime required by the service. It does not bundle or copy Codex, Computer Use, or Codex plugins.

The first time desktop integration is enabled, Codex must restart so its process can connect to the shared daemon. The menu bar app detects this state and offers a safe restart action.

Quick Start

Install dependencies and run from source:

pnpm install
pnpm run build
pnpm cli -- profiles add default --workspace "$HOME/Documents"
pnpm cli -- start default

Read the generated API key:

pnpm cli -- token default

Send a task:

export CODEX_REMOTE_TOKEN='your-profile-api-key'

curl -X POST http://127.0.0.1:8787/v1/tasks \
  -H "Authorization: Bearer $CODEX_REMOTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instruction": "Inspect this project, fix the failing tests, and summarize the changes."
  }'

By default, the request waits for Codex and returns the final output. Set "wait": false for long-running tasks.

Skills and Computer Use

Skills are passed to Codex as structured skill inputs:

curl -X POST http://127.0.0.1:8787/v1/tasks \
  -H "Authorization: Bearer $CODEX_REMOTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instruction": "Open Chrome and navigate to the requested website.",
    "skills": ["chrome:control-chrome"],
    "permissions": "full-control"
  }'

Computer Use can be requested explicitly:

{
  "instruction": "Inspect the currently running Mac applications.",
  "skills": ["computer-use"],
  "computerUse": true,
  "permissions": "full-control"
}

Query the capabilities exposed by the installed Codex version:

curl http://127.0.0.1:8787/v1/capabilities \
  -H "Authorization: Bearer $CODEX_REMOTE_TOKEN"

Task Options

POST /v1/tasks accepts:

Field	Description
instruction	Required natural-language task
workspace	Working directory within the profile's allowed roots
developerInstructions	Additional developer guidance
model	Optional model override
effort	Reasoning effort such as medium, high, or xhigh
skills	Enabled Codex Skill names
attachments	Remote images, local images, or local files
computerUse	Enable the installed Computer Use capability
permissions	read-only, workspace-write, or full-control
wait	Wait for completion; defaults to true
timeoutSeconds	Synchronous wait timeout

CLI and Profiles

codex-remote profiles add frontend --workspace "$HOME/Projects/frontend"
codex-remote profiles add backend --workspace "$HOME/Projects/backend" --port 8800

codex-remote profiles list
codex-remote start --enabled
codex-remote status --json
codex-remote stop --all

Profile data is stored at:

~/Library/Application Support/Codex Remote/profiles.json

The profile document is owner-readable only (0600). Each profile has a unique API key and can independently enable LAN access, Computer Use, and full-control permissions.

API

Method	Path	Purpose
GET	/health	Service and Codex readiness
GET	/docs	Built-in usage guide
GET	/openapi.json	OpenAPI schema
POST	/v1/tasks	Start a complete Codex task
GET	/v1/capabilities	Skills and permission capabilities
GET	/v1/events	Stream Codex events over SSE
GET	/v1/threads	List threads
POST	/v1/threads	Create a thread
GET	/v1/threads/:threadId	Read a thread
POST	/v1/threads/:threadId/turns	Start a turn
POST	/v1/threads/:threadId/interrupt	Interrupt a turn

Advanced API documentation is available from every running profile:

http://127.0.0.1:8787/docs

macOS App

Build the native menu bar app:

pnpm run package:mac:app

Build a DMG:

pnpm run package:mac:dmg

DMG builds recreate the app from the current source by default. Reusing a previously verified app requires an explicit path:

REUSE_APP_PATH="/absolute/path/Codex Remote.app" pnpm run package:mac:dmg

Public distribution should use a Developer ID certificate and Apple notarization:

CODE_SIGN_IDENTITY='Developer ID Application: Example (TEAMID)' \
NOTARY_PROFILE='notarytool-keychain-profile' \
pnpm run package:mac:dmg

Security

• Profiles listen on 127.0.0.1 by default.
• Every /v1 route requires a Bearer API key.
• /health, /docs, and /openapi.json remain public.
• Workspaces and local attachments are restricted to configured roots.
• Ordinary tasks default to workspace-write.
• Computer Use and full-control must be explicitly requested per task and can be disabled per profile.
• Put the service behind TLS, rate limiting, and an audited gateway before exposing it beyond a trusted network.

Development

pnpm run typecheck
pnpm test
pnpm run build

Protocol types are generated from the installed Codex CLI:

pnpm run generate:protocol