Setting up Claude Code and Codex for class

Why we're doing it this way

Claude Code and Codex read files, write files, and run commands.

A Codespace is a throwaway Linux computer in a data center. When an agent makes a mess there, you delete the Codespace and make a new one in three minutes. Your own laptop, your files, and your other work are never in reach.

If you've never used a terminal

A terminal is a panel where you type commands as text instead of clicking buttons. The tools you'll use in this class — Claude Code and Codex — are CLI tools (Command Line Interface), meaning you start them by typing their name and pressing Enter. There is no icon to double-click. The terminal is the interface.

Throughout this guide you'll see boxes like this one:

• The $ is not something you type. It's the computer saying "ready" — you type after it.
• So the line above means: type claude --version and press Enter.
• Every box has a Copy button in its top-right corner. It copies just the command — no $, no greyed-out output — so you can paste it straight into the terminal. (Selecting the text by hand also skips the $.)
• You can paste several lines at once. Some boxes hold a command that spans multiple lines, or a few commands in a row; paste the whole thing and the terminal runs it line by line. (Some terminals ask "paste multiple lines?" — say yes.)
• Greyed-out lines are what the computer prints back at you.
• Anything from a # to the end of the line is a note for you. The computer ignores it, so there's no need to strip these out before pasting — they're harmless.

0Get ready

1Make your own copy of the class repo

This step happens on the GitHub website, in your ordinary web browser — not in VS Code. First log in to github.com, then click this link to open the class repository:

github.com/agnes-beaudry/ai-sandbox

Then:

1. Click the green Use this template button, then Create a new repository.
2. Give it any name you like — ai-class is fine.
3. Leave the other settings alone and click Create repository.

Everything after this happens on your copy, not the link above — so you don't need to come back to it.

You now have your own copy under your own GitHub account. Your work is yours; nothing you do affects your classmates or the original.

2Create your Codespace

On your new copy of the repo (look at the top left of the screen — it should say your-username / ai-class or equivalent):

1. Click the green Code button.
2. Click the Codespaces tab in the dropdown.
3. Click Create codespace on main.

When it's finished you'll be looking at a page of text — the repository's README file, opened for you automatically. That's the normal resting state, and it means you're in.

If there's a panel open along the bottom of the window, you'll also see this in it:

That line was written into the class repo's setup file, so seeing it means your tools installed correctly. If there's no panel and you can't see it, that's fine too — nothing has gone wrong, and you'll get another chance to spot it in step 4.

Either way, there's nothing to do here. Carry straight on to step 3.

3Open it in the VS Code app

Two ways to get there — pick whichever's easier. Both need the GitHub Codespaces extension, so install it first if you skipped that in Get ready: open the Extensions view (Cmd Shift X on Mac, Ctrl Shift X on Windows), search GitHub Codespaces, and click Install.

Option A — from the browser tab you're already in.

1. Click the ☰ hamburger menu at the very top-left of the codespaces page.
2. Click Open in VS Code Desktop.
3. Your browser will ask permission to open VS Code. Allow it.

Option B — from VS Code directly. Quicker once you know it, and it's the same shortcut you'll use every week in Reconnecting.

1. Open VS Code.
2. Press Cmd Shift P (Mac) or Ctrl Shift P (Windows) — this opens the Command Palette, VS Code's "search all commands" box.
3. Type Connect to Codespace.
4. Choose "Codespaces: Connect to Codespace..." from the results.
5. Pick your Codespace from the list that appears.

A few prompts will appear as it connects, either way. Here's what to do with each:

4Open a terminal in VS Code

You may already have one. Look along the bottom of the VS Code window — if there's a panel there with a tab labelled TERMINAL, click that tab and skip ahead. There's no need for a second one.

If there's no panel at all, open one:

