Skip to main content
Connect to a rig VM from Codex in two ways:
  • Desktop app: add the rig as an SSH host and open its remote project.
  • Mobile app: pair with the rig’s remote-control daemon.
The rig must remain active while you use either connection. See Create a rig.

​
Connect the desktop app

You need the Codex desktop app, the authenticated Amika CLI, and an SSH identity. Create an identity with amika secret ssh-keygen if you do not already have one.
1

Add the rig as an SSH host

Run this on the computer where you use the Codex desktop app. Replace dev-box with your rig name.
The command adds a concrete host to your SSH configuration, enables Codex remote connections, and opens the Codex app. It prints the SSH host name and remote project folder to use in the next step.
2

Enable the SSH host in Codex

In the Codex desktop app, open Settings > Connections. Add or enable the SSH host printed by the CLI, then choose the printed remote project folder.
The desktop app starts and manages the remote Codex app-server over SSH. You do not need to start codex remote-control or generate a pairing code for this connection.

​
Connect the mobile app

You need Codex remote control access for your ChatGPT account and workspace. Sign in to the Codex mobile app with the same account and workspace you use on Amika rigs.
1

Open a shell in the rig

Replace dev-box with your rig name.
2

Sign in to Codex

Check whether the rig already has a Codex login:
If you are not logged in, use device authentication and follow the printed instructions:
3

Start remote control

Start the app-server daemon in the rig:
4

Generate a pairing code

Generate a short-lived code:
Open remote control in the mobile app and enter the code. Generate another code if it expires before you finish pairing.

​
Stop mobile remote control

Stop the rig’s app-server daemon when you no longer want it available for remote control:
Stopping or deleting the rig also makes it unavailable.