Set up your workshop

Arjun’s new Crumb laptop arrives on Saturday morning, still in its box. Priya has sent him a short list: terminal, uv, Python 3.12, git, VS Code, a project, an API key with a spending limit, a .env file, hello world.

“Fifteen minutes,” Arjun says to himself. He is a backend developer. He has set up machines before.

It takes him seventy minutes. Not because any step is hard, but because four small things go wrong, each in a way that is completely normal and completely baffling the first time. A command he just installed is “not found”. His computer insists it already has Python, the wrong one. He nearly publishes a secret key to the internet. And his first call to Claude fails with an error that makes no sense, because the key in his file is correct.

This lab walks you through the same setup, and the same four surprises, so that yours takes fifteen minutes. Every step ends with what you should see when it worked. If you see something else, the step tells you why.

Why each tool is on the list

Before installing anything, Arjun asks the right question: “Why these, specifically?” Priya answers with the bakery.

• The terminal is the back door to the kitchen. Menus and buttons are the shop front; the terminal is where you type exact instructions to your computer. Every AI tool you will use can be driven from it. (The Developer Toolkit has a full lesson on it.)
• Python is the language almost all AI engineering is written in. We use version 3.12: modern, and well supported by every AI library in this course.
• uv is the kitchen manager. It installs Python itself, creates a separate, clean set of ingredients for each project, and records exactly which library versions you used, so your project works the same on Priya’s laptop as on yours. It replaces several older tools (pip, venv, pyenv) with one fast one.
• git is a save-point system for code. Every time something works, you save a snapshot; when you break it, you go back.
• VS Code is the workbench: a free code editor with good Python support.
• An API key is your account’s password for calling a model. A spending limit makes sure a bug cannot turn into a large bill.
• A .env file is a small, private file that holds secrets like that key, kept out of your code and out of git.

Total cost: zero for the tools, plus a few dollars of API credit.

Step 1: Open a terminal and install uv

Open a terminal.

• macOS: press Cmd+Space, type “Terminal”, press Enter.
• Windows: press the Windows key, type “Terminal” (Windows 11) or “PowerShell” (Windows 10), press Enter.
• Linux: usually Ctrl+Alt+T, or find “Terminal” in your applications.

Type this and press Enter:

echo hello

You should see hello printed back. You just gave your computer an exact instruction.

Install uv. On macOS or Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

On Windows, in PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

These commands download uv’s official installer and run it. (Alternatives: brew install uv on macOS with Homebrew, or winget install --id=astral-sh.uv -e on Windows.) In general, only run “download and execute” commands like these from sources you trust; this one comes from uv’s own documentation, linked at the end.

Now check it worked:

uv --version

This is where Arjun’s first surprise happened. He typed it in the same window and got:

zsh: command not found: uv

(On Windows it reads “The term ‘uv’ is not recognized”.) The installer had worked. But a terminal reads its list of places to look for programs, called the PATH, only when it starts. The window he had open was started before uv existed.

Close the terminal completely and open a new one, then run uv --version again. You should now see a version number, such as uv 0.12.5 (yours may be newer; that is fine).

Step 2: Install Python 3.12 with uv

Arjun’s second surprise came from being curious. Before installing anything, he typed python3 --version and got:

Python 3.9.6

“I already have Python?” Many computers ship with an old Python that the operating system uses for its own purposes. macOS includes one; most Linux distributions include one. Leave it alone: do not upgrade or delete it, because parts of your system may depend on it. uv installs and manages its own Pythons, separately, and picks the right one per project.

uv python install 3.12

You should see something like Installed Python 3.12.14 in 2.31s (the last number of the version will differ). Check it:

uv run --python 3.12 python --version

You should now see Python 3.12.x. Notice that this did not change what plain python3 --version says. That is deliberate: your projects will use uv’s Python, and the system keeps its own.

Step 3: Install git and VS Code

git.

• macOS: run xcode-select --install and accept the dialog (this installs Apple’s command-line developer tools, which include git). Or, with Homebrew, brew install git.
• Windows: run winget install --id Git.Git -e, or download the installer from git-scm.com and accept the defaults. Then open a new terminal.
• Linux: sudo apt install git on Ubuntu or Debian, sudo dnf install git on Fedora.

Check with git --version. You should see something like git version 2.50.1.

Now tell git who you are. Every save point records an author, and it will refuse to save without one:

git config --global user.name "Arjun Mehta"
git config --global user.email "arjun@example.com"
git config --global init.defaultBranch main

Use your own name and the email you will use for GitHub. The last line names your main line of history main, which is the modern convention. These commands print nothing when they work.

VS Code. Download it from code.visualstudio.com and install it. Then:

1. Open VS Code and click the Extensions icon on the left (four small squares), or press Ctrl+Shift+X (Cmd+Shift+X on macOS).
2. Search for Python and install the one published by Microsoft.
3. On macOS only: open the Command Palette with Cmd+Shift+P, type “shell command”, and choose Shell Command: Install ‘code’ command in PATH. (On Windows and Linux the installer usually does this for you.)

