Skip to content

Getting started with Codex on Perlmutter

Codex is OpenAI's coding agent for software development. It can read and change code in a selected workspace and can run local commands according to its configured permissions.

Codex requires a ChatGPT account; the free account includes limited Codex usage. See the official How to get started with Codex page for more information about Codex, and our Overview page with general information and best practices for using AI coding agents on NERSC systems.

Installation

There are three Codex surfaces, all of which can be used on Perlmutter.

Warning

If you want to run Codex on your local machine and also give it access to Perlmutter, we recommend using the Codex App with a Perlmutter SSH host. The codex process itself runs on Perlmutter through the SSH connection, like running codex directly on a Perlmutter login node. If Codex has SSH access to Perlmutter through another surface (for example, an MCP SSH tool or letting it run ssh perlmutter...) it appears as you the user on Perlmutter and is not subject to the system safeguards we have put in place. You therefore run a higher risk of Codex performing actions on your behalf that violate NERSC's Appropriate Use Policy.

CLI

Because the CLI runs in a terminal, it is the easiest surface to use on Perlmutter. Note that if you use VS Code on Perlmutter, you can use the Codex CLI in the VS Code integrated terminal.

To install the Codex CLI on Perlmutter, run the following from your $HOME directory: 

curl -fsSL https://chatgpt.com/codex/install.sh | sh

You can check the install with codex --version or codex doctor, the latter providing detailed diagnostics on the install and status of the Codex CLI.

Follow the Login on headless devices instructions in the OpenAI documentation to authenticate Codex.

If your ChatGPT workspace permissions do not allow the recommended Device Code authentication, you can use port forwarding for browser login.

  1. Start port forwarding. If you have a Perlmutter remote host on VS Code, connect to Perlmutter and open an interactive terminal on Perlmutter. Otherwise, start port forwarding with

    ssh -L 1455:localhost:1455 <username>@perlmutter.nersc.gov

  2. In that SSH session, run codex login and follow the printed address on your local machine.

For more details, see the OpenAI documentation on Codex CLI.

VS Code IDE Extension

First, install the Codex CLI on Perlmutter using the instructions above.

If you have not already done so, install the VS Code Remote-SSH extension for Perlmutter. We recommend using sshproxy to generate a valid SSH key. By default, VS Code will connect to a login node, which is where you will typically use Codex.

Once you are connected to Perlmutter through a Remote-SSH extension, install the Codex extension from VS Code Marketplace. After you install the extension, you'll find Codex in the right sidebar by default.

See the OpenAI documentation on IDE extensions for more details.

Codex App with a Perlmutter SSH Host

You can use the Codex App on your local machine and connect to Perlmutter using an SSH Host.

To do so, you will need to use NERSC's sshproxy to authenticate your SSH connection to Perlmutter.

  1. Follow the Getting started instructions in the Codex App link to install and sign in to the app on a local Mac or Windows machine (the app is not available for Linux).

  2. Run sshproxy to generate a short-lived NERSC SSH key (by default ~/.ssh/nersc, valid for about 24 hours). Optionally, add a Perlmutter alias to your local machine's ~/.ssh/config, for example:

    Host perlmutter 
    Hostname perlmutter.nersc.gov
    User <username>

  3. Confirm that ssh perlmutter (or ssh <username>@perlmutter.nersc.gov) successfully connects to Perlmutter from your local machine after authenticating with sshproxy.

  4. Install and authenticate the Codex CLI on Perlmutter, using the instructions above.
  5. In the Codex app, open Settings > Connections, add or enable the SSH host, then choose a remote project folder.

Because sshproxy keys are short-lived, rerun sshproxy (typically once a day) whenever the connection can no longer authenticate.

See the OpenAI documentation on Connecting to an SSH host for more details.

Warning

Do not directly expose app-server transports on a shared or public network. Only connect the Codex app to Perlmutter using an SSH Host as instructed above.

Session and Context Management

Start a Codex CLI session with codex or use codex resume to choose a recent session to resume. You can resume the most recent session with codex resume --last. Once in Codex, you can choose to resume a previous session with /resume.

Although Codex dynamically manages session context, clearing older tool outputs and summarizing conversations as you approach the limit, you should also manage context manually. Use /new to clear the context and start a new session, while retaining the session text on screen. Use /clear to clear the context and screen text while starting a new session.

