Set Up Codex

In this course you build by talking to a coding agent, Codex, running on your own computer. You say what you want; it makes the files, runs the commands, and shows you what it did. Setting it up is three steps.

Codex talks to the course's model through a server the course runs. That's how the course pays for it, how we can see how these conversations go, and, over the term, how we'll help you get better at them.

Your agent talks to the course's server, which forwards to the model: GPT-5.6, run for Illinois on Microsoft's Azure under the university's agreement, not OpenAI's own service. The course records every exchange, including whatever files the agent reads, may add short notes for your agent during class or when a lesson calls for it (a sentence of context the agent sees; every note is shown to you on your agent's page), and keeps a memory of how you work with the agent so it can help you reflect. Geoff reads these. None of it affects your grade, and nothing goes beyond the course. ChatGPT in your browser or on your phone has nothing to do with any of this: only what you say to Codex on this computer goes through the course. You can see every conversation the course has recorded at your agent's page.

Three Steps

Already use Codex for your own things, on your own account? Read If you used Codex before this course before step 2: the setup line makes the course the app's default for everything you do in it.

Install the Codex app
Codex is the coding agent: the program you'll talk to, which makes files and runs things on your computer for you. Download it for Mac or Windows from openai.com/codex and install it the way you'd install any app. Don't sign in. If it opens and asks for a ChatGPT account, quit it (⌘ Q on a Mac; close it from the taskbar on Windows). Your setup, not an account, is what connects it to the course. If you were already signed in, that's fine too: once the settings file names the course, the app uses the course. If your computer asks for an administrator password you don't have, or says it's too old, stop and tell Geoff; don't spend the night on it.
Connect it to the course
Open a terminal window (a plain window where you type a line and press Enter; the course asks you to do this once). On a Mac, press ⌘ Space, type Terminal, and press Return. On Windows, press the Windows key, type PowerShell, and press Enter. Then paste your setup line (⌘ V on a Mac; right-click or Ctrl V in PowerShell) and press Return or Enter:
Mac
Windows
Your setup line will appear right here once you've signed in and clicked Create my setup in the box above. It's shown once; if you had one and lost it, rotate for a new one.
The line fetches a short script from this site that writes one file, Codex's settings file in your own user folder, and nothing else; then it prints Done, and you can close the window. The file tells Codex to send what you type to the course's server, using a token (a long password that is yours alone; that's why the line is shown once), and lets the agent download what your project needs (Codex works inside a fenced-off space, its sandbox; the file opens that fence to the network, nothing else). If you already had a settings file, it's kept beside the new one as config.toml.bak and its own settings stay. For most of you, that's the one time this course asks you to type into a terminal.

Open Codex and let the agent finish

Open the app (quit and reopen it if it was already running). It won't ask you to sign in now. When it asks for a folder to work in, choose your Desktop, or any folder that's yours. It will ask whether you trust the folder, which means whether the agent may read and change files there; say yes. Then paste this as your first message:

I'm a student in CS 199 ASK, Conversational Programming, at Illinois. In this course I build software by talking to you, and my setup sends your requests through the course's server. Please check that setup and finish it with me:

1. Read Codex's settings, but don't repeat their contents to me: they have my private token in them. Look in ~/.codex/config.toml (on Windows, C:\Users\<me>\.codex\config.toml), and, if I started you with --profile course, in ~/.codex/course.config.toml as well. Tell me whether the file you're running under points at the course: there should be a [model_providers.conversationalprogramming] section whose base_url is on proxy.conversationalprogramming.org, and the lines starting with "model =" and "model_provider =" should come before any [section] in that file. If those two lines are there but not before the first [section], move them to the top and tell me you did. If neither file has the section, stop and tell me to get a fresh setup line (or profile line) from the course's setup page.
2. Tell me which model provider and model you're using for this conversation, and which version of Codex you are.
3. Ask me what I'd like to call my website (any name; I can change it later), make an empty folder with that name on my Desktop, and tell me, step by step for the Codex app, how to open that folder in Codex before we go on.
4. In three sentences, tell me what you can do for me in this course.

If anything looks wrong, say so plainly and tell me to show it to Geoff.

It checks that you're talking to the course (it should name the provider as conversationalprogramming), fixes the settings file if anything is out of place, asks what to call your website (pick anything; you can change it later) and makes a folder for it on your Desktop (say yes if it asks permission), and tells you what it can do for you. While it does, the box at the top of this page shows your agent connecting.

If It Fights You

Doing this at home? Stop at the first thing that doesn't match this page, take a screenshot, and bring it to class. Nothing is lost, and nothing here is graded.

The app asks you to sign in with ChatGPT. The settings file isn't in place yet. Quit the app, do step 2 again, and open the app again.
The terminal printed something other than Done (red text in PowerShell, permission denied, anything). Leave the window open, or copy what it said, and wave Geoff over. In class, that is; at home, screenshot it and bring it. That's enough.
The installer wants an administrator password you don't have (a work or family laptop). Stop; tell Geoff before the next studio.
You lost your line, or you're on a new laptop. Rotate in the box above, then do step 2 again with the new line and quit and reopen Codex. Until you do, Codex will sit at "Reconnecting…" for a few minutes and then say its token was revoked.
The agent says it isn't talking to the course. Show Geoff. Nothing you've built is lost; it just isn't going through the course yet.
You use the terminal with a profile and forgot --profile course. Nothing looks different, but that session went to your own account and the course never saw it. Ask the agent which provider it's using; it should say conversationalprogramming.
You got a note that the app is sending everything through the course, and you use it for other things. Nothing is broken. See Using Codex for other things too.

Other Ways In

Everything below this line is optional. If the three steps worked, you're done; skip it.

Do step 2 by hand

For people who already edit settings files, or whose terminal refused the line. The setup line writes this into Codex's settings file, ~/.codex/config.toml (on Windows, C:\Users\<you>\.codex\config.toml); the .codex folder is hidden (the Finder and Explorer don't show folders whose names start with a dot), so the lines below open the file for you. Make the folder and the file if they don't exist, and paste this at the very top, above anything already there. If your file already has model = or model_provider = lines, replace them with ours. The lines starting with model have to come before any [section], and a file can't have two [sandbox_workspace_write] sections, so if yours already has one, add network_access = true to it instead of pasting a second.

Shown once, together with your setup line.

On a Mac the folder is hidden in the Finder; this line in Terminal opens the file in TextEdit, creating it if needed:

mkdir -p ~/.codex && touch ~/.codex/config.toml && open -e ~/.codex/config.toml

On Windows, this line in PowerShell does the same with Notepad (say yes when Notepad asks whether to create the file):

New-Item -ItemType Directory -Force $HOME\.codex | Out-Null; notepad $HOME\.codex\config.toml

Codex in a terminal instead of the app

For people who'd rather not use the app, and for anyone using a course profile (below). The same agent, in a terminal window instead of a window of its own. It reads the same settings file, so step 2 is unchanged. Two installs, so a second administrator prompt on a locked-down laptop.

Install Node.js, a program Codex needs: the LTS download (the recommended one) from nodejs.org. It brings npm, which installs things, with it.
In a terminal, run npm install -g @openai/codex. On a Mac, if it says permission denied, run it again with sudo in front (it installs for the whole computer) and type your login password when asked; nothing shows while you type it, which is normal.
Do step 2 above.
Make a folder for your project. In the terminal, type cd (with the space), drag the folder into the window, and press Return. Then run codex. Choose Skip if it offers an update, and Yes when it asks whether you trust the folder. Paste the same first message.

If you used Codex before this course

If you installed Codex for this course, skip this. This is for people who already had Codex, on their own account, and want to keep it that way. The setup line makes the course the app's default. From then on, everything you do in Codex, in the app or in a terminal, goes through the course's server, is paid for by the course, and is part of the course's records, whether or not it's for this class. If Codex is already part of your life, you probably don't want that. There are two ways to go.

Keep the app for your own things and do the course in a terminal. Codex can keep a second settings file, called a profile. The course's profile is its own file (~/.codex/course.config.toml); the app never looks at it, and in a terminal one extra word picks it: codex --profile course talks to the course, plain codex is yours, and the app stays signed in to your own account. Your own settings file is left alone; under the profile, the course's settings apply for that session. The app can't pick a profile, which is why this way means the terminal for class.

Install Codex for the terminal if you haven't: steps 1 and 2 under Codex in a terminal instead of the app.
Instead of the line in step 2, run the profile form of it, below. It writes the profile file and touches nothing else.
For class: in a terminal, go to your project folder and run codex --profile course. Then paste the first message from step 3 and carry on as the page says. The box at the top of this page shows your agent connecting from the terminal just as it would from the app. To check the other side, run plain codex and ask it which provider it's using: it should not say conversationalprogramming.

Shown once, together with your setup line. On Windows the profile line is longer because that is how PowerShell hands -Profile to a downloaded script; it does the same thing. Already ran the setup line? See Using Codex for other things too; it moves you over without any of this.

Or let the course be the default. Run the setup line as in step 2. Your own settings stay (your previous file is kept beside it as config.toml.bak), but the course's model becomes the default for everything, so from then on use Codex only for this course, or come back to Using Codex for other things too when you want it back.

Using Codex for Other Things Too

Not part of setup. If you set up today, you're done above.

If you ran the setup line, the course is your Codex app's default: everything you do in the app goes through the course's server and is paid for by the course, whether it's for this class or not, and the course's records include it. If you ever set the app to run tasks on a schedule (it calls them automations), those count too. The course pays for course work, so please keep the app for the course, or, if you want Codex for other things as well, move to the other arrangement: the app on your own ChatGPT account, the course in a terminal. You don't need to understand any of the files; the agent does it. And if you used the app for your own things before you knew, that's on us, not you: nothing to fix, and if there are conversations on your agent's page you'd rather Geoff didn't read, tell him.

Let the agent do it. Open Codex, as it is now, in any folder, and paste this:

I use Codex for things besides CS 199, so I want the course as a profile instead of the app's default. Please do this for me, and ask before each step that changes a file:
0. Check that Codex works in a terminal by running: codex --version. If it doesn't, walk me through installing it before anything else (Node.js, the LTS download from nodejs.org; then npm install -g @openai/codex, with sudo in front on a Mac if it says permission denied), and don't go on until codex --version works.
1. Read Codex's settings file, ~/.codex/config.toml (on Windows, C:\Users\<me>\.codex\config.toml). Don't show me its contents: they include my private token. Under [model_providers.conversationalprogramming], the base_url ends in /u/TOKEN/v1. Take TOKEN from it.
2. Run this with TOKEN filled in, and tell me it wrote ~/.codex/course.config.toml:
   Mac: curl -fsSL https://www.conversationalprogramming.org/api/proxy/install/TOKEN.sh | sh -s -- --profile
   Windows (PowerShell): & ([scriptblock]::Create((irm https://www.conversationalprogramming.org/api/proxy/install/TOKEN.ps1))) -Profile
3. Run this, and tell me the course is out of config.toml:
   Mac: curl -fsSL https://www.conversationalprogramming.org/api/proxy/install/remove.sh | sh
   Windows (PowerShell): irm https://www.conversationalprogramming.org/api/proxy/install/remove.ps1 | iex
4. Then tell me, in a few sentences: quit the Codex app and open it again, and sign in with my own ChatGPT account if it asks (if it doesn't ask, I was already signed in, and that's fine); how to check, by asking the app which provider it's using, that it no longer says conversationalprogramming; that for class I open a terminal, type cd and a space, drag my project folder into the window, press Return, and run codex --profile course; and that this conversation is the last one the course will see from the app.
If anything fails, tell me exactly what happened and to show it to Geoff.

It first checks that Codex works in a terminal, and installs it with you if not (that's the one part that can need your computer's password). Then it reads its own settings, writes the course profile, takes the course out of the app, and tells you what to do next: quit the app, open it again, and sign in with your own ChatGPT account. It asks permission before each step; expect three (to read the settings file, to run a line ending in --profile, and to run remove.sh, which removes the course from the app's settings, not the app and not anything you've built), or a few more if it has to install Codex for the terminal first, which can mean typing your computer's password. Say yes to each. If the app doesn't ask you to sign in afterwards, you were already signed in; ask it which provider it's using, and it should no longer say conversationalprogramming. From then on the app is yours.

By hand, if you'd rather. Two lines in a terminal. First the profile form of your setup line, under If you already use Codex (rotate in the box above if your lines are no longer shown; the old line stops working, which is fine, since you're taking it out of the app). Then this one, which is the same for everyone: it takes the course's lines out of the app's settings file, puts back what the setup had set aside, and leaves your backup and the profile alone. It's short; open its address in a browser to read it first if you like.

Mac

curl -fsSL https://www.conversationalprogramming.org/api/proxy/install/remove.sh | sh

Windows

irm https://www.conversationalprogramming.org/api/proxy/install/remove.ps1 | iex

Then quit the app, open it again, and sign in with your own account if it asks.

Then, for class. Open Terminal (on Windows, PowerShell), type cd and a space, drag your project folder into the window, and press Return. Then run codex --profile course. If it offers an update, skip it; if it asks whether you trust the folder, say yes. Paste the first message from step 3 the first time, and the box at the top of this page shows you connecting. Either way, if something doesn't look right, show Geoff; nothing you've built is lost.