Open a new terminal and type code --version. You should see a version number. Now code . will open the current folder in VS Code.

Step 4: Create the crumb-lab project

Make a folder for all your course work and create your first project inside it. These commands work in macOS, Linux and Windows PowerShell:

mkdir ~/code
cd ~/code
uv init crumb-lab --python 3.12 --no-package
cd crumb-lab

mkdir makes a directory, cd moves into it, and ~ means your home folder. (If ~/code already exists, mkdir complains; that is harmless.) --no-package asks uv for a simple application layout with one main.py; without it, some uv versions create a src/ folder meant for publishable libraries, which we do not need.

List what uv made, including hidden files (names starting with a dot): ls -a on macOS and Linux, ls -Force in PowerShell. You should see:

.git  .gitignore  .python-version  README.md  main.py  pyproject.toml

• pyproject.toml: the project’s ID card, with its name, Python version and (soon) its libraries.
• .python-version: says “3.12”, so uv always uses the right Python here.
• main.py: a starter script.
• .git and .gitignore: uv also made this folder a git repository, with a list of files git should ignore.

Run the starter script:

uv run main.py

The first time, you should see:

Using CPython 3.12.14
Creating virtual environment at: .venv
Hello from crumb-lab!

uv noticed there was no environment yet and created one in a hidden .venv folder: this project’s private Python and library shelf. Now add the two libraries for this lab, Anthropic’s SDK (the ready-made Python library for calling Claude) and python-dotenv (which reads .env files):

uv add anthropic python-dotenv

You should see a list of packages with + signs as uv installs them and their dependencies. Open pyproject.toml and you will find them recorded under dependencies, and a new file, uv.lock, pins the exact version of every package. Commit both files to git and anyone can recreate your environment exactly with uv sync.

Many tutorials online use pip install anthropic. That installs a package too, but does not record it in your project. In this course, uv add is the equivalent, and better habit.

Step 5: Get an API key and set a spending limit

You need an account with at least one model provider. The course mostly uses Anthropic (Claude), with OpenAI and Google Gemini in places. Start with one; add others when a lesson needs them.

1. Go to the Anthropic documentation and follow the link to sign in to the Console (the developer dashboard). Create an account.
2. Open the billing section and add a small amount of prepaid credit, say $5. That is plenty for weeks of exercises. Leave automatic reload switched off. With prepaid credit and no auto-reload, the most you can ever spend is what you put in.
3. Look in the settings for spending limits, and set a monthly limit if one is offered. Menus move around; search the docs for “spend limits” if you cannot find it.
4. Open the API keys page and create a key. Name it after where it will live, like crumb-lab-laptop, so you know which to revoke if this laptop is lost.
5. Copy the key immediately. It is shown only once. It starts with sk-ant- and is long.

Do not paste it anywhere yet. Not into a chat, not into a document, not into main.py. The next step gives it a safe home.

For OpenAI, the process is similar at platform.openai.com: prepaid credit, auto-recharge off, then a key. Be aware that some providers’ “budgets” send an alert email rather than blocking requests, which is why prepaid credit without auto-recharge is the most reliable cap. Google Gemini offers a free tier through Google AI Studio (see the Gemini docs), which is a good option if you would rather not add a card yet; the alternative code at the end of Step 7 uses it.

Step 6: Store the key in .env and keep it out of git

In VS Code, open the project with code . from inside crumb-lab. Create a new file at the top level of the project (next to pyproject.toml) named exactly .env, with one line:

ANTHROPIC_API_KEY=sk-ant-paste-your-real-key-here

No spaces around = are needed, and no quotes. Save it.

Windows users: create this file in VS Code, not Notepad. Notepad likes to save it as .env.txt while showing you .env, and then nothing can find it.

Now Arjun’s third surprise. Run:

git status

You will see something like:

Untracked files:
  .env
  .gitignore
  .python-version
  README.md
  main.py
  pyproject.toml
  uv.lock

.env is in that list. The .gitignore uv created ignores .venv and Python’s cache files, but not .env. If Arjun had typed git add . now, as he does a dozen times a day at work, his key would have been in the first commit. If he had then pushed to GitHub, it would have been public.

Add .env to the ignore list. On macOS or Linux:

echo ".env" >> .gitignore

In Windows PowerShell:

Add-Content .gitignore ".env"

(The PowerShell version matters: older PowerShell’s >> writes the file in an encoding git may not read.) Run git status again. You should now see every file except .env. Make your first save point:

git add .
git commit -m "Set up crumb-lab project"
git ls-files

git ls-files lists everything git is tracking. You should see .gitignore, .python-version, README.md, main.py, pyproject.toml and uv.lock, and no .env.

Step 7: Hello world, then hello Claude