Use @path/to/file to point Codex to specific code within the sandbox; you can also use path/to/file to guide Codex to code outside of the sandbox (which it can read by default). Note that @path/to/file only tab-completes for directories and files tracked by Git.

Tip

Limited context lengths mean AI agents cannot keep long conversations in their working memory. Therefore, we recommend asking agents to create external files, typically Markdown files, that preserve important information from your session so that they persist beyond the current session and do not get lost during automatic context management. For example, if you ask Codex to analyze some log files you have and it gives useful insights in your session conversation, you can tell it something like: "Take the details from our discussion analyzing the log files and add them to a Markdown file at the top of this directory."

AGENTS.md

Create AGENTS.md files to keep durable project instructions and conventions. The contents of these files are automatically loaded as user instructions and context into Codex's sessions. If you find yourself telling Codex the same thing repeatedly when you start new sessions, you should add that to an AGENTS.md file.

For project-specific instructions and conventions, add an AGENTS.md file in the top directory of that project. If you are using the Codex CLI on Perlmutter, this will be the same directory you launch codex from. Run /init in Codex from the project directory to have Codex create the project-specific AGENTS.md for you. If needed, you can further modify and refine this file, or just create it yourself from scratch.

For more general default context for all of your projects on Perlmutter, create ~/.codex/AGENTS.md. The contents of this file are added to Codex's context for every session you run on Perlmutter. This is where you should provide Codex with details for running on Perlmutter.

Tip

We recommend using our NERSC-managed ~/.codex/AGENTS.md file as a baseline template for using Codex on Perlmutter. It provides useful context and guidelines for orienting Codex on Perlmutter. You can add personal preferences and conventions at the end.

Warning

The NERSC-managed ~/.codex/AGENTS.md file provides instructions to Codex for running safely on Perlmutter, but this does not guarantee correct behavior. We have started deploying system-wide safeguards to prevent more troublesome behavior from AI coding agents, but you are still responsible for monitoring Codex and not permitting it to take actions that violate the Appropriate Use Policy.

Sandbox, Approvals, and Permissions

Codex has three related but distinct controls that govern what it can do on your machine: the sandbox is the OS-enforced boundary around local commands, the approval policy determines when Codex must stop and ask before taking an action, and permission profiles define reusable filesystem and network access rules. Together, these controls let Codex work autonomously within a limited scope while requiring confirmation or refusing actions outside that scope.

The sandbox constrains commands run by Codex and the child processes they start. The read-only mode supports inspection without filesystem changes; workspace-write permits routine work inside the active workspace roots and system temporary directories while keeping network access off unless it is explicitly enabled; and danger-full-access removes the local sandbox restrictions. In the default workspace-write policy, .git, .agents, and .codex paths within writable roots remain protected as read-only. Select a mode with --sandbox or configure sandbox_mode in ~/.codex/config.toml.

Approvals control when Codex asks you to authorize an action. With on-request, Codex proceeds with actions allowed by the sandbox and requests approval when it needs to cross the boundary, such as writing outside the workspace or using a blocked network connection. With untrusted, only known-safe read operations run automatically and other commands require approval. With never, Codex does not ask and instead makes a best effort within the configured sandbox. Set the policy with --ask-for-approval (or -a), configure approval_policy in ~/.codex/config.toml, or use /permissions during an interactive session. An approval is consent for the specific escalation, so review the proposed command and its target before accepting it.

Permissions are reusable, least-privilege profiles that combine filesystem rules (read, write, or deny) with network rules. Codex includes the beta profiles :read-only, :workspace, and :danger-full-access; :workspace allows writes within the active workspace roots and system temporary directories, while custom profiles can add roots, protect sensitive paths such as .env files, and allow selected network destinations. Define custom profiles under [permissions.<name>] and select one with default_permissions in ~/.codex/config.toml. Permission profiles replace the older sandbox_mode and sandbox_workspace_write settings for a session rather than composing with them: configure one system or the other.

Tip

We recommend using the Auto preset on version-controlled NERSC projects, which combines the workspace-write sandbox with on-request approvals, and reviewing every request to leave that boundary. Use read-only when you only need Codex to inspect a project. Avoid danger-full-access, :danger-full-access, and --dangerously-bypass-approvals-and-sandbox, which remove important safeguards. See our recommended best practices for coding agents at NERSC.