Choose how to run Codex in a sandbox
The app server is the agent backend for the remote CLI and desktop connections. Choose where you want to interact with the agent:
The attached CLI uses
cws-agent to create a sandbox. The local CLI and desktop
app share the SSH sandbox setup.
For mobile access, pair your phone with the desktop host through Remote. The
phone connects to that host, which connects to the sandbox over SSH. Keep the
desktop host awake, online, and running the app. See
Mobile and another desktop through Remote.
The local terminal user interface (TUI) sends input, presents output, and handles
approvals. The app server owns the remote agent session. It doesn’t forward
individual commands from an agent running on your laptop. See the
OpenAI app server guide.
Starting the app server doesn’t register its sessions with the desktop or mobile app.
Those interfaces use the separate connection setup described in
Use the desktop and mobile apps. OpenAI’s
Remote documentation doesn’t establish a website attachment flow for this
self-hosted session. Browser access is outside the scope of this guide.
The programmatic Agents API workflow uses a separate execution model. See the
OpenAI Agents API recipe.
Prerequisites
Before you begin, make sure you have the following:- A W&B API key and capacity for a CPU sandbox. These examples select W&B authentication.
- An OpenAI account supported by Codex, or an OpenAI API key. The app server example in this guide uses API-key authentication and API billing.
- A public repository URL. Private clones require Git credentials in the sandbox.
- Outbound connectivity to OpenAI, package registries, and your Git host
[WANDB-API-KEY] with your W&B API key, then load
the sandbox credential:
Run Codex CLI in a sandbox
Usecws-agent to launch a sandbox and attach your terminal. Both the Codex TUI
and agent process run inside the sandbox.
-
Follow the
cws-agentinstallation instructions. For API-key authentication, exportOPENAI_API_KEYlocally before launch. The tool passes it to the sandbox and stores it through Codex’s login command. -
Replace
[SANDBOX-NAME]with a name that contains 1 to 40 lowercase letters, digits, or hyphens and starts with a letter or digit. Replace[REPOSITORY-URL]with your public repository URL:If a skills or Model Context Protocol (MCP) import prompt appears, press Enter to skip it for this example. Codex opens in the sandbox’s project directory. Follow its workspace trust and authentication prompts.--permission-mode nativeretains Codex’s own permission settings. The wrapper otherwise defaults to bypassing approval prompts. Seecws-agentpermission modes. -
If you need account sign-in, exit the TUI, then authenticate in the sandbox:
Follow the login flow that Codex shows. For headless device sign-in and workspace restrictions, see Codex authentication.
-
Complete Check the session. To reconnect later while the
sandbox runs, use the same
connectcommand. To resume a saved Codex conversation, seecws-agentsessions.
Create an SSH-accessible sandbox
Complete this setup for either the local CLI or the desktop app. It uses the Sandbox software development kit (SDK) to create a sandbox with Codex installed and authenticated for a non-root SSH user. It doesn’t requirecws-agent.
The setup uses a Transport Layer Security (TLS) passthrough endpoint
and stunnel to carry SSH through the endpoint. A generated Python
ProxyCommand verifies the TLS certificate, then SSH
authenticates your key and verifies the host key. The app server has no public
listener. This follows OpenAI’s network exposure guidance.
Prepare the SSH client
Use a macOS or Linux computer with Python 3.12+,uv, and OpenSSH.
For desktop access, use a supported app and operating system from OpenAI’s
SSH-host instructions.
This setup uses the sandbox credential from Prerequisites and an
OpenAI API key with API billing.
Replace [OPENAI-API-KEY] with your OpenAI API key:
Create the SSH sandbox
Save the following in thecreate_codex_ssh.py file. It creates an 8-hour sandbox, installs
Codex 0.154.0, and configures a non-root agent account with public-key SSH
authentication. It passes the OpenAI key to codex login through standard input (stdin).
It doesn’t store the key in the sandbox’s creation configuration. Codex saves its login
inside the sandbox.
The script also creates a 1-day TLS certificate and retrieves the public
certificate and SSH host key through the authenticated Sandbox SDK. The generated
client configuration verifies both. Keep the output directory to reconnect.
Sandbox setup script
Sandbox setup script
create_codex_ssh.py
[REPOSITORY-URL] with a public Git repository URL, and choose a new
output directory outside your repository:
ssh_config file and leaves the
sandbox running. The output directory also contains the sandbox-id, tls.crt,
and known_hosts files, plus the tls_proxy.py forwarder. If setup fails after
creation, the script attempts to stop the sandbox. If stopping also fails, the
original error includes the sandbox ID for manual cleanup.
Before you connect Codex, verify the SSH connection:
agent, codex-cli 0.154.0, and repository-ready.
If the first connection fails, retry after the endpoint and services finish
starting. If connections continue to fail, inspect the /var/log/codex-sshd.log and
/var/log/codex-stunnel.log files through the Sandbox SDK.
With the SSH connection verified, continue with either
your local CLI or the
desktop and mobile apps.
Connect your local CLI to Codex app server
Complete Create an SSH-accessible sandbox first. Use a supported Node.js long-term support (LTS) release to install the same Codex version locally. The npm package declares Node.js 16 or later as its minimum:-
In the sandbox’s project directory, start the app server. This command saves startup
output even if the app server exits. Keep the terminal open:
The
-toption allocates a remote terminal so Ctrl+C reaches the listener. -
In a second terminal, forward a local port to that listener and keep the
connection open:
-
In a third terminal, connect the local TUI and explicitly select the remote
project directory:
-
Confirm that the TUI shows
/workspace/project, then complete Check the session. If the connection fails, inspect the retained startup output:
codex --remote command.
This listener is separate from the app server managed by the desktop app.
Sharing a conversation between the two hasn’t been verified. See OpenAI’s
local TUI connection reference.
When you finish, exit the TUI, then press Ctrl+C in the listener terminal
and the forwarding terminal. Follow
Reconnect and stop the SSH sandbox
to retrieve files and stop compute.
Use the desktop and mobile apps
Complete Create an SSH-accessible sandbox first. Add the sandbox as an SSH project in the desktop app, then use Remote to continue from a paired phone. The desktop host maintains the SSH connection.Connect the desktop app
Add the sandbox as a remote project, then confirm that Codex writes to its filesystem.-
In the
~/.ssh/cw-codex-session/ssh_configfile, copy the generatedHost cw-codexblock. In the~/.ssh/configfile, paste it before anyHost *defaults. Replace an existingHost cw-codexentry rather than adding a duplicate. -
Run
ssh cw-codex 'codex --version'. Resolve authentication or host-key errors before continuing. -
In the desktop app, open Settings > Connections, then add or enable
the
cw-codexSSH host. -
Choose
/workspace/projectas the remote project folder and save the project. -
Open that remote project and start a conversation. Ask Codex to write a unique,
non-secret value to the
/workspace/project/sandbox-proof.txtfile. -
From your terminal, verify the result independently:
Mobile and another desktop through Remote
OpenAI’s Remote feature connects supported desktop and mobile apps through a paired host. The documented mobile setup starts in the ChatGPT desktop app on a Mac or Windows host, with the same account and workspace on both devices. Organization settings and rollout availability can restrict access. To work in the sandbox from your phone, first connect that desktop host to the sandbox’s SSH project. Then pair your phone with the desktop host. In ChatGPT on iOS or Android, use Remote. Your phone connects to the desktop host, which connects to the sandbox. The desktop app must stay running, awake, and online. Another supported Mac or Windows desktop app can connect to the same host when Control other devices is available. Follow OpenAI’s Remote setup instructions. An app server WebSocket URL isn’t a mobile pairing URL. The Agents API’scodex exec-server --remote connection also doesn’t pair a mobile device.
Session continuity and other entry points
Remote supports continuing a connected host’s chats from paired devices. That doesn’t establish that a conversation started with the directcodex --remote
example appears in an independently configured desktop SSH project. Treat
that cross-interface session handoff as unverified for this setup.
The published Remote setup lists mobile and supported desktop clients. It doesn’t
document attaching the ChatGPT or Codex website to this sandbox session. Website
access is outside the interfaces covered in this guide.
Some Codex builds expose experimental codex remote-control start and
codex remote-control pair commands. They manage an app server daemon and pairing,
but the published mobile instructions don’t establish a supported headless Linux
sandbox pairing flow. This guide doesn’t treat them as a verified equivalent of
Claude Remote Control. Check the installed CLI help and current OpenAI guidance
before relying on them.
Check the session
For Run Codex CLI in a sandbox or Connect your local CLI to Codex app server, verify that Codex writes to the sandbox’s filesystem. For desktop access, follow Connect the desktop app. Replace[PROOF-VALUE] with a unique non-secret value, then send this prompt in
the connected Codex TUI:
- cws-agent
- Local CLI over SSH
Reconnect and stop the SSH sandbox
While the sandbox runs, use the samecw-codex host and project.
Closing an SSH connection or the desktop app doesn’t stop sandbox compute.
Before you stop the sandbox, save your work to Git or copy files you need:
Host cw-codex block with the new
configuration. Each sandbox has a new endpoint, TLS certificate, and SSH host key.
Keep results and stop
For the local CLI and desktop app, follow Reconnect and stop the SSH sandbox. Forcws-agent, save a workspace snapshot and stop compute:
cws-agent down [SANDBOX-NAME] --no-snapshot.
Exiting the TUI doesn’t stop compute. When you stop the sandbox or it expires,
its processes end. To restart compute, restore any saved files and start Codex
again. Snapshots don’t preserve running processes. Treat saved Codex
authentication and session files as sensitive when you choose what to preserve.
Troubleshoot
Use the following checks to troubleshoot common issues:- Authentication fails: distinguish sandbox provisioning credentials, Codex model authentication, and SSH keys. They serve different purposes.
- App server flags are rejected: compare local and sandbox
codex --versionoutput. The local CLI example requires the documented WebSocket flags. - The TUI connects but work fails: inspect model access, billing, workspace trust, and approval settings. A transport connection alone doesn’t prove model access.
- The connection drops: reconnect while the sandbox is running. Endpoint or transport timeouts don’t extend its lifetime or guarantee an in-flight turn completed.
- Remote isn’t available in the mobile app: check OpenAI’s account, workspace, host, and rollout requirements. Starting the app server alone doesn’t enable it.