Skip to main content
Run Codex against a repository in a CoreWeave sandbox. Run Codex CLI inside the sandbox, connect your local CLI to Codex App Server, or use the desktop and mobile apps with a remote project. In all three options, the agent process, workspace, and command execution stay in the sandbox. These examples send model requests to OpenAI.
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.
In your local terminal, replace [WANDB-API-KEY] with your W&B API key, then load the sandbox credential:
The sandbox creation examples set an 8-hour sandbox lifetime. This is a maximum wall-clock lifetime, not an inactivity timer. Stop the sandbox when you finish. Model usage and sandbox compute can incur separate charges.

Run Codex CLI in a sandbox

Use cws-agent to launch a sandbox and attach your terminal. Both the Codex TUI and agent process run inside the sandbox.
  1. Follow the cws-agent installation instructions. For API-key authentication, export OPENAI_API_KEY locally before launch. The tool passes it to the sandbox and stores it through Codex’s login command.
  2. 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 native retains Codex’s own permission settings. The wrapper otherwise defaults to bypassing approval prompts. See cws-agent permission modes.
  3. 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.
  4. Complete Check the session. To reconnect later while the sandbox runs, use the same connect command. To resume a saved Codex conversation, see cws-agent sessions.

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 require cws-agent or configure snapshots.
OpenAI marks the app-server WebSocket transport experimental and unsupported for production workloads. This example exposes a public endpoint: CoreWeave supplies Transport Layer Security (TLS), while app-server checks a bearer token. Anyone with that token can control the agent within its configured permissions. Keep it separate from your OpenAI and sandbox API keys. OpenAI recommends Secure Shell (SSH) or virtual private network (VPN) connectivity instead of public app-server listeners in its Remote guidance. For that approach, use Local TUI over the same SSH access.

Prepare the local client

Use Python 3.12+, Node.js 22+, and uv. Install matching Codex versions locally and in the sandbox. This example pins 0.154.0:
Export your OpenAI API key, then generate a separate app-server connection token. In the same local terminal you use to connect, replace [OPENAI-API-KEY] with your OpenAI API key, then run:

Create the sandbox and start app-server

Save the following in the create_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
Replace [REPOSITORY-URL] with your public repository URL, then run the script:
Keep the printed sandbox ID and remote URL. The script leaves compute running after setup completes. An assigned URL confirms routing, not app-server readiness or login.

Connect and verify

Replace [REMOTE-URL] with the printed wss:// URL:
The token flag takes an environment-variable name, not the token itself. The --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:
Keep the token for later connections from the same shell. Connecting again doesn’t by itself select an existing conversation. Use the remote client’s session picker or resume flow and confirm the repository and conversation before continuing. A new token doesn’t authenticate against the existing server’s stored hash. For a programmatic client, app-server also provides JSON remote procedure call (JSON-RPC) methods to start and resume threads, send turns, handle approvals, and stream events. Use the app-server protocol reference with the same authenticated endpoint. You don’t need a custom chat user interface (UI) for the TUI flow.

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:
The generated SSH configuration uses the absolute path of this Python interpreter to run the TLS forwarder. Keep the Python installation and output directory available while you use the sandbox. Create a dedicated SSH key, then load it into your running SSH agent. Choose an unused filename and enter a passphrase when prompted:
The private key stays on your computer. The setup script copies only the public key into the sandbox.

Create the SSH sandbox

Save the following in the create_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.
create_codex_ssh.py
Replace [REPOSITORY-URL] with a public Git repository URL, and choose a new output directory outside your repository:
Successful setup prints the location of the 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:
The output should include 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.
  1. Copy the generated Host cw-codex block from the ~/.ssh/cw-codex-session/ssh_config file into the ~/.ssh/config file, before any Host * defaults. Replace an existing Host cw-codex entry rather than adding a duplicate.
  2. Run ssh cw-codex 'codex --version'. Resolve authentication or host-key errors before continuing.
  3. In the desktop app, open Settings > Connections and add or enable the cw-codex SSH host.
  4. Choose /workspace/project as the remote project folder, following OpenAI’s SSH-host instructions.
  5. Open that remote project and start a conversation. Ask Codex to write a unique, non-secret value to the /workspace/project/sandbox-proof.txt file.
  6. From your terminal, verify the result independently:
The file content should match the value you requested. The desktop app starts the remote app-server using the SSH user’s login shell. Codex must be installed and authenticated for that user. See OpenAI’s desktop SSH setup.

Reconnect and stop the SSH sandbox

While the sandbox runs, use the same cw-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:
Stop the sandbox using its saved ID:
This example has no persistent volume or snapshot. Stopping or expiry removes access to its files, login state, and endpoint. To start again, create a new sandbox and output directory, then replace the 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:
In a second terminal, forward a local port to that listener and keep the connection open:
In a third terminal with matching Codex 0.154.0 installed, connect the local TUI:
This listener is reachable through the SSH tunnel and is separate from the app-server managed by the desktop app. Sharing a conversation between the two hasn’t been verified. OpenAI documents the local TUI connection as experimental. When you finish, close the TUI, stop the listener, and close the forwarding connection. The sandbox continues running until you stop it.

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’s codex 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 direct codex --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:
If prompted, approve the write. Exit the TUI, then verify the file independently from your local terminal using the command for your setup:
The matching value confirms that the agent wrote to this sandbox’s filesystem. It doesn’t demonstrate mobile pairing or access from another app.

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. For cws-agent, save a workspace snapshot and stop compute:
If snapshot creation fails, inspect the reported error before you retry. To stop without saving, use 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:
Exiting the TUI doesn’t stop compute. When you stop the sandbox or it expires, its processes end and its public endpoint disappears. To restart compute, restore any saved files and start Codex again. Snapshots don’t preserve a running app-server process. 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 the app-server connection token. They serve different purposes.
  • App-server flags are rejected: compare local and sandbox codex --version output. 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.
Last modified on September 24, 2026