CoreWeave Serverless sandboxes are in public preview.
Choose how to run Codex in a sandbox
Codex App Server is the agent backend used by the remote CLI and desktop connections. Choose where you want to interact with the agent:
Each section includes a sandbox creation example. The desktop app option
creates an SSH connection and adds the sandbox as a remote project.
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. Codex 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 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. For CoreWeave API access tokens, see Choose a credential.
- 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.
Connect your local CLI to Codex App Server
This alternative uses the Sandbox software development kit (SDK) directly. It creates a separate sandbox with a public HTTPS endpoint and app-server authentication. It doesn’t requirecws-agent or configure snapshots.
Prepare the local client
Use Python 3.12+, Node.js 22+, anduv. Install matching Codex versions locally
and in the sandbox. This example pins 0.154.0:
[OPENAI-API-KEY] with
your OpenAI API key, then run:
Create the sandbox and start app-server
Save the following in thecreate_codex_server.py file. The script sends the OpenAI key
to codex login through standard input (stdin). It sends only a SHA-256 hash of the
connection token to app-server. Keep the original token in your local environment.
create_codex_server.py
[REPOSITORY-URL] with your public repository URL, then run the script:
Connect and verify
Replace[REMOTE-URL] with the printed wss:// URL:
--cd flag selects the remote project directory. Complete
Check the session before continuing.
If the first connection fails, inspect server startup before you retry.
Replace [SANDBOX-ID] with the printed sandbox ID:
Use the desktop and mobile apps
Connect your desktop app to a sandbox over SSH, then use Remote to continue from a paired phone. The desktop host maintains the SSH connection. Create a sandbox that your desktop app can reach with OpenSSH. The app starts Codex app-server over SSH and runs commands against/workspace/project in the
sandbox. If you already have an SSH-accessible sandbox with Codex installed and
authenticated, follow OpenAI’s SSH-host connection instructions.
This example uses a TLS passthrough endpoint
and stunnel to carry SSH through the endpoint. The generated OpenSSH
ProxyCommand establishes TLS, then SSH authenticates your key. App-server has
no public listener in this setup.
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 W&B 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 stdin instead
of storing it 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 and 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 open the app, verify the 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.
Connect the desktop app
Add the sandbox as a remote project, then confirm that Codex writes to its filesystem.-
Copy the generated
Host cw-codexblock from the~/.ssh/cw-codex-session/ssh_configfile into the~/.ssh/configfile, 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 and add or enable
the
cw-codexSSH host. -
Choose
/workspace/projectas the remote project folder, following OpenAI’s SSH-host instructions. -
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:
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.
Local TUI over the same SSH access
To use the local TUI instead of the desktop app, start a separate app-server listener through SSH. Keep this terminal open:0.154.0 installed, connect the local TUI:
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 verified interfaces 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. The following commands use those examples’ project path and connection method. For the SSH example, 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
- Sandbox SDK
Keep results and stop
The following commands apply to Run Codex CLI in a sandbox and Connect your local CLI to Codex App Server. For the SSH example, follow Reconnect and stop the SSH sandbox. Forcws-agent, save a workspace snapshot and stop compute:
cws-agent down [SANDBOX-NAME] --no-snapshot.
The direct SDK example doesn’t create a persistent mount. Before you stop the
sandbox, retrieve results with
file operations.
Then stop the sandbox:
Troubleshoot
Use the following checks to troubleshoot common issues:- Authentication fails: distinguish sandbox provisioning credentials, Codex model authentication, and the app-server connection token. They serve different purposes.
- App-server flags are rejected: compare local and sandbox
codex --versionoutput. This example requires the documented WebSocket and token-auth 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 app-server alone doesn’t enable it.