That ` is the backtick — top-left of the keyboard, above Tab, sharing a key with ~.

Either way, what you're after is a panel showing a line that ends in $. That's your prompt. You're ready.

You may also spot the Sandbox ready message here if you didn't see it earlier. Either way, step 8 checks properly.

5Choose how you'll log in

Each tool can be used two ways. You pick one per tool — they don't have to match. For this class, log in with your subscription account — it's the default we recommend, and it means nothing below needs setting up on GitHub. The department's AI gateway key is the alternative, if your instructor gives you one.

Alternative: using the gateway key instead

Two short jobs: create the key on the gateway site, then store it with GitHub so every Codespace you open has it.

First, create your key

1. In your browser, go to math.colorado.edu/ai and log in. You land on a chat screen.
2. Look at the row of small buttons under the message box, at the bottom centre of the screen — Download chat · Open chat · New chat · API keys. Click API keys.
3. A panel titled API keys for coding tools (Claude Code / Codex) opens. Scroll to the bottom of it: there's a box labelled Label (e.g. laptop) next to a Create key button. Type a label — codespace is fine; it's only so you can recognise the key later — and click Create key.
4. The new key appears under "New key — shown once, copy it now". It starts with cuai-. Click Copy beside it. This is the only time the site will show it; if you lose it, come back here, Revoke it, and create another.

It's a secret: don't paste it into chat windows, screenshots, or files in your repo.

Then store it with GitHub

You'll store it as a Codespaces secret. Do this once, and it's waiting for you — as an environment variable named MATHPROXY_API_KEY — in every Codespace you create, and it survives rebuilds. One secret covers both tools.

1. Go to github.com/settings/codespaces. Note this is your GitHub account settings, not the class repo — which is why each of you does this separately with your own key.
2. Find Codespaces secrets and click New secret.
3. Fill in the name and paste your key as the value. The name must be exactly:

4. Under repository access, choose your copy of the class repo. You can add more repositories later if you need to; keep it to the one for now.
5. Click Add secret.

To confirm a key arrived, run this in a terminal — it checks without displaying your key:

Don't use a command that prints the key itself — a key on screen is a key in your next screenshot.

6Log in to Claude Code

If you're using your Claude account (recommended)

You'll see this menu:

Choose 1. A browser opens — approve the login there and the terminal picks it up.

To sign out later: type /logout inside Claude Code.

Alternative: if you're using the gateway key

Claude Code talks to the gateway when two environment variables are set: where to send requests (ANTHROPIC_BASE_URL) and the key to send (ANTHROPIC_AUTH_TOKEN). Your key is already in the Codespace as MATHPROXY_API_KEY (step 5), so you never type it. No login menu, no browser. You can set the variables inline, every time you start it:

Or set them once, so that plain claude works from then on in every terminal (the first two lines append to your shell's start-up file; the third loads it into the current terminal):

Either way, Claude Code starts without asking you to log in. Inside it, /status shows the gateway address, which is how you know you're on the key and not on an account. Then type hi and press Enter: a wrong or revoked key still gets you into Claude Code, and only fails when you actually send a message. A reply means the key works; an error (typically mentioning authentication or a 401) means it doesn't — see step 8. Remember the AI use rules: everything it reads goes to the provider.

7Log in to Codex

If you chose option 1, a browser opens — sign in with your ChatGPT account and approve. The terminal picks it up on its own within a few seconds.

To sign out later: type /logout inside Codex. Somewhat hilariously, if you type "exit" or other attempts to leave, Codex will cheerfully bid you goodbye and not close.

Alternative: if you're using the gateway key

Codex doesn't read a base-URL variable the way Claude Code does (it ignores OPENAI_BASE_URL), so instead you tell it about the gateway as a model provider, with five -c options. The key itself is read from MATHPROXY_API_KEY, which step 5 put in your Codespace — nothing to paste. Run it inline, nothing to install or edit:

Codex starts straight away — no sign-in menu — because the key comes from the environment. Type hi and press Enter to make sure it actually answers: a bad key gets you this far and fails only when you send a message (see step 8). The AI use rules apply here just as for Claude Code. Add -m <model> to choose a model, e.g. -m claude-opus-5. These options leave any existing Codex config and ChatGPT login untouched, so you can use both ways side by side.

Typing all that every week is tedious, so you can also write it once into Codex's config file, after which plain codex uses the gateway:

To go back to your ChatGPT account later, delete those lines from ~/.codex/config.toml (or the whole file) and run codex again.

8Check everything works

At the $ prompt, run these two. Version numbers mean success.

Your numbers may differ — that's fine. Any version number means the tool is installed. It does not mean the tool can reach a model — a wrong, expired, or revoked key, or a login that didn't finish, lets you start the tool and only fails when you send a message. So, second check: start each tool, say hi, and make sure it answers.

(If you're on the gateway, start them the gateway way from steps 6 and 7 instead of plain claude and codex.) Any reply at all — a greeting, a question about what you'd like to do — means the connection works.

Once both tools have answered you, you're done. Come to class ready to work.

Managing your free hours

GitHub gives free accounts a monthly allowance of Codespaces time, measured in "core hours": hours of wall-clock running time multiplied by the machine's CPU count. Free accounts get 120 core hours a month, and the standard Codespace machine has 2 CPUs — so in practice you have about 60 hours per month. That's plenty for this class, as long as your Codespace isn't running while you're off doing something else.

Stop it when you're done for the day

Any of these works — they all pause the meter without losing anything:

• From VS Code: click the Codespaces: … badge in the bottom-left corner and choose Stop Current Codespace.
• Or open the Command Palette (Cmd/Ctrl Shift P) and run Codespaces: Stop Current Codespace.
• Or go to github.com/codespaces, click the … menu on your Codespace's row, and choose Stop codespace.

Stopping is not deleting. Your files, your logins, and anything you installed are all there when you reconnect.

Shorten the idle timeout

The idle timeout is your safety net for the times you forget to stop it. You can make it tighter:

1. Go to github.com/settings/codespaces — the same settings page as the gateway key.
2. Find Default idle timeout and set it to something short. 15 minutes is a good choice for this class.

The new timeout applies to Codespaces you start after changing it, so stop and reopen yours if it's currently running.

Reconnecting: getting back to your work

Everything above is one-time setup. This section is the one you'll use every week.

Your Codespace doesn't go anywhere. Your files, your logins, and anything you installed are all still sitting there exactly as you left them. It goes to sleep when you stop using it — that's normal, and it's how you avoid burning through your free hours — but nothing is lost. Coming back is a matter of reconnecting to it.

First, the thing that confuses everyone

VS Code can show you two completely different computers, and they look identical. It can show files on your own laptop, or files in your Codespace. Same window, same sidebar, same terminal, no obvious difference.

This matters because the class tools only exist in the Codespace. They were never installed on your laptop. So if you open VS Code, type claude, and get command not found, you almost certainly aren't connected — the tool isn't missing, you're just looking at the wrong computer.

Two ways to connect

Both do the same thing. Use whichever you find easier to remember.

Option A — the Command Palette. Faster once you know it.

1. Open VS Code.
2. Press Cmd Shift P on Mac, or Ctrl Shift P on Windows. A search box appears at the top — this is VS Code's "search all commands" box, and it can run anything VS Code does.
3. Type Connect to Codespace.
4. Choose "Codespaces: Connect to Codespace..." from the results.
5. Pick your Codespace from the list that appears.

Option B — the Remote Explorer sidebar. More clicking, but you can see what you're doing.

1. Open VS Code.
2. In the narrow icon strip down the left edge, click the Remote Explorer icon — it looks like a small monitor or screen. If you don't see it, it's because the extension only appears once installed; use Option A instead.
3. At the top of that panel there's a dropdown. Set it to GitHub Codespaces.
4. Your Codespaces are listed. Clicking the name does nothing useful — you have to click the small plug icon that appears to the right of the name when you hover over it. That's the connect button, and it's very easy to miss.
5. If you can't find the plug, right-click your Codespace and choose Connect to Codespace instead — same result.

Either way, VS Code will take a few seconds to connect — and longer if the Codespace was asleep, because it has to wake up first. Wait for the badge in the corner before you start typing. A terminal opened too early may be pointing at your laptop.

Do I need to log in again?

Normally, no. Your Claude and Codex logins are stored inside the Codespace and survive it going to sleep and waking up.

You will need to log in again if the Codespace gets rebuilt or deleted — for example if you delete it to start fresh, or if you change its settings in a way that recreates it. That's not a sign anything is wrong; just run claude and codex again and log in as you did the first time.

Before you start work: check how you're logged in

This is worth thirty seconds at the start of a session. Because your login is remembered, it's entirely possible to be signed in a way you didn't intend and not notice — most commonly, running on the gateway key when you meant to use your own subscription, or the other way round.

In Claude Code, start it and run:

A Login method row shows your subscription account. If you're on the gateway instead, you'll see the gateway address (math.colorado.edu/ai) and an auth-token row — and the AI use rules apply. That's your answer in one command.

Switching between them

You can switch either direction. The two tools do it differently.

When things break

Everything here has happened to someone. None of it means you broke anything.