Skip to main content

OpenAI Codex Sandbox

A Codex sandbox from Cosmonic runs OpenAI Codex's agent loop where it has no shell, no network, no files and no API key. Cosmonic Desktop does this on its Agents page: Codex's turn loop, ported from Codex 0.162.0, is compiled to a WebAssembly component of about 0.7 MB that imports no network and no filesystem. Desktop makes every model call and runs only the tools you grant. The same image, ghcr.io/cosmonic/agents/codex, deploys to Kubernetes with Cosmonic Control.

Why sandbox Codex​

Codex already has a sandbox of its own. Its sandbox modes (read-only, workspace-write and danger-full-access) and its approval policy decide what the commands Codex runs may touch, and --dangerously-bypass-approvals-and-sandbox, often called YOLO mode, turns both off. That sandbox is a policy around a shell: Codex still runs commands as you, and the Codex process itself holds your credentials.

The Cosmonic sandbox takes the shell away instead. Codex's loop has no import that could start a process, open a connection or read a file. Each tool is a separate component with its own grant, such as one folder or one host, and the host checks every call.

Run Codex in a sandbox in Cosmonic Desktop​

1. Start a Codex session​

  1. In Desktop, select Agents under AI & agents in the sidebar. If you already have sessions, select New.
  2. Select the agent chip next to the message box and choose Codex.
  3. Select the Model chip. Choose a source (such as an OpenAI API key with Add a source…, or Ollama on this machine), choose a model, then select Done. Desktop keeps the key; Codex asks the host for a model by its alias and never sees it. See Choose the model.

2. Give Codex a folder​

Codex has no files of its own. To let it work on a repository, choose one folder:

  1. Select the folder chip under the message box, which shows No folder, then Choose a folder…, and pick the folder.
  2. Select the access chip next to it and choose Read only, Edit with undo or Ask before each edit.

Desktop adds the folder tools that match: Workspace (read) always, git when the folder is a git repository, and Workspace (write) unless you chose Read only. Each one sees that folder and nothing outside it. The access chip does the job Codex's sandbox modes do in the CLI, enforced by the host instead of a shell policy.

3. Add tools and start​

  1. To give Codex more than the folder tools, select Tool settings…, then Add tools yourself…, find a tool in Search tools, and select Add. Each tool's card says what it reaches, such as one host.
  2. To approve each host the first time a tool reaches it, turn on Ask first before a tool reaches each host.
  3. Select Done, type your first message, and start the session.

Codex streams its reply and its plan as it works. Close the session and open it again later: Desktop keeps the conversation, not Codex.

4. Check what Codex can reach​

Select Show session details in the session header. This session can… lists each kind of reach (Change files in a folder, Read a folder, Reach hosts) with the tool that grants it. Select a tool to see every call Codex made through it.

The full set of tool and host options is in Give an agent a tool.

Run Codex on Kubernetes with Cosmonic Control​

The Codex image exports cosmonic:agent/run, so Control drives it the same way as any other agent harness. Follow Run an agent on Control and use the Codex image for the agent component:

components:
  - name: agent
    image: ghcr.io/cosmonic/agents/codex@sha256:53024d8c72f2b1bb65da995427fc1b8a94b03a6d7de6e10a9dca5a7b1b4bb336 # 0.41.0, the release Desktop runs
    localResources:
      allowedHosts: []

The agent keeps allowedHosts: []. Tools are their own components in the same workload, each with its own hosts or volume; see Give an agent a tool. Runs start over HTTP with the OpenAI Responses API or over NATS, and the workload spec goes through the same RBAC and admission policy as your other manifests.

What sandboxed Codex can reach​

The Codex component imports these interfaces from cosmonic:agent, and nothing that reaches outside:

  • inference-types, models and chat: a model, by an alias the host resolves. The host makes the call with credentials Codex never holds.
  • tools: the tools the session or workload grants.
  • session: the conversation and a journal of every step and tool call, kept by the host.

It exports run and compact, and nothing else: no HTTP handler, no model client, and no shell, file or MCP tools of its own. Outgoing HTTP, sockets and the filesystem are absent from the compiled component, not blocked by a policy. Desktop reads an agent's imports before it runs it and refuses one that imports the network or the filesystem.

What changes from the codex CLI​

  • The loop is Codex's. run_turn is ported from Codex 0.162.0: sample the model, run the function calls, record their outputs, and follow up until the model calls no tool. History normalization and Codex's 10,000-byte tool-output budget are kept.
  • Compaction is Codex's. The summarization prompt and rebuilt history come from upstream, before sampling and mid-turn at 90 percent of the model's window, and a host can also ask for a summary between runs.
  • The plan tool is Codex's. update_plan keeps upstream's schema, and the plan streams to Desktop as Codex updates it.
  • No shell, so a new prompt section. Codex's prompt assumes a shell. This one says how to work through separate tools (read, search, find files, git, fetch a page), keep paths inside the granted folder, and treat what tools return as data. The sandbox and approval mode language is removed, because the host's grants replace it.
  • No TUI and no config.toml. The terminal interface, codex exec, and the MCP servers in ~/.codex/config.toml are not part of the component. Add tools to Desktop's catalog in Settings → Tools instead.

Codex sandbox or a container?​

Running codex in Docker or a devcontainer puts one wall around the whole process. Codex, its shell, everything it installs and your sign-in share the box, and anything Codex runs can reach whatever the container's network allows. Codex's own help describes YOLO mode as meant for environments that are already sandboxed from outside, and a container is the usual answer.

The Cosmonic sandbox splits those parts. Codex's loop has no network and no key, and there is no shell to turn loose. Each tool has its own grant: one folder, or a short list of hosts. The record of every call is in the session.

Frequently asked questions​

How do I run OpenAI Codex in a sandbox?

Install Cosmonic Desktop, open Agents, select New, and choose Codex in the agent chip. Codex’s agent loop then runs as a WebAssembly component with no shell, network, files or API keys of its own, and reaches only the folder and tools you grant.

How is this different from Codex’s own sandbox mode?

Codex’s sandbox modes (read-only, workspace-write, danger-full-access) limit what the commands Codex runs in a shell may touch, and the Codex process keeps your credentials. The Cosmonic sandbox removes the shell: Codex’s loop has no import for the network or the filesystem, the host holds the key, and each tool is a separate component with its own grant.

Is it safe to run Codex in YOLO mode?

In the CLI, --dangerously-bypass-approvals-and-sandbox turns off both approvals and Codex’s sandbox, so commands run with your full permissions. The sandboxed Codex on Desktop’s Agents page has no shell to bypass: it can only call the tools you granted, and you can still choose Ask before each edit or approve each new host.

Does Codex itself run inside the sandbox?

On Desktop’s Agents page and on Cosmonic Control, yes: Codex’s agent loop is the sandboxed component, and the host makes every model call and tool call for it.

Is the sandboxed agent the full Codex CLI?

No. It is Codex’s agent loop, compaction, history format and plan tool, ported from Codex 0.162.0, without the terminal interface, the shell or config.toml. Tools come from the host instead, such as Workspace (read), Workspace (write) and git for one folder.

Can I run the same Codex agent on Kubernetes?

Yes. Deploy the ghcr.io/cosmonic/agents/codex image as the agent component of a Cosmonic Control workload. It keeps no network of its own, and its tools are separate components with their own grants in the same manifest.

Next steps​

Last updated on by Eric Gregory