Run Codex or Gemini CLI From an iPhone
Claude Code is not the only coding agent that lives in a terminal, and none of them care what kind of device is attached to that terminal. OpenAI's Codex CLI and Google's Gemini CLI both install on a server, authenticate against your own account, and read and write files in a project directory. That makes them reachable from a phone the same way anything else on your server is reachable: over SSH. The part worth getting right is not the connection, it is what happens when your phone locks mid-run, and how you check what the agent actually changed before it becomes a commit.
Written by the GateShell team at Hefty Innovations
Step by step
- 1
Install the CLI on the server, not on the phone
The agent runs where your code is. Install Codex CLI or Gemini CLI on the server that holds the project, and authenticate it there against your own provider account. Nothing about this step is GateShell-specific, and that is the point: the agent is an ordinary program on your machine, billed to your account, and your phone is only the terminal attached to it. GateShell detects which of Claude Code, Codex, and Gemini CLI are installed and reports the version it found, so you are not guessing at whether a PATH problem or a missing install is behind a command that does nothing.
- 2
Pick the project before you start the session
Both CLIs operate relative to a working directory, and an agent started in the wrong directory is the most common way to waste a run. Select the remote project first, so the session is scoped to it from the beginning. This also makes resuming meaningful later: a session belongs to a project, rather than being whatever the shell's last cd happened to leave behind.
- 3
Start a new session or resume the one already running
Starting fresh and resuming are genuinely different operations, and conflating them costs context. A new session begins with no history. Resuming reattaches to work already in progress, which is what you want when you started something at a desk and are now continuing on a train. GateShell exposes both as explicit choices per project rather than inferring which you meant.
- 4
Keep the run alive independently of your phone
This is the failure mode that actually bites. If the agent is a child of your SSH session, the session ending kills it, and on iOS the session ends more often than you would like: the screen locks, the app backgrounds, the network switches from Wi-Fi to cellular. Run the agent inside tmux so the process belongs to the server rather than to your connection, and connect over Mosh so a network change does not tear the session down in the first place. The two solve different halves of the problem and are worth combining.
- 5
Interrupt it when it goes the wrong way
Watching an agent commit to a bad approach and not being able to stop it is worse on a phone than on a laptop, because the instinct is to close the app, which does not stop anything. Send a real interrupt instead. GateShell surfaces interrupt as an explicit action on the running session, so stopping the agent does not depend on finding the right key combination on a software keyboard.
- 6
Review the diff before you trust it
The review is the part that protects you, and it is the part most easily skipped on a small screen. GateShell reads staged and unstaged Git diffs over the same SSH connection, read-only, so you can see exactly what changed without granting the review surface any ability to change it further. Read the diff before committing, particularly for edits to files you did not expect the agent to touch.
Frequently asked questions
Does my provider API traffic go through GateShell?+
No. The CLI on your server talks to the provider directly, using the account and credentials configured there. GateShell does not proxy, inspect, or relay that traffic — it is attached to the terminal, not to the model connection. Your provider billing and rate limits behave exactly as they do when you run the same CLI from a laptop.
Which agents are detected?+
Claude Code, Codex, and Gemini CLI. GateShell detects which are installed on the selected server and reports the installed version, then offers new or resumed project-scoped sessions for the one you pick.
Do I need an API key stored in the app?+
No, and there is nowhere to put one. Authentication belongs to the CLI on your server. This is a deliberate consequence of the zero-backend design: the app holds SSH credentials in the device Keychain and nothing else, so there is no provider key on the phone to leak if the device is lost.
What happens to the agent if my phone loses signal?+
That depends entirely on whether the process is a child of your SSH session. If it is, the disconnect kills it. If you started it inside tmux, it keeps running on the server and you reattach when you have signal again. Mosh additionally survives the IP address change, so brief network switches do not register as a disconnect at all. Use both.
Can I review changes without giving the app write access to my repository?+
Yes. Diff review is read-only by design. It runs Git read commands over the existing SSH connection and renders the result; it does not stage, commit, or push. Those remain things you do deliberately in the terminal.
Is this different from running the agent on my Mac?+
Functionally it is the same agent doing the same work — the difference is where it runs. Running it on a server means it continues when your laptop is closed, it uses the server's resources and network, and any device with an SSH client can attach to it. The phone becomes a viewport onto a long-running process rather than the host of one.
Try it in GateShell
GateShell is a zero-backend SSH client for iPhone, iPad, and Mac, with no vendor cloud, no accounts and no telemetry. Everything above works out of the box.
Guide reflects GateShell's shipped features as of September 2026. Steps assume basic familiarity with SSH and the command line; server-side commands may vary by distribution. All product names, logos, and brands are property of their respective owners.