Skip to main content
Run Codex against a repository in a CoreWeave sandbox. You can run the Codex command-line interface (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 use OpenAI for model requests.

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
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 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.

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 require cws-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:
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 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.
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, 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:
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. 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:
OpenAI marks the app server WebSocket transport experimental and unsupported for production workloads. This example binds the listener and forwarded port to loopback addresses and carries traffic through SSH. Other processes on those hosts can reach the loopback ports. Use trusted hosts.
Connect the local CLI through an SSH tunnel:
  1. 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 -t option allocates a remote terminal so Ctrl+C reaches the listener.
  2. In a second terminal, forward a local port to that listener and keep the connection open:
  3. In a third terminal, connect the local TUI and explicitly select the remote project directory:
  4. Confirm that the TUI shows /workspace/project, then complete Check the session. If the connection fails, inspect the retained startup output:
To continue a saved conversation while the listener is running, restore the SSH tunnel, then open the remote session picker:
Select the conversation to resume. To start a new conversation instead, use the original 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.
  1. In the ~/.ssh/cw-codex-session/ssh_config file, copy the generated Host cw-codex block. In the ~/.ssh/config file, paste it 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, then add or enable the cw-codex SSH host.
  4. Choose /workspace/project as the remote project folder and save the project.
  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.

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 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:
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.

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.

Keep results and stop

For the local CLI and desktop app, 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. 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 --version output. 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.
Last modified on September 30, 2026