Codex Remote

Product Introduction

1. Definition: Codex Remote (https://codexremote.io) is an open-source macOS menu bar application and AI agent infrastructure automation tool that provisions cloud virtual machines and configures them as remote development environments for OpenAI Codex CLI and Anthropic Claude Code. It combines OpenTofu-based infrastructure-as-code provisioning, SSH host registration, systemd service orchestration, MCP server synchronization, and lifecycle monitoring into a single native menu bar interface. Technical category: macOS menu bar utility, cloud provisioning orchestrator, remote AI coding agent deployment tool, and multi-cloud remote dev environment manager.
2. Core Value Proposition: Codex Remote exists to eliminate the repetitive, error-prone manual work required to run Codex or Claude Code on a cloud machine you control. It lets developers choose a cloud provider and size, then automatically provisions the server, installs the agents, carries over MCP servers, syncs projects, and connects the machine to the apps already used. Primary keywords: remote Codex, Claude Code remote machine, cloud AI coding agent, macOS menu bar app, OpenTofu provisioning, no hosted middleman, local cloud credentials, open-source AI agent infrastructure.

Main Features

1. Multi-Cloud Provisioning with OpenTofu: Users add a token for Hetzner, AWS, DigitalOcean, Linode, Vultr, or Scaleway. The token is stored in the macOS login keychain, never in a file or OpenTofu state. When creating a new machine, the app applies a small per-cloud OpenTofu module, creates one VM with the user's SSH key, and assigns each machine its own state file so one machine can never disturb another. An estimated price appears beside Create before the user confirms. The HCL module receives name, region, size, image, ssh_public_key, ssh_key_ids, user_data, and tags, and must declare at least instance_id and public_ipv4 so the machine is reachable.
2. Automated Bootstrap and Systemd Service Orchestration: Over SSH, Codex Remote installs base packages, the Codex CLI at /usr/local/bin/codex, Claude Code under its own claude account with its own login, MCP servers, and a systemd unit for each agent. First-run wizards are pre-answered so they do not block forever under a service manager. Units are enabled at boot and share the prefix codex-remote-, so systemctl status 'codex-remote-' shows the whole stack. A stop and start brings all agent services back, which solves reboot and laptop-lid session loss for long-running AI coding sessions.
3. SSH Host Registration and Codex App-Server Integration: The app writes an inline Host codex-remote- block into the user's SSH config, placed above Host * so first-match rules cannot override it. The block sits inside markers so it can be cleanly removed again. This is how the Codex app finds a machine and starts codex app-server on it over SSH. Claude Code dials out and appears in the user's account. Pair it once and the cloud box can answer from a phone as well.
4. Project Sync and MCP Server Migration: The codex-remote push command clones or copies a local project to the remote machine, then sends untracked configuration separately, including gitignored .env files. Portable MCP servers come across with the project. This ensures the code is present and the project has the runtime secrets and tool connections needed to actually run, rather than arriving as a clone that fails because local configuration was left behind.
5. Agent-Driven Machine Management via MCP: Users can run claude mcp add codex-remote -- codex-remote mcp serve to expose Codex Remote tools to an AI agent. Read-only tools include list_machines for health, running sessions, CPU, and memory, plus list_sizes for regions, sizes, images, and prices. Changing tools include run_command, sync_project, and create_machine. Destroying has its own switch. destroy_machine requires the machine's name twice, so a model-generated but unverified name fails instead of deleting something real.
6. Runtime Provider Registry with Pinned HCL: The cloud provider catalogue is a JSON file fetched at runtime from codexremote.io/registry.json, so adding a cloud provider is a pull request rather than a new app release. Users can point Settings → Providers at their own registry for a homelab, an internal cloud, or a fork with custom packages and volumes. HCL can live in its own .tf file pinned to a SHA-256 hash. That hash matters because the HCL runs against cloud credentials, and without it whoever serves the URL could change what gets applied long after the registry was read. A Swift test filter validates the shipped registry so malformed entries fail locally rather than in review.
7. Security, Monitoring, and Lifecycle Controls: Cloud credentials stay in the macOS login keychain and never go to a file or OpenTofu state. There is no hosted middleman. The menu bar app lists every machine across clouds and shows whether a machine is paused, idle, or running agent sessions, so users can see whether stopping it would interrupt work. It displays CPU, memory, and active sessions, and supports pausing idle servers, syncing a project, or letting an agent manage machines with opt-in MCP access. The product is open source and independent of OpenAI and Anthropic.

Problems Solved

1. Pain Point: Fragile SSH Configuration for Codex: Codex parses SSH config with a library that never expands Include directives. A host behind an Include is invisible, and nothing explains why. Codex Remote writes the host block inline where it is read, above Host *, so first-match cannot override it, and uses markers so it can be removed without manual cleanup.
2. Pain Point: Blocking OAuth and First-Run Wizards: Manual setup requires installing Node, installing the CLI, completing an OAuth round trip, and answering a first-run prompt that blocks forever under a service manager because nobody is there to pick a theme. Codex Remote pre-answers wizards, handles sign-in, and runs Claude Code as its own claude account with its own login because two installs cannot share one refresh token.
3. Pain Point: Session Loss and Agent Downtime: Closing a laptop lid loses a terminal session. Rebooting the cloud box can leave the agent never coming back, discovered days later. Codex Remote installs systemd units enabled at boot with a shared codex-remote-* prefix, so stop and start brings all services back and remote AI coding sessions survive restarts.
4. Pain Point: Missing Gitignored Config and Secrets: A clone arrives without the gitignored .env file, so the code is all there and the project still does not run. Codex Remote push clones or copies the project, then sends untracked config separately. Portable MCP servers travel with it, reducing environment drift between local and remote AI coding agents.
5. Pain Point: Credential Sprawl and Hosted Middleman Risk: Cloud tokens kept in files or OpenTofu state can leak, and hosted remote development platforms introduce a middleman that holds or mediates access. Codex Remote stores tokens in the macOS login keychain, never to a file or OpenTofu state, and has no hosted middleman. Credentials stay on the Mac.
6. Target Audience: AI engineers, DevOps engineers, platform engineers, indie hackers, Mac-based developers using Codex CLI or Claude Code, remote-first teams, MCP tool builders, multi-cloud users, homelab operators, and engineering managers evaluating secure remote AI coding environments. The product is especially relevant to users who already pay for a cloud account and want agent infrastructure without a managed hosted service.
7. Use Cases: Running long-lived Codex or Claude Code sessions on cloud VMs; running parallel agents across multiple projects; offloading heavy builds and tests to cloud hardware; maintaining persistent MCP servers; letting an agent provision its own compute under opt-in MCP permissions; syncing local projects with secrets; managing Hetzner, AWS, DigitalOcean, Linode, Vultr, and Scaleway machines from one menu bar; and using custom provider registries for internal clouds or homelabs.

Unique Advantages

1. Differentiation: Traditional methods require manually editing SSH config, installing Node and CLIs, completing OAuth, creating systemd units, copying .env files, and repeating the process for every new machine. Generic Terraform or OpenTofu scripts do not handle Codex parser quirks, Claude Code account separation, MCP migration, or agent MCP permissions. Hosted remote dev platforms introduce middlemen and move credentials off-device. Codex Remote is open source, provider-agnostic, credential-local, and specifically wires Codex and Claude Code into the tools users already work in.
2. Key Innovation: The runtime provider registry with SHA-256 pinned OpenTofu HCL allows new clouds without app releases while protecting against later HCL tampering. Per-machine OpenTofu state prevents cross-machine interference. The inline SSH config block solves Codex's Include limitation. The systemd prefix codex-remote-* groups services for easy status and recovery. MCP permission tiers separate read, change, and destroy operations, with destroy requiring the machine name twice. Credentials stay in the macOS login keychain, never OpenTofu state. The app is independent of OpenAI and Anthropic.

Frequently Asked Questions (FAQ)

1. What is Codex Remote? Codex Remote is an open-source macOS menu bar app that provisions a cloud VM you control and wires it up as a remote Codex or Claude Code agent. It uses OpenTofu for provisioning, SSH for bootstrap, systemd for agent services, and MCP for tool access. It supports Hetzner, AWS, DigitalOcean, Linode, Vultr, and Scaleway, with custom provider registries available at runtime.
2. How does Codex Remote keep cloud credentials secure? Cloud provider tokens are stored in the macOS login keychain, not in files or OpenTofu's state. The app has no hosted middleman, so credentials stay on your Mac. The registry HCL is pinned to a SHA-256 hash so a registry URL cannot silently change applied infrastructure later.
3. Which cloud providers and custom clouds are supported? Built-in providers include Hetzner, AWS, DigitalOcean, Linode, Vultr, and Scaleway. The catalogue is a JSON registry fetched at runtime, so users can point Settings → Providers to a custom registry for a homelab, internal cloud, or fork. Adding a provider is a pull request rather than an app release.
4. Can an AI agent create or destroy machines with Codex Remote? Yes, through MCP. Read-only tools list_machines and list_sizes are always available. run_command, sync_project, and create_machine require opt-in because they change systems or spend money. destroy_machine has its own switch and requires the machine's name twice, so a model-generated unverified name fails instead of deleting something real.
5. Is Codex Remote affiliated with OpenAI or Anthropic? No. Codex Remote is independent and open source. It installs and connects Codex CLI and Claude Code, but it is not affiliated with OpenAI or Anthropic. It is designed to put those agents on a cloud machine you control without a hosted middleman.