---
url: https://clusto.app/docs/codex-cli-remote.md
description: >-
  Run OpenAI Codex CLI on your own server or VPS with Clusto, keep it working
  when you disconnect, and reattach from the desktop app, your phone or a
  browser.
---

# Codex CLI Remote: Run Codex on a Server and Reach It From Any Device

To use Codex CLI remotely, run it on a machine that stays on and put a session
manager in front of it. With Clusto you install the daemon (`clustod`) on your
Linux or Windows server, start Codex as a session on it, and attach from the
desktop app, the Android app, the web app on any phone, or the CLI. The Codex
process belongs to the daemon, so it keeps working when you close the laptop or
your phone loses signal, and you reattach to the same session later.

OpenAI also offers its own ways to run Codex away from your desk. This page
covers those first, then the self-hosted setup.

## Your options for running Codex remotely

**Last reviewed: November 20, 2026.** Product details below come from OpenAI's
documentation on that date and can change.

* **Codex cloud.** OpenAI runs the task in its own cloud environment. Each task
  gets its own workspace and keeps running while your computer is asleep. It
  checks out repositories from a connected GitHub or GitLab account, and you can
  start and review tasks from the web, the desktop app, mobile, or the CLI. See
  [Codex cloud](https://learn.chatgpt.com/docs/cloud).
* **Remote connections in the ChatGPT apps.** From the ChatGPT mobile app you can
  open Codex and work with chats on a paired Mac or Windows computer that runs the
  ChatGPT desktop app. The desktop app can also open projects on an SSH host. The
  host has to stay awake, online and signed in; if it sleeps or closes the app,
  remote access stops. See
  [Remote connections](https://learn.chatgpt.com/docs/remote-connections).
* **SSH and tmux.** Run `codex` inside tmux on a server and reattach over SSH. It
  costs nothing and works anywhere, but phone typing is awkward and nothing tells
  you when Codex is waiting for an approval.
* **A self-hosted session manager such as Clusto.** Codex runs on your server as
  a managed session, next to your other agents and shells, and you reach it from
  several kinds of client.

If your code is on GitHub and a fresh cloud environment per task suits you, Codex
cloud needs no server at all. If your laptop is a Mac or Windows PC that stays on
at your desk, OpenAI's remote connections may be all you need.

## Where self-hosting differs

Self-hosting fits when the work has to happen on a specific machine:

* **Your environment.** The server has your toolchain, databases, private package
  registries and credentials already in place, and repositories from any host.
* **Always on without a desktop app.** A headless Linux VPS has no ChatGPT desktop
  app to pair with. The Clusto daemon runs there as a system service.
* **More than Codex.** The same node runs Claude Code, OpenCode, GitHub Copilot
  CLI and plain shells, and one app shows sessions from every
  [clustered](/clustering) machine.
* **You run it.** You install and update the server, Codex and the daemon
  yourself. Codex still talks to OpenAI as usual; self-hosting the session does
  not make model inference local.

## Set up Codex on a server with Clusto

### 1. Install Codex CLI and sign in

On the server, install Codex with npm, as the
[Codex README](https://github.com/openai/codex) shows:

```bash
npm install -g @openai/codex
```

A server has no browser for the normal sign-in. OpenAI's
[authentication docs](https://learn.chatgpt.com/docs/auth) recommend device code
login for headless machines (marked beta, and it must be enabled in your ChatGPT
security settings first):

```bash
codex login --device-auth
```

Open the printed link on any device, sign in, and enter the code. The same page
describes two fallbacks: copy `~/.codex/auth.json` from a machine where you
already signed in, or forward the login callback port with
`ssh -L 1455:localhost:1455 user@remote` and run `codex login` in that session.

### 2. Install the Clusto daemon

On Linux, run the install script. It installs the CLI for x64 or ARM64 and runs
the `clusto install` wizard, which installs and starts the daemon:

```bash
curl -fsSL https://dl.clusto.app/install.sh | sh
```

On Windows, run this in PowerShell; it registers the `clustod` service:

```powershell
irm https://dl.clusto.app/install.ps1 | iex
```

See [Downloads and Installation](/downloads) for both, including a per-user
install without `sudo`.

### 3. Connect a client

Print the node's token on the server:

```bash
sudo clusto daemon get-token
```

Then add the server under **Connection** in the app, with its host, port (9178
by default) and token. Clients are the desktop app on Windows and Linux, the
Android app, and the web app at [web.clusto.app](https://web.clusto.app/), which
installs on iPhone and iPad from Safari with **Add to Home Screen**. The web app
needs a `wss://` address and a sign-in with a licensed Clusto account; see
[Web Client (PWA)](/web-client). To reach the server without a VPN or port
forwarding, use [Clusto Tunnel](/clusto-tunnel), a licensed feature. Tailscale
or any network where the server is reachable also works.

### 4. Add Codex to the node's shells

The daemon seeds a **Claude agent** preset when it finds Claude Code, but Codex
needs one entry. Open the node's **Node settings** in the **Cluster** view, go to
**Shells > Add Shell**, and set `codex` as the program. You can also pick
**Custom...** in **New Session** and type the command line. See
[Configuration](/configuration#commands).

### 5. Start Codex and reattach

Choose **New Session**, pick a project, and select your Codex shell. You get the
real Codex terminal interface, running on the server. Split it next to other
sessions in the [Terminal Workspace](/terminal-workspace).

You can also start it from a shell on the server. The CLI streams output but does
not forward keystrokes, so you type into the session from the app:

```bash
clusto open --dir /srv/myapp --shell codex --name "codex-refactor"
```

Press `Ctrl+C` to detach; the session keeps running. Later, list sessions with
`clusto ls` and watch one with `clusto attach <session-id>`.

Close the app, lock the phone, switch networks. When you open Clusto on any
device and pick the session from the **Terminals** tree, it resumes where it
left off. One client types at a time and the others view until you take over;
see [Session Exclusivity](/session-exclusivity).

## Knowing when Codex needs you

Codex 0.166 and later report approvals and questions with
[OSC 7501](/terminal-notifications), and older releases show an `Action
Required` terminal title. Clusto reads either, marks the session with an amber
`?` in the sidebar, and clears it when Codex continues. The desktop app shows a
popup and sound when an agent goes idle, and Android can check in the background
about every 15 minutes. See [Agent Waiting Marker](/agent-attention).

## Codex as a chat instead of a terminal

If a terminal is too fiddly on a phone, create a [Chat](/chats) and pick
**Codex** as the provider. You get a conversation view with Markdown replies,
file pasting and queued messages, and the status line shows Codex's 5-hour and
weekly plan windows and context fill. Codex chats run without approval prompts.
**Open in TUI** switches the same conversation to `codex resume` in a terminal,
and turns you make there are copied back into the chat.

## Several Codex agents at once

[Teams](/teams) run a leader and workers as headless agents, and each worker gets
its own git worktree. A Codex leader is one flag:

```bash
clusto team create --name codex-team --working-dir /srv/myapp --agent codex
```

For the wider picture, see
[Run Multiple Claude Code Sessions](/run-multiple-claude-code-sessions), which
applies to Codex too.

## FAQ

### Can I use Codex CLI from my phone?

Yes. Run Codex on a server under Clusto and open the session from the Android
app or the web app on any phone, including iPhone. OpenAI's ChatGPT mobile app
can also reach Codex on a paired Mac or Windows computer, or Codex cloud tasks.

### How do I run Codex on a server that has no browser?

Install it with npm, sign in with `codex login --device-auth`, and run it under a
session manager so it survives disconnects. The steps are above.

### Does Codex keep running when I close my laptop?

With Clusto, yes: the session lives on the server, not on the client. A reboot
of the server itself ends terminal sessions, as with any process.

### Do I need an OpenAI API key?

No. Codex signs in with your ChatGPT account or an API key, the same as it does
locally. Clusto does not change how Codex authenticates.

### Is Clusto free?

Clusto requires a license. The Personal plan is free for one user on up to three
devices. See [Accounts and Licensing](/accounts-licensing).

## Get started

1. Install Codex and the daemon on your server with the commands above.
2. Download the app from [clusto.app/download](https://clusto.app/download) or
   open [web.clusto.app](https://web.clusto.app/).
3. Connect, start a Codex session, and close the laptop.

For the Claude Code version of this guide, see
[Run Claude Code on a Server or VPS](/run-claude-code-on-a-server).
