# Codex Cloud Tutorial: Setup, GitHub & Your First PR

Learn Codex Cloud step by step: connect GitHub, publish an environment, fix a bug, review tests, and open a PR. Includes pricing and limitations.

Author: Vladislav Guzey
Published: 2026-10-11
Canonical: https://proflead.dev/posts/codex-cloud-tutorial/


Hey devs! Codex Cloud lets OpenAI's coding agent work on your project in a remote environment. It can read code, edit files, and run commands while your computer is asleep. You can return to the task from the web, mobile, or desktop app. [OpenAI's Codex Cloud overview](https://learn.chatgpt.com/docs/cloud)

I started with a small JavaScript project and three short requests: explain the code, fix an issue, and create a pull request. This guide walks through the same setup so you can try it with your own project.

## Watch the Codex Cloud video tutorial

Follow the setup and GitHub workflow in my [video tutorial, “How to Use Codex Cloud: From GitHub to Your First Pull Request”](https://youtu.be/GPrPPNCu1Uw).

<div class="videoWrapper">
  <iframe width="100%" src="https://www.youtube.com/embed/GPrPPNCu1Uw" title="How to Use Codex Cloud: From GitHub to Your First Pull Request" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
</div>

## What is Codex Cloud?

Codex Cloud runs coding tasks on a remote virtual machine. You give it a project and a request, and it works with the files and tools available there.

There are four terms you'll see throughout the setup:

<table>
<thead><tr><th scope="col">Term</th><th scope="col">What it means in this walkthrough</th></tr></thead>
<tbody>
<tr><td>Repository</td><td>The GitHub project containing your code.</td></tr>
<tr><td>Environment</td><td>The reusable project setup: repositories, installed tools, dependencies, and access settings.</td></tr>
<tr><td>Task</td><td>One conversation and its working files, starting from a published environment.</td></tr>
<tr><td>Pull request, or PR</td><td>Proposed code changes submitted through GitHub for review before merging into another branch.</td></tr>
</tbody>
</table>

The environment and the task have different jobs. You prepare and publish the environment so tasks can use it. Each new task gets its own workspace. A follow-up in an existing task continues with that task's files and context. [Cloud environments](https://learn.chatgpt.com/docs/environments/cloud-environments)

### Codex Cloud vs local Codex

Choose based on where the work needs to run:

<table>
<thead><tr><th scope="col">Your situation</th><th scope="col">Where I&#x27;d start</th></tr></thead>
<tbody>
<tr><td>A GitHub project with setup that can run remotely</td><td>Codex Cloud</td></tr>
<tr><td>A project that depends on files, running apps, or browser sign-ins on your computer</td><td>Local Codex</td></tr>
<tr><td>A task you want to leave running while your laptop sleeps</td><td>Codex Cloud</td></tr>
<tr><td>Frequent edits and checks in your existing editor</td><td>Local Codex or its IDE integration</td></tr>
</tbody>
</table>

Both workflows can produce code changes and pull requests. The practical difference is access to the working environment. Your laptop's files, processes, browser sessions, and VPN connection aren't automatically transferred to a cloud task. [Environment access](https://learn.chatgpt.com/docs/environments/cloud-environments), [my Codex in VS Code guide](/posts/codex-cli-in-vscode/)

## What you need before starting

Have these ready:

- A ChatGPT account with access to Codex Cloud in the workspace you're using.
- A GitHub repository you can connect. Start with a small project you understand, or a copy you can experiment with.
- A way to check the result: existing tests, runnable examples, or a specific behavior you can verify.

Codex Cloud uses **ChatGPT sign-in**. You don't need an OpenAI API key for this workflow. If your account supports email-and-password login, OpenAI requires MFA before cloud access; social-login and SSO requirements differ. [Authentication requirements](https://learn.chatgpt.com/docs/auth#secure-your-codex-cloud-account)

The current pricing guide lists cloud chats for Plus, Pro, Business, and Enterprise/Edu. Access also depends on workspace permissions. Free or Go access to other Codex features doesn't establish access to this cloud workflow. Check the [current plan comparison](https://learn.chatgpt.com/docs/pricing#feature-availability) before subscribing for it.

You can follow the cloud setup in a browser. Installing Node.js on your own computer becomes relevant if you want to rerun this JavaScript example locally.

## How to set up Codex Cloud and run your first task

### 1. Choose Cloud and create an environment

Open [ChatGPT](https://chatgpt.com/) on the web or in the desktop app and sign in. In the video, I open the sidebar's three-dot menu and choose **Codex**. Near the prompt field:

1. Open **Work in**.
2. Choose **Cloud**.
3. Open **Select environment**.
4. Choose **Create environment**.

If you already have a suitable published environment, select it and skip to the first-task step below. You can also create an environment through **Settings → Codex Cloud → Environments**. [Official setup steps](https://learn.chatgpt.com/docs/environments/cloud-environments#create-and-publish-an-environment)

<figure>
<a href="/assets/blog/codex-cloud-tutorial/01-choose-cloud.png" target="_blank" rel="noopener noreferrer" aria-label="Open screenshot at original size">
<img src="/assets/blog/codex-cloud-tutorial/01-choose-cloud.png" alt="Work in menu with Cloud selected and Choose environment visible" width="665" height="235" loading="lazy" />
</a>
<figcaption>Cloud selected in the Work in menu, with Choose environment available.</figcaption>
</figure>

### 2. Connect GitHub and select your repository

Connect GitHub if prompted, then select the repository Codex should prepare. My GitHub connection was already set up, so I could select the project directly.

When GitHub offers repository access choices, I usually select only the project I want to work on. Check the repository name and the access you're granting before continuing.

<figure>
<a href="/assets/blog/codex-cloud-tutorial/07-select-repository.png" target="_blank" rel="noopener noreferrer" aria-label="Open screenshot at original size">
<img src="/assets/blog/codex-cloud-tutorial/07-select-repository.png" alt="Create a cloud environment dialog with repository selection and Get started" width="1088" height="591" loading="lazy" />
</a>
<figcaption>Choose the GitHub repository for the cloud environment, then select Get started.</figcaption>
</figure>

Select **Get started**. Codex inspects the selected project and prepares its tools and dependencies. If it needs information or access, supply that during setup. [Create and publish an environment](https://learn.chatgpt.com/docs/environments/cloud-environments#create-and-publish-an-environment)

### 3. Read the setup report

My project used standalone JavaScript examples. Codex found Node.js already available, so I could publish the environment without installing extra dependencies.

<figure>
<a href="/assets/blog/codex-cloud-tutorial/02-setup-report.png" target="_blank" rel="noopener noreferrer" aria-label="Open screenshot at original size">
<img src="/assets/blog/codex-cloud-tutorial/02-setup-report.png" alt="Codex Cloud setup report with JavaScript checks and the Save and publish button" width="665" height="325" loading="lazy" />
</a>
<figcaption>The setup report shows the available tools, completed checks, and Save and publish button.</figcaption>
</figure>

A larger application may need a package installation, a database, or configuration values. Use **Edit environment** to add the environment variables your project needs. Follow the versions and commands declared by your project.

Before publishing, check:

- Did setup run the commands your project actually needs?
- Did any command fail, get skipped, or stop for missing access?
- Are the available tools and runtime versions appropriate for the project?
- Did setup leave anything unfinished?

If the report is unclear, try this suggested follow-up:

```text
Explain what you checked during setup.
List the commands you ran, any failures, and anything still missing.
Tell me whether the environment is ready for a coding task.
```

### 4. Save, publish, and wait for confirmation

Click **Save and publish** and wait for **Environment published**. Then return to Codex, choose **Cloud**, and select the published environment for your first task.

<figure>
<a href="/assets/blog/codex-cloud-tutorial/08-save-and-publish.png" target="_blank" rel="noopener noreferrer" aria-label="Open screenshot at original size">
<img src="/assets/blog/codex-cloud-tutorial/08-save-and-publish.png" alt="Codex Cloud setup report with Save and publish highlighted" width="1088" height="591" loading="lazy" />
</a>
<figcaption>Select Save and publish after reviewing the environment setup.</figcaption>
</figure>

<figure>
<a href="/assets/blog/codex-cloud-tutorial/03-environment-published.png" target="_blank" rel="noopener noreferrer" aria-label="Open screenshot at original size">
<img src="/assets/blog/codex-cloud-tutorial/03-environment-published.png" alt="Codex Cloud setup report with the Environment published confirmation" width="665" height="325" loading="lazy" />
</a>
<figcaption>The Environment published confirmation below the setup report.</figcaption>
</figure>

Saving stores configuration. Publishing makes the prepared environment available as the starting point for new tasks. If you later change the reusable setup, edit it, test the change, and **Republish**. Existing tasks keep their own state; start a new task to use the updated setup. [Publishing and saved state](https://learn.chatgpt.com/docs/environments/cloud-environments#reuse-and-update-saved-state)

### 5. Ask Codex to explain the project

My first message was:

```text
explain this repo
```

<figure>
<a href="/assets/blog/codex-cloud-tutorial/04-first-prompt.png" target="_blank" rel="noopener noreferrer" aria-label="Open screenshot at original size">
<img src="/assets/blog/codex-cloud-tutorial/04-first-prompt.png" alt="The explain this repo prompt in the composer with a cloud environment selected" width="665" height="135" loading="lazy" />
</a>
<figcaption>The first prompt, “explain this repo,” with a cloud environment selected.</figcaption>
</figure>

Codex explained the files and flagged a few search issues. That gave me a focused follow-up task.

For a first run on your own project, I'd make the request more explicit:

```text
Explain this repository to a developer joining the project.
Identify the main files, how to run the project, and how to check it.
Point out one small issue worth investigating and name the relevant files.
Do not edit files yet.
```

### 6. Request one focused fix

In the same task, I followed up with:

```text
fix the issues
```

That message had context: Codex had just listed the search issues. If you start a fresh task, describe the problem again instead of assuming it knows which issues you mean.

For this example, a more precise request would be:

```text
Fix the binary-search and jump-search boundary issues you identified.
Keep the standalone JavaScript examples working.
Add regression checks for empty arrays, single-item arrays,
missing targets, and targets in the final search block.
Run the relevant checks and report the commands and results.
Avoid unrelated refactoring or new dependencies.
```

A boundary case is a situation at the edge of the normal input. For an array with three items, the valid indexes are `0`, `1`, and `2`. A search must also handle an empty array or a target that doesn't exist.

### 7. Read the changes and reported checks

Read the change summary and test output before moving on. Ask which files changed, which checks ran, and whether anything still needs attention:

```text
Summarize the changes.
List the tests and commands you ran, their results, and any failures.
```

<figure>
<a href="/assets/blog/codex-cloud-tutorial/05-reported-test-results.png" target="_blank" rel="noopener noreferrer" aria-label="Open screenshot at original size">
<img src="/assets/blog/codex-cloud-tutorial/05-reported-test-results.png" alt="Codex task summary with changed files and test results" width="665" height="450" loading="lazy" />
</a>
<figcaption>Codex&#x27;s summary of the changes and test results.</figcaption>
</figure>

### 8. Create a pull request

Changes made in Cloud stay in the task's workspace until you ask Codex to publish them. To create a pull request, send:

```text
create a pr
```

Open the link Codex returns and review the changed files in GitHub.

<figure>
<a href="/assets/blog/codex-cloud-tutorial/06-open-pull-request.png" target="_blank" rel="noopener noreferrer" aria-label="Open screenshot at original size">
<img src="/assets/blog/codex-cloud-tutorial/06-open-pull-request.png" alt="GitHub pull request showing its description and changed files" width="600" height="515" loading="lazy" />
</a>
<figcaption>The pull request brings the proposed changes together for review.</figcaption>
</figure>

For a more detailed request, try:

```text
Create a pull request for these changes.
Describe the problem, the fix, and the validation commands and results.
Include any checks you could not run. Do not merge it.
```

## How to get Codex Cloud changes onto your computer

Your local checkout doesn't update automatically when Codex opens a pull request. Fetch and check out the PR branch to review the changes on your computer. After the PR is merged, switch to its target branch and pull the merged changes.

Check your current branch and any uncommitted work before switching branches.

## How to review the result before merging

Before merging, read the diff and run the project's checks. Focus on whether the change solves the problem you asked Codex to address.

### Read the diff and the tests

A diff shows added and removed lines. Check whether the changed files match your request and whether the tests exercise the problem that prompted the fix.

Useful questions include:

- Does the change address the requested issue?
- Do the tests cover edge cases, such as empty input or a missing value?
- Would the added tests detect the original failure?
- Are there unrelated changes that need explaining?

### Reproduce the checks when possible

Fetch the PR branch, check it out locally, and run the tests listed in your project's README. Install the project's required tools and dependencies first.

If Codex couldn't run a check, find out why. A missing dependency, a failing assertion, and an unavailable external service need different follow-up steps.

For a visual change, also check the page or app in a suitable local or preview environment. Current Codex Cloud environments don't support browser or computer use, so don't assume a successful command means someone inspected the interface. [Current limitations](https://learn.chatgpt.com/docs/environments/cloud-environments#current-limitations)

### Request a correction in the same task

If you find a problem, return to the original task with a specific observation:

```text
The single-item missing-target case still fails with this input: [input].
Expected: -1. Actual: [result].
Fix this case, add a regression check, and rerun the search checks.
```

Replace the brackets with a result you've actually observed. Continuing the same task preserves its working state and conversation context. [Task state](https://learn.chatgpt.com/docs/environments/cloud-environments#reuse-and-update-saved-state)

If a task exposes another issue, you can investigate it before requesting a merge. GitHub's no-conflicts message tells you about mergeability; it doesn't prove the behavior is correct.

## Codex Cloud advantages and limitations

### Where cloud execution helps

**The task can continue while your laptop sleeps.** You can leave the remote work running and return to it later. [Codex Cloud](https://learn.chatgpt.com/docs/cloud)

**You can reuse the prepared setup.** Once an environment is published, new tasks can start from it. You can also continue the same task across supported devices. Each task has separate working files. [Cloud environments](https://learn.chatgpt.com/docs/environments/cloud-environments)

**The result can include code, tests, and a PR.** You can review the proposed files and validation notes together in GitHub.

### Limits to understand before relying on it

- **Local access doesn't transfer automatically.** Files on your laptop, browser logins, running processes, and local VPN access aren't automatically available in the cloud environment.
- **Git hosting support has boundaries.** The current environment guide lists GitLab and self-hosted GitHub Enterprise Server as unsupported.
- **Browser and computer use are unsupported in current cloud environments.** Plan a separate visual check when the change needs one.
- **Local personal skills aren't synced.** Repository-stored skills are available, but don't assume a skill installed on your computer will appear in Cloud.
- **Resources and saved state are finite.** The documented defaults for Plus are 2 vCPUs, 8 GiB memory, and 8 GiB disk; Pro defaults are 4 vCPUs, 16 GiB memory, and 32 GiB disk. Saved VM state is normally recoverable for up to seven days after your last turn or resume. Commit or save important work rather than relying on that state as a backup.

Check the [environment guide](https://learn.chatgpt.com/docs/environments/cloud-environments#vm-specifications) for your plan and the latest supported capabilities.

Usage is another limit. Local messages and cloud chats share your plan allowance, consumption varies by task, and weekly limits may apply. There isn't a reliable conversion from a subscription into a fixed number of bug fixes. Check your [usage dashboard](https://chatgpt.com/codex/settings/usage) and the [current usage guide](https://learn.chatgpt.com/docs/pricing#what-are-the-usage-limits-for-my-plan).

## Common Codex Cloud problems and how to approach them

<table>
<thead><tr><th scope="col">Problem</th><th scope="col">What to check next</th></tr></thead>
<tbody>
<tr><td>Cloud isn&#x27;t available</td><td>Confirm the account, workspace, plan access, and authentication requirements. In a managed workspace, check with an admin.</td></tr>
<tr><td>The repository isn&#x27;t available</td><td>Confirm the GitHub account and repository access granted to the connection. Supply missing access when prompted.</td></tr>
<tr><td>Setup fails</td><td>Diagnose the first failing command. Retry after fixing tool or access issues. If source files, a manifest, or a lockfile need changes, make them in a coding task, then return to setup.</td></tr>
<tr><td>A package or API request fails</td><td>Check the exact destination hostname, then check authentication separately. An allowed domain doesn&#x27;t supply credentials.</td></tr>
<tr><td>Your environment isn&#x27;t selectable</td><td>Check whether it&#x27;s still unpublished. Finish setup and publish it.</td></tr>
<tr><td>New setup changes don&#x27;t appear</td><td>Republish, then start a new task. Existing tasks retain their own state.</td></tr>
<tr><td>Git push or PR creation fails</td><td>Read the error and check repository permissions, authentication, and network access.</td></tr>
</tbody>
</table>

The [environment troubleshooting guide](https://learn.chatgpt.com/docs/environments/cloud-environments#troubleshoot-setup-and-runtime-access) covers setup, missing values, network failures, and publishing problems.

### Where to edit an existing cloud environment

Open **Settings → Codex Cloud**, select the environment, open its three-dot menu, and choose **Edit**. That's where you can revisit its configuration, including environment variables.

After changing the reusable setup, test it and republish it for new tasks. Existing tasks keep their own state. That reuse behavior is documented in the [environment guide](https://learn.chatgpt.com/docs/environments/cloud-environments#reuse-and-update-saved-state).

### Configure internet access and credentials separately

Current environments let you configure internet access and allowed domains. Add the package registries or service hosts your project needs, test access during setup, and republish for new tasks. Avoid applying old “internet only works during setup” instructions to this current workflow. [Internet access settings](https://learn.chatgpt.com/docs/environments/cloud-environments#connect-to-services)

For configuration values, distinguish:

- **Environment variables:** values programs need to read directly.
- **Network secrets:** credentials for specific allowed HTTPS services on port 443. During setup and tasks, programs receive a placeholder, and a proxy supplies the credential for the matching destination. The raw credential isn't placed in the program's process or files.

For a private package registry, both the allowed host and the authentication must be right. If you're using a network secret, its destination rules and HTTPS requirements also matter. Configure credentials through the supported settings rather than committing them to the repository. [Variables and network secrets](https://learn.chatgpt.com/docs/environments/cloud-environments#configure-environment-variables-and-network-secrets)

### Put recurring project instructions in AGENTS.md

If you keep repeating the same setup and review instructions, add an `AGENTS.md` file to the repository. For a small JavaScript project, an example could say:

```markdown
# Project instructions

- This repository contains standalone JavaScript examples. Follow README.md.
- Keep the examples runnable with Node.js.
- For behavior fixes, add focused regression checks and document how to run them.
- Run the affected examples and relevant checks. Report failures or skipped checks.
- Avoid unrelated refactoring and dependencies unless the task requires them.
```

Adapt these instructions to your project. My [AGENTS.md tutorial](/posts/agents-md-tutorial/) explains how to write useful repository guidance.

## Codex Cloud FAQ

### Is Codex Cloud free?

Don't assume free access to another Codex surface includes Cloud. The current feature matrix lists cloud chats for Plus, Pro, Business, and Enterprise/Edu. Check the [plan comparison](https://learn.chatgpt.com/docs/pricing#feature-availability) and your workspace access.

### How much does Codex Cloud cost?

It uses eligible ChatGPT plan allowances. The current guide lists Plus at US$20 per month, but included usage is limited and additional credits may be available. Prices and workspace billing differ, so check [live pricing](https://learn.chatgpt.com/docs/pricing) for your account rather than treating this as a per-task quote.

### Do I need to know how to code?

You can describe a task in plain English. You still need a way to judge the result. If you're learning, start with explanations and a small change you can understand; get help reviewing changes you can't assess, especially before using them in a real application.

### Can I close my laptop while Codex Cloud works?

Yes, cloud tasks can continue while your computer is asleep. That's different from work executing on your connected personal computer. [Cloud execution](https://learn.chatgpt.com/docs/cloud)

### Can it use a private GitHub repository?

The repository must be available to the account and connection running the task. Connect GitHub and provide the required access when prompted. If an organization manages the repository, its access rules still apply. Don't assume a repository will be accessible just because you can see it elsewhere. [Repository setup and access](https://learn.chatgpt.com/docs/environments/cloud-environments)

### Why can't I see the cloud changes in my local repository?

Your local checkout has its own files and branch state. Fetch and check out the proposed PR branch to review it locally, or pull the target branch after the PR is merged. Opening a PR alone doesn't update your checkout. Follow the [local review steps above](#reproduce-the-checks-when-possible) before merging.

### Can I move an existing local Codex chat into Cloud?

The current handoff guide says handoff to a Codex Cloud environment isn't supported. Prepare a cloud environment and start a cloud task with the context it needs. Reopening an existing cloud task across devices is a separate capability. [Handoff limits](https://learn.chatgpt.com/docs/remote-connections#hand-off-a-chat-between-hosts), [continue a cloud task](https://learn.chatgpt.com/docs/environments/cloud-environments#continue-on-web-or-mobile)

### Does Codex Cloud merge or deploy the result automatically?

Creating a pull request proposes changes for review. Merging and deployment are separate actions. Review the diff and relevant checks before asking for either.

### Is my source code private?

You're giving a remote service access to the selected code. Review repository permissions, environment access, and the data controls and policies for your account or workspace before connecting sensitive projects. OpenAI states that Business, Enterprise, and Edu business data isn't used for training by default; don't assume that statement describes every personal-account setting. [Plan data protections](https://learn.chatgpt.com/docs/pricing), [account and workspace policies](https://learn.chatgpt.com/docs/auth)

### Is this the same as older Codex Cloud tutorials?

Check which experience they show. OpenAI now distinguishes current Codex Cloud from Codex Cloud (Legacy). This guide follows the current **prepare → publish → start task** flow. Legacy code-review and integration instructions may use different setup screens and rules. [Current and legacy environments](https://learn.chatgpt.com/docs/environments/cloud-environments)

For your first task, pick something small enough that you can explain the expected result before Codex starts. Prepare the environment, ask for the change, and use the returned diff and checks to decide what needs to happen next.

My [original Codex walkthrough from June 2025](/posts/openai-chatgpt-codex-tutorial/) covers the earlier interface and includes its video tutorial.

