This independent repository owns the Apple Silicon Runtime CLI, release assembly, compatibility manifest, installation tests, and Homebrew metadata update flow. It consumes versioned outputs from the independent Relay Server, Mac Agent, and Mobile Web repositories; it does not import their source.
Runtime 0.2.0-beta.10 uses one
com.codex-remote.runtime LaunchAgent. Its Supervisor manages isolated
PostgreSQL 17, bundled Valkey 9.1.1, Relay, Mac Agent, and Gateway with dynamic ports,
doctor --json, Mac Agent connectivity, and QR generation. Developer ID
signing and Apple notarization remain deferred to a later stable release.
Beta 10 keeps the Beta 4 bounded restart barrier and prints a styled terminal
QR plus a copyable one-time pairing URL after pair, start, and restart.
PNG output remains an explicit override. Do not publish a Formula that points
to a local file:// URL or describe a version as available until every Beta
release gate below has passed.
The additive dev-supervisor command reuses the release Supervisor process
ownership and readiness/failure behavior for a source-worktree stack. It is
not part of the installed Runtime setup and does not touch the release
com.codex-remote.runtime LaunchAgent or its state directory. mobile-web
builds this binary as bin/codex-remote-dev-supervisor and runs it under the
isolated com.codexremote.runtime.dev LaunchAgent for devrun crweb.
Development Supervisor currently manages the source-built Relay, Mac Agent,
and Mobile Web Gateway while using the existing isolated development
PostgreSQL/Valkey endpoints. Vite test, codex, and poll entries remain
direct frontend-development launchers and are not children of this Supervisor.
The published third-party Tap installation is:
brew trust --formula codex-remote/tap/codex-remote
brew install codex-remote/tap/codex-remote
codex-remote setup --workspace-root ~/work
codex-remote pairBy default, codex-remote pair prints the complete terminal QR and the
copyable pairing URL. The same terminal QR and URL are emitted after
codex-remote start and codex-remote restart. Use --terminal=false --output PATH explicitly when a PNG is preferred.
The Runtime keeps Relay, Auth Control, PostgreSQL, Valkey, Mac Agent, Codex, and project files on the Mac. Its Gateway can advertise either of two access origins without moving data or restarting the stack:
# Same trusted local network. This remains the default for existing installs.
codex-remote network lan
# Private Tailscale network, for access away from home or office.
codex-remote network tailscaleTailscale mode requires the official macOS Tailscale client to be installed,
connected, and signed in. The CLI finds either tailscale in PATH or the
executable bundled in /Applications/Tailscale.app. Pairing defaults to the
Mac's stable MagicDNS short name and can fall back to its Tailnet IPv4 address.
codex-remote status --json
codex-remote doctor --json
codex-remote pair --network tailscale
codex-remote pair --network tailscale --address ipThe pairing command verifies that at least one iPhone or iPad is online in the
same Tailnet. It automatically selects the only online iOS device. If several
are online, an interactive terminal presents a numbered choice; scripts must
use --device NAME_OR_IP. The selection names and confirms the intended
client, while the one-time Runtime pairing grant remains the authorization
boundary and is not cryptographically bound to the Tailscale device.
Changing the mode changes the advertised URL and newly generated pairing links. Devices paired through a different origin must pair again because browser cookies, IndexedDB, and native credentials are scoped to that origin. The Gateway still listens on the configured host port so LAN access remains a recovery path; Tailscale access control should restrict the Gateway port to the owner's devices. Tailscale Funnel and public router port forwarding are not supported access modes.
Homebrew 6 requires explicit trust before loading a non-official Formula. This security decision cannot be embedded in the Formula itself. Homebrew versions without Tap Trust ignore the extra command.
After the Tap has been registered, upgrades and reinstalls use the short name:
brew upgrade codex-remote
brew reinstall codex-remoteA bare brew install codex-remote on a clean Mac is a later official Homebrew
distribution milestone. Until then, users must trust and install the
third-party Tap Formula once; short-name upgrades then work on that machine.
brew install installs immutable Runtime files plus postgresql@17. The
Runtime archive contains a pinned, non-TLS Valkey executable used only on
loopback, avoiding Homebrew's redis/valkey binary conflict. Installation
does not inspect Codex, initialize databases, allocate ports,
write credentials, or start services.
codex-remote setup performs those per-user operations. It validates Codex
with a real App Server stdio handshake, creates isolated data directories,
stores random credentials in macOS Keychain, selects and persists free ports,
writes user LaunchAgents, runs the first database initialization, starts the
stack, checks health, and prints the LAN address.
Existing PostgreSQL, Redis, or Valkey instances are left untouched. Codex Remote uses
its own data directory and picks another port if a preferred port is occupied.
After setup, a saved Gateway port is never silently changed by repair or
upgrade; doctor reports the conflicting process instead.
make test vet
make notices
make assemble VERSION=0.2.0-beta.10 CHANNEL=beta
./scripts/update-formula.sh \
0.2.0-beta.10 \
dist/codex-remote-runtime-0.2.0-beta.10-darwin-arm64.tar.gz \
../homebrew-tapThe Beta gate requires the Apache-2.0 source license and NOTICE, generated third-party licenses, immutable component tags, a GitHub prerelease, clean-Mac Homebrew install/upgrade/rollback tests, and true-device pairing acceptance. The stable gate additionally requires Developer ID signing and Apple notarization.
Source code and future Runtime artifacts are licensed under the
Apache License 2.0. See NOTICE for attribution and project
name guidance. The already published 0.2.0-beta.1 through 0.2.0-beta.3
archives retain the historical license embedded in those immutable artifacts.
Codex Remote is an independent open-source project and is not affiliated with or endorsed by OpenAI. Codex and OpenAI are trademarks of their respective owners.