Codex remote environments

The Codex CLI can work away from the terminal you type in, in two ways. Both reach the box over SSH by its name (fig here; yours are in prized box ls), which prized setup adds to ~/.ssh/config, so nothing on the box listens on a public port. Both use parts of Codex that OpenAI marks experimental; this page was checked with Codex 0.166.0.

For agents that keep working with the lid closed, use the first. The ChatGPT desktop app has its own SSH connection to a box: Codex remote.

11. Sign Codex in on the box

In your project folder:

prized setup --sync --agent codex

This syncs the folder to ~/code/myproject on the box and signs Codex in there with a sign-in of its own (Run Codex in the cloud).

22. Add codex-box to your shell

Paste this into ~/.zshrc or ~/.bashrc, then open a new terminal:

codex-box() {
  local box=${1:?usage: codex-box BOX [resume --last | agents]} dir out sock; shift
  dir=${CODEX_BOX_DIR:-code/$(printf %s "${PWD##*/}" | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9._' - | sed 's/^[._-]*//; s/-*$//')}
  out=$(ssh "$box" "bash -lc 'codex app-server daemon start >/dev/null 2>&1 || exit 3; cd ~/$dir || exit 4; echo \$HOME \$PWD'") || { echo "codex-box: Codex did not start on $box, or ~/$dir is not there" >&2; return 1; }
  sock="$HOME/.codex/prized-$box.sock"
  pkill -f "L $sock:" 2>/dev/null
  ssh -fN -o ExitOnForwardFailure=yes -o StreamLocalBindUnlink=yes -L "$sock:${out%% *}/.codex/app-server-control/app-server-control.sock" "$box" || return
  codex "$@" --remote "unix://$sock" -C "${out#* }"
}

It starts Codex's background server on the box, forwards its socket over SSH to ~/.codex/prized-BOX.sock, and opens the Codex terminal UI in the box's copy of the folder you are in. CODEX_BOX_DIR=code/other codex-box fig picks another folder under the box's home.

33. Give Codex a task, then close the lid

cd ~/code/myproject
codex-box fig

The task runs in the background server on the box. Leave with /quit, close the terminal or close the laptop, and it keeps working; Ctrl+C while Codex works interrupts the turn instead.

• Approvals wait for you. A turn that asks for approval waits until you attach, so set the sandbox and approvals before you leave (Run Codex in the cloud).
• Auto-pause. Codex's background server has no terminal on the box, so it counts as use only through sustained CPU or network traffic. Before a long run, prized box auto-pause fig off, and switch it back after (Auto-pause).

44. Attach again

From the same folder:

codex-box fig resume --last

This opens the last conversation in that folder, finished or still streaming. codex-box fig agents lists the chats on the box, including ones started in a prized ssh session.

Laptop Codex, commands on the box

Codex reads remote environments from ~/.codex/environments.toml. With this file, every new Codex session on your laptop runs its commands and file edits on the box:

default = "fig"

[[environments]]
id = "fig"
program = "ssh"
args = ["fig", "bash", "-lc", "'exec codex exec-server --listen stdio'"]

Codex sends the path of the folder you started it in, so that path has to exist on the box. From your project folder, link the synced copy to the same path there:

name=$(printf %s "${PWD##*/}" | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9._' - | sed 's/^[._-]*//; s/-*$//')
ssh fig "sudo mkdir -p '$(dirname "$(pwd -P)")' && sudo ln -sfn ~/code/$name '$(pwd -P)'"

• It stops with the laptop. The agent runs on your laptop: when Codex quits, the box ends the commands it started, and when the laptop sleeps they end once its SSH connection drops.
• Back to local. Delete the file, or set default = "local", then start Codex again.

Troubleshooting