How to run Codex in the cloud

Codex can edit files, run commands, and test changes on a remote machine instead of using your laptop’s development environment. The cloud option you choose determines who manages that machine, how you access it, and which project resources are available.

This guide explains the hosting choices, then shows you how to run Codex in the cloud with Northflank: create a workspace, authenticate, fix a failing test, preview the application, and retain your work between sessions.

Use OpenAI’s hosted environment for its built-in cloud workflow, a managed workspace for configurable development infrastructure, or a VM when you want to administer the machine yourself.

In the web or desktop interface, choose Work in → Cloud and select a published environment. To create one, connect your GitHub repositories, let Codex prepare the dependencies and tools, review the setup, and select Publish. Then start a task using that environment. Access depends on your account and workspace settings.

Each task gets an isolated workspace from the published environment. This Codex Cloud workflow is separate from running the Codex CLI on Northflank. OpenAI also retains a legacy environment workflow for certain integrations, so use the instructions for the interface you are using.

Choose a VM when you want to maintain the server yourself; choose a managed workspace when you want the platform to provide workspace configuration, access, and lifecycle controls.

On a VM, you install the Codex CLI, authenticate, and prepare your project. You also maintain the operating system and arrange for the process to survive an SSH disconnection. Size the machine for your builds, tests, and supporting services.

Northflank brings those workspace controls into its dashboard. Your team can configure a coding environment, expose an application preview, monitor resources, and pause the workspace while retaining its files. This serves both shared development workflows and individual tasks without requiring a separate server-management setup.

You can use Northflank’s managed cloud or bring your own cloud (BYOC), where Northflank acts as the control plane to run Codex and its workspace inside your cloud account and VPC. The model service remains separate from the coding workspace.

Connect a development branch and work through a task you can review. Create a Cloud Harness, or book a demo to discuss your team’s infrastructure requirements.

You need a Northflank account, Codex authentication, and a Git integration if you want to connect a repository:

• A Northflank account with permission to create a Cloud Harness in your project.
• A ChatGPT account with Codex access, or an OpenAI API key, for agent authentication.
• A Git integration if you want to connect an existing repository.

Use a development branch of your project, or create the standalone example below without connecting a repository. The example needs Node.js 24 LTS and no third-party packages. After creating the harness, run node --version in its shell and confirm v24.x; configure the runtime first if needed.

For a Northflank workspace or a VM, budget for hosting and Codex usage separately. Your ChatGPT subscription does not cover the compute you rent from another provider.

• ChatGPT sign-in: Codex usage follows the access and allowances available to your account and workspace.
• OpenAI API key: model requests are billed through your OpenAI Platform account at API rates, separately from a ChatGPT subscription.
• Workspace resources: Northflank has free, Pay-as-you-go, and Enterprise plans. Paid resources are prorated to the second; account for configured compute, retained storage, and applicable transfer.

The Codex CLI supports ChatGPT and API-key authentication. OpenAI-hosted Codex Cloud requires ChatGPT sign-in. Check which route you selected before running a long task, and pause unused workspace compute while accounting separately for any retained resources.

Create the workspace from the Northflank dashboard using the Cloud Harness quickstart.

1. Create or open a project. A project groups related resources. To create a project, select Create project, enter a name, choose Northflank Cloud or Bring Your Own Cloud under Deployment target, select a region, and create the project. Then open Harnesses and select Create harness.
2. Select Codex as the coding agent.
3. Name the Cloud Harness, for example codex-health-check.
4. Select the environment where it should run.
5. Choose authentication. Under Authentication, select an API key or a linked account.
6. Choose a repository. Under Repository, select an existing repository and branch, create a new repository, or continue without one.
7. Review Advanced options. Choose privacy and review runtime variables, the runtime image, resources, and workspace storage. Select Team privacy if you need SSH or authorised teammates to connect; Private workspaces use the in-app terminal. Keep Persist workspace files enabled to retain your work. Privacy and persistence cannot be changed after creation.
8. Select Create Harness. Northflank opens the terminal. Complete the agent sign-in if prompted.

For BYOC, your cluster also needs a supported microVM runtime and compatible nodes; follow the prerequisites in the linked quickstart before creating the harness.

The remaining walkthrough takes place in this Northflank Cloud Harness. Use the Northflank dashboard for workspace settings, the Cloud Harness shell for terminal commands, and the Codex session for prompts and slash commands. A shell reached through SSH still runs commands in the remote harness. Prepare the project before asking Codex to edit files.

Choose an API key or linked account when creating the Cloud Harness, then complete the Codex sign-in shown in its terminal. OpenAI’s authentication guide distinguishes subscription access from API-key usage.

If ChatGPT browser login cannot complete from the remote machine, device-code authentication is an alternative. Enable it in your account’s security settings or through your workspace administrator, then run this in the Cloud Harness shell:

