Run Codex remote control on a server

Set up the VM#

On your computer, create a VM and connect. Pick any free name: the VM shows up in the ChatGPT app under it. If you've already clicked Deploy or have a VM, skip the first command and use its name:

ssh exe.dev new --name=my-codex-rc
ssh my-codex-rc.exe.xyz

On the VM, turn on remote control for Codex's daemon and have a systemd user service start the daemon on every boot. Codex's own daemon doesn't survive a reboot by itself:

codex app-server daemon enable-remote-control
mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/codex-remote-control.service <<'EOF'
[Unit]
Description=Codex app-server daemon with remote control
Wants=network-online.target
After=network-online.target

[Service]
Type=oneshot
RemainAfterExit=yes
ExecStart=/usr/local/bin/codex app-server daemon start
ExecStop=/usr/local/bin/codex app-server daemon stop

[Install]
WantedBy=default.target
EOF
systemctl --user daemon-reload
systemctl --user enable --now codex-remote-control
git init ~/project

The first command copies Codex into ~/.codex/packages/app-server-daemon, where the daemon runs and updates itself. Check that it's up: the service is active and the daemon reports "status":"running":

systemctl --user is-active codex-remote-control
codex app-server daemon version

exe.dev VMs keep user services running without a login, so this survives reboots and disconnects.

Sign in and pair your phone#

Remote control goes through your ChatGPT account, so Codex on the VM signs in to it. First, turn on device code login in your ChatGPT security settings (a workspace admin does this in workspace permissions). Then, on the VM:

codex login --device-auth

Open the link it prints on your computer or phone, sign in, and enter the code. If you've connected this VM's Codex to exe.dev's LLM integration before, delete the model_provider = "exe-llm" line from ~/.codex/config.toml too, so Codex uses your ChatGPT plan.

Restart the daemon so it picks up the sign-in, then check the connection:

systemctl --user restart codex-remote-control
codex remote-control start

It says This machine is available for remote control as my-codex-rc. Now create a pairing code:

codex remote-control pair

It prints Pairing code: and a short code, valid for a few minutes. In the ChatGPT app on your phone, signed in to the same account and workspace, open Codex (Remote in some versions), start adding a computer, and choose to pair manually instead of scanning a QR code. Enter the code. The VM appears as my-codex-rc. Pair each phone once; the pairing is saved on the VM's disk.

Note

If your ChatGPT account belongs to a workspace, its admin may have to allow Remote Control before pairing works.

Start a chat from your phone#

In the ChatGPT app, open my-codex-rc, choose the ~/project folder and give Codex a task. For example:

Build a tiny website for a sandwich critic with strong opinions, and serve it on port 8000.

Codex works on the VM; you approve commands and read the diff on your phone, and lock it whenever you like. Open https://my-codex-rc.exe.xyz/ to see what it built: it's private to you by default (HTTPS proxy).

• Bring your code: connect a GitHub repo to the VM, so it can clone and push with no token on the VM. On your computer, ssh exe.dev integrations add github --name myapp --repository you/myapp --attach vm:my-codex-rc; then, on the VM, git clone https://github.int.exe.xyz/you/myapp.git ~/myapp, and pick ~/myapp in the app.
• At the keyboard: ssh my-codex-rc.exe.xyz, then codex in your project folder. The Codex page has the terminal setup.
• Another agent: Shelley, exe.dev's own agent, is on the VM too, at https://my-codex-rc.shelley.exe.xyz/ in your phone's browser.

codex app-server daemon update
codex app-server daemon version

Troubleshooting#

• Remote control is enabled on my-codex-rc but the connection is errored. Codex isn't signed in to ChatGPT. codex login status says Not logged in or that it uses an API key. Sign in with codex login --device-auth, then restart the service.
• remote control pairing is unavailable until enrollment completes. Same cause: the VM hasn't registered with OpenAI's relay yet. Fix the sign-in, run codex remote-control start, then pair.
• timed out waiting for remoteControl/pairing/start response. Run codex app-server daemon restart, then pair again.
• The device code is rejected. Device code login is off in your ChatGPT security settings or workspace permissions.
• The VM doesn't show up on your phone. The phone must use the same ChatGPT account and workspace as codex login status on the VM. Update the ChatGPT app and pair again.

To dig further, on the VM: codex doctor checks the install and sign-in, journalctl --user -u codex-remote-control shows the service, and ~/.codex/app-server-daemon/daemon.stderr.log is the daemon's log.