How to run Codex headlessly on a remote computer

Codex CLI can run on a remote computer just as it runs in a local terminal. The remote host supplies the filesystem, tools, and uptime; your laptop becomes a client used to start, inspect, and review the work.

"Headless" describes a workflow without a continuously attended graphical interface. It does not remove the need for authentication, approvals, a durable output, or a machine that stays available.

Choose the remote-host model

There are three common ways to run Codex away from a laptop:

• a CI runner for bounded automated jobs,
• a raw VPS that your team configures and maintains,
• a managed persistent computer with browser or terminal access.

Use CI when the task belongs inside a repeatable pipeline. Use a VPS when you want maximum infrastructure control. Use a persistent development computer when people and agents should return to the same project environment across tasks.

OpenAI also offers managed Codex workflows. Compare those with a self-operated CLI based on whether you want OpenAI or your team to own the execution environment.

Prepare the host

Install Git, the repository's language runtimes, build dependencies, and Codex CLI using the current OpenAI Codex documentation. Create a non-root developer user and restrict inbound access.

Authenticate through a supported method. Do not copy browser cookies or unrelated personal credentials to the server. Use scoped repository access and short-lived tokens where possible.

Clone the repository and confirm that a normal human workflow succeeds before adding the agent:

git clone <repository-url>
cd <repository>
corepack pnpm install --frozen-lockfile
corepack pnpm test

Replace the commands with the project's documented setup.

Give every task a worktree

Create an isolated checkout rather than allowing Codex to edit the shared main working directory:

git fetch origin
git worktree add ../app-codex-142 -b agent/codex-142 origin/main
cd ../app-codex-142
codex

State the objective, allowed scope, acceptance criteria, and required verification. Ask Codex to stop and report when it needs authority outside that boundary.

Keep the process available

If you start Codex through SSH, use a persistent terminal or the host's supported session manager. tmux keeps a remote shell alive when the SSH connection drops:

tmux new -s codex-142
codex

Detach and reconnect later with tmux attach -t codex-142.

This protects against a client disconnect. It does not automatically recover the process after a host reboot or application failure. Use Git checkpoints and process supervision when automatic recovery is required.

Review the result through Git

Before pushing, inspect the diff and rerun the relevant checks. The ideal handoff contains:

• a narrowly scoped branch,
• an explanation of the change,
• tests and their output,
• known limitations or follow-up work,
• no unrelated formatting or dependency churn.

Push the branch and open a draft pull request. Keep merge rights and deployment credentials separate from the agent unless the workflow has an explicit reason to grant them.

Use Matrix OS as the remote computer

Matrix OS provides a persistent cloud computer with browser and terminal access. Codex CLI can run alongside other terminal agents and project services, with separate Git worktrees used to keep tasks isolated.

Matrix removes the laptop from the runtime path and manages more of the computer setup than a raw VPS. It does not replace branch protection, backups, agent permissions, or review.

For local lifecycle details, see How to keep Codex CLI running after you close your laptop. For parallel work, see How to run Claude Code and Codex in parallel.

FAQs

Does Codex CLI require a graphical interface?

No. It is terminal-native. The exact modes and automation flags depend on the current Codex CLI, so use OpenAI's official documentation when scripting it.

Will Codex continue if my laptop disconnects?

Yes, if Codex runs on a remote computer and the remote process remains active. A disconnect only removes your view of that process.

Will tmux recover Codex after a server reboot?

No. tmux helps with terminal disconnections, not full host restarts. Preserve work in Git and configure appropriate process supervision if the job must restart automatically.

Can Codex and Claude Code share one remote machine?

Yes. Give each agent a separate worktree, branch, ports, and task. Merge through a normal review queue rather than letting both edit the same checkout.