codex login --device-auth

Open the displayed link in your local web browser, sign in, and enter the one-time code. This authenticates Codex on the remote machine. Device-code login is currently beta and must be allowed for your account.

For API-key authentication, use the harness’s authentication configuration. Keep the key out of project files, prompts, and Git commits.

In the Cloud Harness shell, enter your existing project’s directory, follow its setup instructions, install dependencies, and run its tests before editing. Review unfamiliar installation scripts before running them. The example below needs no package installation.

In the Northflank dashboard, open your Cloud Harness, select Environment in the right sidebar, and select Edit. Add the runtime variables or secret files your application requires, then select Update & restart to apply them. These controls are part of Cloud Harness configuration.

Add only the development credentials the project needs. Keep baseline test results so you can identify new failures.

Inside the Codex session running in your Cloud Harness, enter /permissions to review the active permission profile. Use /status to inspect session configuration. These are Codex commands, not commands for the Cloud Harness shell.

The Cloud Harness provides the remote workspace. Codex’s command sandbox separately restricts filesystem and network access; approval settings determine when an action needs review. Check the active configuration rather than assuming a particular policy is enabled by Northflank.

On Linux, review sandbox startup errors and the runtime’s bubblewrap and user-namespace support. If a test cannot bind a local port or a command is blocked, identify the specific restriction before approving broader access. Project prompts and instructions do not enforce a security boundary.

Use /plan when you want Codex to propose its approach before implementation. Connected tools may have their own access controls beyond the shell sandbox.

Inside your Northflank Cloud Harness, give Codex a small failing test with a clear expected result. Use your project’s tests, or follow the optional example below: create the files and run the baseline in the Cloud Harness shell, then give the task prompt to the Codex session.

This example serves a /health endpoint that incorrectly returns starting instead of ok. It also tests that an unknown route still returns HTTP 404.

In the Cloud Harness shell, create and enter a new directory. If the terminal currently shows Codex’s prompt, use /quit to leave the CLI session and return to its shell first. Run these commands remotely in the harness:

mkdir /home/harness/codex-cloud-example
cd /home/harness/codex-cloud-example

Copy this whole block into the Cloud Harness shell, including the final EOF line. It creates server.mjs in the directory you just entered:

cat > server.mjs <<'EOF'
import { createServer } from 'node:http';

export function createApp() {
  return createServer((request, response) => {
    if (request.method === 'GET' && request.url === '/health') {
      response.writeHead(200, { 'Content-Type': 'application/json' });
      response.end(JSON.stringify({ status: 'starting' }));
      return;
    }
    response.writeHead(404);
    response.end('Not found');
  });
}

if (process.argv.includes('--serve')) {
  createApp().listen(3000, '0.0.0.0');
}
EOF

In the same Cloud Harness shell, copy this block to create server.test.mjs alongside it:

cat > server.test.mjs <<'EOF'
import test from 'node:test';
import assert from 'node:assert/strict';
import { createApp } from './server.mjs';

async function withServer(check) {
  const server = createApp();
  await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
  try {
    await check(`http://127.0.0.1:${server.address().port}`);
  } finally {
    await new Promise(resolve => server.close(resolve));
  }
}

test('health check returns ready status', () => withServer(async base => {
  const response = await fetch(`${base}/health`);
  assert.equal(response.status, 200);
  assert.deepEqual(await response.json(), { status: 'ok' });
}));

test('unknown route returns 404', () => withServer(async base => {
  assert.equal((await fetch(`${base}/missing`)).status, 404);
}));
EOF

Still in /home/harness/codex-cloud-example in the Cloud Harness shell, run the baseline test:

node --test server.test.mjs

You should see one passing test and one failing test: the health response contains starting, while the test expects ok. If you instead see a missing runtime or permission error, resolve that before asking Codex to fix the application.

From /home/harness/codex-cloud-example in the Cloud Harness shell, run codex to open the agent session. Enter /plan, then paste this prompt into the Codex session:

Work in /home/harness/codex-cloud-example.
Run node --test server.test.mjs and identify why the health check fails.
Explain the smallest fix before editing.
Keep the existing tests unchanged and do not add dependencies.
After I approve the plan, fix the endpoint and rerun both tests.
Report the changed file and the test results.

After reviewing the plan, approve proceeding with implementation and allow the relevant edit and test actions. Then use /quit to leave the Codex session and return to the Cloud Harness shell and run node --test server.test.mjs yourself from the example directory. Both tests should pass, and the endpoint should return { "status": "ok" }. Review server.mjs to confirm that Codex fixed the response rather than weakening the test.

If you are working in an existing Git repository, run these commands from its directory in the Cloud Harness shell before committing:

