Running Agents locally

Use this page to run an extracted Agents project on your computer. The ReAct loop, function-calling loop, and final interface use the same Vite setup, but they show their results in different places. Update the OpenAI key lookup and legacy model ID before starting the milestone you have.

What you need first

Install a supported LTS version of Node.js. Node 24 is recommended and includes npm; the export is a Vite project, so Node and npm cover all the tooling it needs.

You also need an OpenAI API key with billing and model access enabled. Model access is set per project in the OpenAI dashboard: the project your key belongs to must allow the model you configure below. The key itself goes into a .env file in a later step.

JunoWhat you need first Install the LTS version of Node.js, which brings npm along with it. You also need an OpenAI API key from an account that can make paid model requests. Collecting both before you start means you never have to stop halfway through setup to find them, which I always used to do!

JunoWhat you need first The export is a Vite project, so Node LTS plus npm is the whole toolchain. Your OpenAI key goes into .env a couple of steps from now, and model access means the allowed-models list on the key's project in the OpenAI dashboard. If you check that list now, you avoid the most confusing error later.

JunoWhat you need first Vite will start these projects with no working key at all, which makes a broken key the quietest failure on this page. Nothing reports a problem until the agent loop makes its first model request and receives an auth or quota error. Confirm billing and model access before you blame the code. I once lost a morning because I blamed the code first.

Open and install the project

Open a terminal in the extracted folder containing package.json, then install the packages:

$ cd path-to-your-downloaded-project
$ npm install

JunoOpen and install the project Open the extracted folder that contains package.json and run npm install there. Every later command on this page happens in that same folder. Keeping one terminal open in that folder saves you from losing track of where you are, which happened to me constantly in my first month.

JunoOpen and install the project All three milestones share the npm-and-Vite setup, so this install step is identical whichever one you extracted. Install beside package.json, then make the two code changes described in the next section. Every command runs in that same folder.

JunoOpen and install the project These exports ship without a lockfile, the package-lock.json that pins exact versions, so npm install resolves the OpenAI SDK and Vite fresh on your machine. Different resolved versions are possible but rarely the cause here. When something breaks later, check your edits to the source before you start changing package versions.

Update the key and model

In index.js, change:

apiKey: process.env.OPENAI_API_KEY,

to:

apiKey: import.meta.env.VITE_OPENAI_API_KEY,

Vite reads environment values through import.meta.env; the same repair appears in Running Embeddings and Vector Databases locally, which adapts a similar course export.

The course snapshots use legacy model IDs such as gpt-3.5-turbo, gpt-3.5-turbo-1106, and gpt-4-1106-preview. For these course examples, replace the model value in your extracted index.js with gpt-4o-mini:

model: "gpt-4o-mini",

Create .env beside package.json:

VITE_OPENAI_API_KEY=your-openai-api-key

Create .gitignore in the same folder:

.env
node_modules/

The .gitignore keeps your key out of any repository you create from this folder; ignoring files and good habits explains why that matters.

This learning setup exposes the key

The OpenAI SDK is intentionally running in the browser, and Vite places the key in the frontend bundle. Use a temporary, restricted key only. Do not deploy or share this version. Production agents need a backend.

JunoUpdate the key and model Swap the old key lookup and model name in index.js, put your temporary key in .env, and keep that file out of Git. This learning version shows the key to the browser on purpose, so use a key you can cancel the moment you finish this project. Never use a key that anything else depends on.

JunoUpdate the key and model Vite only exposes variables that start with VITE_, so the name in the source and the name in .env must match exactly. Search the whole download for legacy model IDs too, because different milestones contain different snapshots. If you miss one ID, one milestone will work while another fails.

JunoUpdate the key and model The production fix is architectural: create the OpenAI client on a backend and have the browser call that backend, so the key never leaves the server. The Vite substitution here belongs to learning mode, and it is not the pattern to deploy. Adding a backend after launch costs more than building it first, and I have done it in both orders.

Run the project

$ npm start

Open the exact Local URL printed by Vite. For a console-only milestone, open your browser's developer tools and select Console. The ReAct and function loops print their progress and response there. In the UI milestone, send a message and look for the response in the page. Stop Vite with Ctrl+C.

JunoRun the project Run npm start and open the exact Local URL Vite prints. For the earlier milestones the output appears in the browser's Console, so a page that looks empty can still be running correctly. Press Ctrl+C to stop when you finish.

JunoRun the project Vite picks the port and prints the exact address, so use what it prints rather than a remembered URL. In a console-only milestone a blank page is what you should expect; check the developer Console for loop output before you treat it as a startup failure. Only the UI milestone answers on the page itself.

JunoRun the project Vite starting proves the edited project compiles, and nothing more; OpenAI has not been contacted yet. Run one real interaction, either the loop output in DevTools or a message through the final interface, before you decide the setup is finished. A project that compiles is not a project that works, and I stopped accepting that conclusion years ago.

Troubleshooting

process is not defined: Search index.js for the remaining process.env.OPENAI_API_KEY and replace it with the Vite form above.

A legacy model is unavailable: Confirm that every model field uses a current model available to your OpenAI project. The downloaded milestones can contain different legacy IDs.

The page looks empty: The earlier milestones report progress in the developer console rather than the page. Use the final UI lesson if you want a visible chat interface.

Authentication or quota error: Check that .env is beside package.json, restart Vite, and confirm billing and key access in the OpenAI account.

JunoTroubleshooting Match each symptom to its fix: process is not defined means the key lookup still needs changing, an empty page usually means the output is in the Console, and an authentication error points at the key or the account. Each one has a single fix. Work through them calmly, one at a time.

JunoTroubleshooting Check in order: the source reads the Vite variable, .env uses the matching name, every model ID is current, and you are watching the place where that milestone actually prints its output. That sequence follows the order in which the request is built, so the first step that fails is the cause. Fix that one and rerun before you change anything else.

JunoTroubleshooting When the agent stays silent, there are four possible causes: the key never reached the bundle, the model ID no longer exists, OpenAI rejected the account, or the UI discarded the returned message. Check them in that order, because a failure early in the list produces the same symptoms as the ones after it. Checking them out of order once turned a five-minute fix into a whole evening for me.