name

codex-mobile-remote-control-vm

description

Set up, repair, or verify an Ubuntu/Linux desktop VM that lets the ChatGPT/Codex mobile app remotely control Codex Desktop. Use when Codex needs to create a Proxmox or SSH-accessible Ubuntu VM, install a desktop session, run the Linux Codex Desktop port, configure remote_connections/remote_control, pair or troubleshoot mobile remote control, handle disappearing Connections rows, or document a third-party handoff.

Codex Mobile Remote Control VM

Workflow

Use this skill to take a fresh or existing Ubuntu VM from SSH-only to a usable Codex Desktop host that can be controlled from the ChatGPT/Codex mobile app.

Establish access and inventory.
- Confirm Proxmox VM id/name/IP when applicable.
- Confirm SSH works before changing the VM.
- Record the GUI username/password handoff only if the user explicitly wants it stored.
- If using Proxmox UI or noVNC, use Computer Use for browser/GUI verification.
Install or repair the desktop layer.
- Prefer a light desktop such as XFCE with LightDM.
- Ensure qemu-guest-agent is active on Proxmox VMs.
- Ensure xrdp only when the user wants RDP access.
- Verify noVNC shows a GUI login or desktop, not only tty1.
Install or launch Codex Desktop.
- Use the local Linux-compatible Codex Desktop port already chosen by the user or repo.
- Create a stable launcher such as ~/.local/bin/codex-desktop-launch.
- If the port's launcher assumes a NixOS-only path, wrap it so it directly executes the app's start.sh with a normal shell.
- Create a desktop shortcut for the GUI user that points to the stable launcher.
- Launch from the GUI session with:

DISPLAY=:0 XAUTHORITY=$HOME/.Xauthority XDG_RUNTIME_DIR=/run/user/1000 ~/.local/bin/codex-desktop-launch

Configure mobile remote control.
- Ensure ~/.codex/config.toml contains:

[features]
remote_connections = true
remote_control = true
workspace_dependencies = false

Also check the app-server feature DB when Connections behaves inconsistently:

sqlite3 ~/.codex/sqlite/codex-dev.db 'select feature_name, enabled from local_app_server_feature_enablement order by feature_name;'

If needed, insert remote_control and remote_connections with enabled=1, then relaunch Codex Desktop.
Do not leave ~/.codex/config.toml immutable. Immutable config can block future app settings writes.

Sign in and pair mobile.
- Sign into Codex Desktop in the VM with the same ChatGPT account as the mobile app.
- Have the user open the ChatGPT/Codex mobile app and refresh/open the mobile remote-control surface.
- Treat the VM-side Connections UI carefully: on the Linux port it may show only the SSH card while mobile remote control still works.
Verify using three surfaces.
- GUI: Codex Desktop reaches the home screen and Settings > Connections opens.
- Local state: ~/.codex/state_5.sqlite has a remote_control_enrollments row.
- User proof: mobile app can open and control the VM Codex session.
- Convenience: the GUI desktop has a trusted Codex Desktop.desktop shortcut.

For detailed command sequences and known failure modes, read references/runbook.md. For a read-only health check, run scripts/audit-codex-remote-vm.sh.

Troubleshooting Priorities

If the user says the row appeared and disappeared, check logs before reinstalling.
connectionCount=0 in ~/.cache/codex-desktop/launcher.log means the Connections UI list is empty, but not necessarily that mobile remote control is broken.
A valid enrollment looks like one row in remote_control_enrollments with server_name, environment_id, and updated_at.
If the app removes remote_control = true at startup, re-add it after the app is open and verify again; avoid making the file immutable except for short diagnosis.
If Proxmox noVNC shows a TTY after reboot, GUI login may still be required before launching Codex Desktop.
If mobile control works, report that as the primary success criterion even if Settings > Connections does not show a device row.

Handoff

Always leave a short repo or note with:

VM host, VM id, VM name, guest IP, SSH alias, and GUI login method.
Exact launcher path and restart command.
Desktop shortcut path and whether it is trusted/executable.
The config.toml feature block.
How to verify enrollment and logs.
Whether mobile control was personally verified by the user.

Codex Mobile Remote Control VM

Workflow

Use this skill to take a fresh or existing Ubuntu VM from SSH-only to a usable Codex Desktop host that can be controlled from the ChatGPT/Codex mobile app.

Establish access and inventory.

Confirm Proxmox VM id/name/IP when applicable.
Confirm SSH works before changing the VM.
Record the GUI username/password handoff only if the user explicitly wants it stored.
If using Proxmox UI or noVNC, use Computer Use for browser/GUI verification.

Install or repair the desktop layer.

Prefer a light desktop such as XFCE with LightDM.
Ensure qemu-guest-agent is active on Proxmox VMs.
Ensure xrdp only when the user wants RDP access.
Verify noVNC shows a GUI login or desktop, not only tty1.

Install or launch Codex Desktop.

Use the local Linux-compatible Codex Desktop port already chosen by the user or repo.
Create a stable launcher such as ~/.local/bin/codex-desktop-launch.
If the port's launcher assumes a NixOS-only path, wrap it so it directly executes the app's start.sh with a normal shell.
Create a desktop shortcut for the GUI user that points to the stable launcher.
Launch from the GUI session with:

DISPLAY=:0 XAUTHORITY=$HOME/.Xauthority XDG_RUNTIME_DIR=/run/user/1000 ~/.local/bin/codex-desktop-launch

Configure mobile remote control.

Ensure ~/.codex/config.toml contains:

[features] remote_connections = true remote_control = true workspace_dependencies = false

Also check the app-server feature DB when Connections behaves inconsistently:

sqlite3 ~/.codex/sqlite/codex-dev.db 'select feature_name, enabled from local_app_server_feature_enablement order by feature_name;'

If needed, insert remote_control and remote_connections with enabled=1, then relaunch Codex Desktop.

Do not leave ~/.codex/config.toml immutable. Immutable config can block future app settings writes.

Sign into Codex Desktop in the VM with the same ChatGPT account as the mobile app.
Have the user open the ChatGPT/Codex mobile app and refresh/open the mobile remote-control surface.
Treat the VM-side Connections UI carefully: on the Linux port it may show only the SSH card while mobile remote control still works.

Verify using three surfaces.

GUI: Codex Desktop reaches the home screen and Settings > Connections opens.
Local state: ~/.codex/state_5.sqlite has a remote_control_enrollments row.
User proof: mobile app can open and control the VM Codex session.
Convenience: the GUI desktop has a trusted Codex Desktop.desktop shortcut.

For detailed command sequences and known failure modes, read references/runbook.md. For a read-only health check, run scripts/audit-codex-remote-vm.sh.

Troubleshooting Priorities

If the user says the row appeared and disappeared, check logs before reinstalling.

connectionCount=0 in ~/.cache/codex-desktop/launcher.log means the Connections UI list is empty, but not necessarily that mobile remote control is broken.

A valid enrollment looks like one row in remote_control_enrollments with server_name, environment_id, and updated_at.

If the app removes remote_control = true at startup, re-add it after the app is open and verify again; avoid making the file immutable except for short diagnosis.

If Proxmox noVNC shows a TTY after reboot, GUI login may still be required before launching Codex Desktop.

If mobile control works, report that as the primary success criterion even if Settings > Connections does not show a device row.

Handoff

Always leave a short repo or note with:

VM host, VM id, VM name, guest IP, SSH alias, and GUI login method.

Exact launcher path and restart command.

Desktop shortcut path and whether it is trusted/executable.

The config.toml feature block.

How to verify enrollment and logs.

Whether mobile control was personally verified by the user.