git status --short --untracked-files=all
git diff
git diff --cached

If you created the standalone example without Git, skip these Git commands. Keep the two files in the persistent workspace to return later, and copy their contents somewhere outside the harness before deleting it.

For a Git-backed project, open untracked files separately because they are not included in git diff. Check for unrelated edits and secrets, then commit and push through your normal review process. Keep the task and test results with the change so your agent execution audit trail connects the work to its review.

In the Cloud Harness shell, return to the example directory, start the server, and leave it running:

cd /home/harness/codex-cloud-example
node server.mjs --serve

It listens on port 3000 and binds to 0.0.0.0. Next, switch to the Northflank dashboard, open the same Cloud Harness, and select Networking in the right sidebar:

1. Select Add port.
2. Enter 3000 and select HTTP.
3. Enable Publicly expose to make this example’s preview accessible from the internet.
4. Select Save changes.

In your web browser, open the public endpoint shown by Northflank and append /health. After the fix, it should display { "status": "ok" }; the root URL returns 404 intentionally. For your own application, use its actual port and bind the server to 0.0.0.0.

Before sharing a public preview, check for debug routes, sensitive data, and missing authentication. Remove public access when the review is complete.

Port exposure controls incoming connections. If you also need outbound restrictions on your own cluster, configure BYOC network policies; without egress rules, outbound traffic is allowed.

You can connect from your local terminal when the Cloud Harness is running, uses Team privacy, and you have permission to access it. Private harnesses use the in-app terminal, including for their creator.

Install and authenticate the Northflank command-line interface (CLI). To connect to your Cloud Harness locally, open its overview in the Northflank dashboard, select Connect under Local access, and copy the generated command. Run it in your local terminal. It has this form:

northflank dev ssh --projectId YOUR_PROJECT_ID --harnessId YOUR_HARNESS_ID

Use the dashboard-generated command with your actual project and harness IDs.

In the Northflank dashboard, open your Cloud Harness and select Observe in the right sidebar to check CPU and memory while Codex runs builds or tests. If resources are constrained, adjust them under Options → Update options, then rerun the task.

In Northflank, pause the Cloud Harness to return to the work later, or delete it after saving the files you need. An active Cloud Harness keeps running until you pause or delete it; closing your terminal does not stop it.

To pause your Cloud Harness, open its overview and select the Pause harness icon in the top-right corner. With persistent workspace storage enabled, files under /home/harness survive, while terminal sessions and running processes stop. Select Resume harness from the overview when you want to continue, then restart any development servers or other processes you need.

Persistent storage defaults to enabled at creation. If you disabled it, files are lost when the container restarts, is redeployed, or stops.

Before deleting, push your commits or export the files you want to keep. Open the three-dot menu in the top-right corner, select Delete harness, and confirm. Deleting a Cloud Harness permanently removes its associated workspace. Revoke temporary credentials at the services that issued them when they are no longer needed.

Check whether the failure is in authentication, project setup, application networking, or workspace state before changing permissions or resources.

Create a Cloud Harness, connect a development branch, and let Codex work on one change you can test and review. Once that workflow works for your project, reuse the environment with clear access and cleanup rules.

Cloud execution changes where your project runs; workspace settings determine how you access it and retain your work.

An active Northflank Cloud Harness keeps running until you pause or delete it, so closing your browser or local terminal does not stop the workspace. A task can still pause for input, fail, or reach an account limit; a running workspace does not guarantee that the task finishes unattended.

No. A Northflank Cloud Harness is the remote workspace where Codex runs. Codex’s command sandbox restricts file and network access for its commands inside that environment. Review both the agent permissions and the workspace’s credentials and networking.

No. The CLI executes against the files and tools on the machine where you launch it. In a Northflank Cloud Harness, that machine is the remote workspace. OpenAI’s Codex Cloud uses its own published environments and hosted task workflow.

Yes. On Northflank, teammates with the required permissions can access the same Cloud Harness when it uses Team privacy. Private privacy restricts workspace access to its creator. Share access only with collaborators authorised to use the repository and development credentials.

Yes. With bring your own cloud (BYOC), Northflank acts as the control plane, managing Kubernetes to run Codex and its workspace inside your cloud account and VPC. Your team owns the underlying cloud resources; the model service remains separate.

Yes. You can keep files between Codex sessions in a Northflank Cloud Harness with persistent workspace storage enabled. Files under /home/harness survive pause and resume, but terminal sessions and processes stop. Restart the processes you need after resuming, and export any files you want to keep before deleting the Cloud Harness.

Continue with the infrastructure and access controls around your coding workspace:

• What infrastructure do AI agents need to run code safely?
• What should an audit trail for AI-agent code execution contain?
• AI-agent sandbox security checklist
• How to give your AI agent a secure computer