First, prove the key loads, without calling any model. Replace everything in main.py with:

import os

from dotenv import load_dotenv

load_dotenv()  # read .env into environment variables

key = os.getenv("ANTHROPIC_API_KEY")
if not key:
    raise SystemExit("No ANTHROPIC_API_KEY found. Is .env in this folder?")

# Never print a whole key. The start and end are enough to recognise it.
print(f"Key loaded: {key[:7]}...{key[-4:]} ({len(key)} characters)")

Line by line: load_dotenv() reads .env and puts each line into the program’s environment variables (named values a program can read from its surroundings). os.getenv reads one of them, returning None if it is missing. If it is missing, we stop with a helpful message instead of a confusing crash later. Then we print just enough to recognise the key.

uv run main.py

You should see Key loaded: sk-ant-... followed by the last four characters and a length of around a hundred characters. If you see “No ANTHROPIC_API_KEY found”, the .env file is missing, misnamed, or in a different folder.

Now call a model. Create hello_claude.py:

import anthropic
from dotenv import load_dotenv

load_dotenv()  # puts ANTHROPIC_API_KEY into the environment

client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY automatically

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=300,  # a hard cap on the length (and cost) of the reply
    system="You are Crumb's friendly support assistant.",
    messages=[{"role": "user", "content": "Do you have eggless cakes? Answer in one sentence."}],
)

print(next(b.text for b in response.content if b.type == "text"))
print("Tokens in:", response.usage.input_tokens, "out:", response.usage.output_tokens)

The new pieces: anthropic.Anthropic() creates a client that knows how to talk to the API; messages.create sends one request; system is the standing instruction; messages is the conversation so far, here a single user message. The reply comes back as a list of content blocks, and the next(...) line picks out the text. response.usage reports how many tokens (small chunks of text) went in and out, which is what you are billed for.

uv run hello_claude.py

Arjun’s fourth surprise: it failed.

anthropic.AuthenticationError: Error code: 401 - {'type': 'error',
'error': {'type': 'authentication_error', 'message': 'invalid x-api-key'}}

main.py had just shown the right key. Priya asked one question: “Have you ever set this variable another way on this laptop?” He had: months ago, following a tutorial, he had added an old, revoked key to his shell’s startup file. load_dotenv() does not overwrite environment variables that already exist, so the old key won. He removed the line from his shell startup file, opened a new terminal, and ran it again.

You should now see something like:

Yes, we have a lovely range of eggless cakes, including chocolate truffle and pineapple!
Tokens in: 31 out: 24

Your wording will differ, because models do not produce identical text every time. A call this size costs a tiny fraction of a cent. Now look at that answer critically. The model has no idea what Crumb sells. It invented chocolate truffle and pineapple because that is what a bakery assistant usually says. That is the hallucination from the last lesson, live on your laptop, and fixing it properly is what Module 09 is for.

import os

from dotenv import load_dotenv
from google import genai

load_dotenv()
client = genai.Client()  # reads GEMINI_API_KEY

response = client.models.generate_content(
    model=os.getenv("GEMINI_MODEL", "gemini-2.5-flash"),
    contents="You are Crumb's support assistant. Do you have eggless cakes? One sentence.",
)
print(response.text)

Finally, run it from VS Code. Open hello_claude.py. Press Ctrl+Shift+P (Cmd+Shift+P on macOS), choose Python: Select Interpreter, and pick the one inside .venv. Click the play button at the top right. You should see the same output in VS Code’s built-in terminal. If the editor underlines import anthropic in red, it is using the wrong interpreter; select the .venv one again.

Save your progress: git add . then git commit -m "First model call". Check once more that git ls-files does not list .env.

When it does not work

Recap

• Your workshop: a terminal, uv (which installs and manages Python 3.12), git, and VS Code with the Python extension.
• uv init, uv add and uv run create a project, record its libraries, and run code in its private virtual environment.
• Secrets go in .env, loaded with python-dotenv; .env goes in .gitignore before your first commit.
• Prepaid credit with auto-reload off, plus a spending limit, caps what a bug can cost you.
• New terminal windows pick up newly installed tools; existing environment variables beat .env.

At 11:10 a.m., Arjun walks over to Meera with the laptop and shows her the eggless cake answer.

“So it works,” she says.

“The plumbing works,” Arjun says. “My laptop can safely talk to the model, my key is locked away where git cannot leak it, and the account cannot spend more than five dollars even if I write a terrible loop. But look: it invented two cakes we do not make. The pipe is connected. Now I have to learn what to send through it.”

“How long did it take?”

“Seventy minutes. It would have been fifteen if I had read the error messages properly the first time.”

Priya grins. “Which is exactly what the Developer Toolkit is for. Next: the terminal, without fear.”

Go deeper

• uv documentation: installation options, projects, and Python versions.
• Anthropic documentation: getting started, API keys and the Messages API.
• The Python tutorial: the official introduction, if Python itself is new to you.