4  Setting Up Your Machine

Keywords

Quarto, reproducible publishing, coding agents, Markdown, Python, EPUB, data analysis, k-means clustering

This chapter ends with a number: 42, printed in a web page and a PDF that your own computer built. Getting it there proves that the agent, Python, Quarto and Typst work together. That is all the hands-on parts need, because everything in them happens on your machine: the agent writes files in your folders, Quarto renders them there, and you open the results in your own browser and word processor. It takes six steps, and each ends with a check you can see, so you always know whether a step worked before you move on.

Do the setup somewhere calm, with a good connection, and allow about an hour. Mac and Linux readers can follow this chapter straight through. Windows readers first install Ubuntu, a version of Linux, inside Windows with WSL, the Windows Subsystem for Linux; Appendix A walks through that one step at a time, and from then on they follow this chapter inside Ubuntu.

In this chapter
  • Install Git, a coding agent, Quarto, uv and gh, checking each step before the next.
  • Move around the terminal, and tell the terminal from the agent when you type.
  • Run the setup check and read its report.
  • Render a test document to HTML and PDF, and confirm that both say 42.

Start froma computer you can install software on, a good connection and the accounts listed in Section 4.1; on Windows, Ubuntu set up with Appendix A.

You buildthe tools, installed and signed in; ~/quarto-workshop, the workshop’s files with their checkpoints; and a throwaway ~/quarto-test whose hello.html and hello.pdf say 42.

Checkpointnone, because setup builds no project to catch up to. The workshop’s files arrive in Step 5, with the checkpoints and the starter that Chapter 5 opens: a real report you can read.

4.1 Before you start

A stable, fast connection. Almost every step downloads something: on Windows the Ubuntu image (several hundred megabytes), then Quarto, uv (which manages Python for each project) and Python packages, the agent itself and the example projects with their data. The agent also sends every request to its model over the internet, so a weak connection shows up as long pauses, timeouts and half-finished installs, which are easy to mistake for your own errors. Use a wired connection or strong Wi-Fi, and avoid a VPN (a virtual private network, which sends your traffic through another network) where you can. On a company network, expect a proxy, a server that all web traffic must pass through, to block some downloads; a personal connection avoids it.

Two accounts. A free GitHub account, used to publish in the hands-on parts, and an account with access to one coding agent. Claude Code needs a Pro, Max, Ultra, Team, Enterprise or Console account; Codex a ChatGPT sign-in or an API key (for pay-per-use billing, Section 2.2); Antigravity a Google account (checked 2026-11-18; Appendix K keeps the current list). An API key is a long secret string that identifies your account to the vendor’s programming interface, which bills each request; keep it out of files you share. Sign-up and email verification can take hours, so do them first.

The low-cost route. The book needs one agent, not the most expensive one. Two routes keep the cost down. The first costs nothing: a personal Google account can use Antigravity on its free tier, with a quota refreshed weekly (checked 2026-11-18), and every prompt in the book is written to work in Antigravity too, although its screens were not captured for it (Section 2.2). The second is to pay only for what you use, with an API key, after setting a monthly cap on the vendor’s site: a Claude Console account can cap Claude Code’s monthly spending with a workspace spend limit, and an OpenAI API organization or project can set a hard monthly spend limit, after which requests stop (both checked 2026-11-18). With either, choose a small model at medium effort (Section 2.3), and start a fresh conversation for each task.

No install rights? If you cannot install software, on a locked-down work laptop or a Windows computer where WSL is not allowed, use the workshop’s ready-made environment in your browser instead (Section 4.8) and skip Steps 1 and 4.

A plan for when a step fails. Errors during setup are normal: each step depends on your system, your network and that week’s versions, so an error does not mean you have failed. It tells you what to fix:

  1. Look the message up in Appendix D, whose Setup table lists failures seen in practice, with tested fixes.
  2. If it is not there, ask a web chat in your browser (Claude, ChatGPT and Gemini each have a free plan, checked 2026-11-12), not the agent: installs can fail before it is working, and sometimes the agent is what fails. Paste the command you ran and the whole error message, with a sentence saying your system (“Mac”, or “Windows with Ubuntu on WSL”) and which step you are on.
  3. Try one suggested fix at a time, and read each suggested command before you run it. Never paste passwords, keys or private data.
  4. If two suggestions fail, ask a person: your group’s help channel, or a colleague.

The six steps, and how you know each one worked:

Table 4.1: The setup steps and their checks.
Step Do this It worked when
1 Get the computer ready (Section 4.2) git --version prints a version
2 Move around the terminal (Section 4.3) after cd ~ the prompt shows ~
3 Install a coding agent (Section 4.4) it starts, signed in, and answers
4 Let the agent install the tools (Section 4.5) it prints every version
5 Run the setup check (Section 4.6) every check reports OK
6 Do the test run (Section 4.7) hello.pdf says 42

4.2 Step 1: Get the computer ready

The later steps assume two small programs: git, for version control, and curl, which downloads a file from a web address. Open a terminal, the window for typing commands that Step 2 explains (on a Mac: Command-Space, type Terminal, Enter; on Ubuntu: Ctrl+Alt+T), and run the line for your system.

On a Mac, install Apple’s Command Line Tools, which include git:

xcode-select --install

A dialog asks to install them: click Install and wait. Doing this deliberately now matters, because otherwise the dialog appears the first time anything uses git, which would be in the middle of Step 4 while the agent is waiting. “Already installed” is fine.

On Ubuntu or Debian (including Ubuntu on Windows):

sudo apt update && sudo apt install -y curl git

apt is Ubuntu’s package manager, the program that installs software from Ubuntu’s own collection and keeps it up to date; apt update refreshes its list, and apt install installs. sudo runs a command as the administrator and asks for your Linux password, which stays invisible as you type. On other Linux distributions, install curl and git with your usual package manager. On Windows, follow Appendix A first: it ends with this same command, run inside Ubuntu.

ImportantTry it

Run git --version in the terminal.

You’re done when it prints a version number. On Windows, you are in Ubuntu and wsl -l -v, run in PowerShell, shows Ubuntu with VERSION 2.

4.3 Step 2: Move around the terminal

The rest of the book happens in a terminal, a window where you type commands instead of clicking. When it is ready for a command it shows a prompt, a line ending in $ (or % on a Mac), which tells you who and where you are (not to be confused with a prompt you give an agent):

ana@laptop:~/demo$

ana is the user, laptop the computer, and ~/demo the current folder: ~ is your home folder, so this is a folder called demo inside it. Eight commands are enough to move around:

Table 4.2: Moving around the terminal.
Command Does
pwd prints the folder you are in (print working directory)
date prints the date and time
ls lists what is in this folder
mkdir name makes a folder
cd name goes into a folder
cd .. goes up one folder
cd ~ goes straight home, from anywhere
rmdir name removes an empty folder (it refuses if anything is inside)

Figure 4.1 runs them in order. Type them yourself rather than pasting: the hands remember.

A terminal session with the prompt ana@laptop. pwd prints the home folder. date prints the date and time. mkdir demo makes a folder, and ls lists it. cd demo goes in, and the prompt now ends in tilde slash demo. mkdir notes and cd notes go one folder deeper, and pwd prints the full path ending in demo slash notes. cd dot dot goes up one level, cd tilde goes straight home, and rmdir demo slash notes demo removes both empty folders.
Figure 4.1: Moving around the terminal: each command, and what the terminal answers. A real recording, made with a demo account whose home folder is /tmp/home/ana; yours is /home/<you> on Linux and Windows, or /Users/<you> on a Mac.

Two keys save most typing mistakes: Tab completes a file or folder name, and the up arrow brings back the previous command. Copying and pasting work differently in a terminal: select the text, then Ctrl+Shift+C copies and Ctrl+Shift+V pastes (Command-C and Command-V on a Mac), because Ctrl+C on its own stops the running program (Table B.3). Two commands start most projects in this book, one line each:

mkdir -p london-guide
cd london-guide

The first makes the folder, and -p makes mkdir quietly accept a folder that already exists, so running it twice does no harm. The second goes into it. Later chapters often join the two lines into one with &&, which means “and then, if that worked”:

mkdir -p london-guide && cd london-guide

If mkdir fails, cd does not run. Appendix B has more keys and habits.

ImportantTry it

From your home folder, type the commands in Table 4.2 in the order shown in Figure 4.1.

You’re done when rmdir raised no error, and the prompt shows ~.

4.4 Step 3: Install a coding agent

Pick one agent and run its installer, the vendor’s own documented command (checked 2026-10-30). Run only the line for your agent.

Claude Code:

curl -fsSL https://claude.ai/install.sh | bash

Codex:

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

Antigravity:

curl -fsSL https://antigravity.google/cli/install.sh | bash

curl … | bash downloads a small install script and runs it immediately. That is normal for these tools, and it is also exactly why you should only do it with links you trust, such as each vendor’s documented command.

Then open a new terminal tab (Ctrl+Shift+T on Ubuntu, Command-T on a Mac, Ctrl+Shift+D in Windows Terminal). A terminal learns where programs are when it starts, from its PATH, the list of folders it searches for programs, so it cannot find one installed a moment ago, which is the usual cause of command not found straight after an install. On a Mac, a new tab is not enough for Claude Code: its installer puts it in ~/.local/bin, a folder the PATH leaves out, and prints the fix under “Setup notes”. Paste that fix into the terminal, press Enter, then open the new tab (Claude Code, installation troubleshooting, checked 2026-11-06).

Start the agent in a fresh folder. Type the three lines one at a time: make the folder setup in your home folder (-p: no complaint if it exists), go into it, and start the agent:

mkdir -p ~/setup
cd ~/setup
claude

That last line starts Claude Code; type codex for Codex, or agy for Antigravity.

The first start walks through three screens. Claude Code’s are shown below as captured on 2026-11-07 (version 2.1.319, in an empty folder, with folder names changed); the screens change between versions, so yours may differ in wording. Before them, Claude Code asks for a text style: press Enter to keep the one selected.

Sign in. Choose the option for your account: the first for a subscription, the second for an Anthropic Console account billed by API use. The agent opens your browser; where there is none, as in WSL, it prints a link to copy into your browser, and then a code to paste back into the terminal. Codex’s first screen (version 0.167.0, captured the same day) offers “Sign in with ChatGPT”, which works the same way, and “Sign in with Device Code”, a one-time code to use when the browser sign-in fails.

 Select login method:

 ❯ 1. Claude account with subscription · Individual, Team, or Enterprise
   2. Anthropic Console account · API usage billing
   3. 3rd-party platform · Amazon Bedrock, Microsoft Foundry, Google Vertex AI

Trust the folder. The pointer starts on “No, exit”, so pressing Enter straight away quits. Press the down arrow first. Quitting by mistake is harmless: type claude again. Codex asks nothing in a plain folder like ~/setup; it asks the same question later, in a project that is a Git repository.

 Accessing workspace:

 /home/ana/setup

 Quick safety check: Is this a project you created or one you trust?
 (Like your own code, a well-known open source project, or work from
 your team). If not, take a moment to review what's in this folder first.

 Claude Code'll be able to read, edit, and execute files here.

 ❯ No, exit
   Yes, I trust this folder

 Enter to confirm · Esc to cancel

Ready. The agent shows its version, the model and plan of the account you signed in with, and the folder, then waits for a prompt on the line marked ❯. In this capture the logo beside the first lines is left out, and the model and plan are those of the account that captured it; yours shows your own.

 Claude Code v2.1.319
 Opus 5.5 with xhigh effort
 Claude Max
 ~/setup
────────────────────────────────────────────────────
❯ Try "write a test for <filepath>"
────────────────────────────────────────────────────
ImportantTry it

Install one agent, start it in ~/setup, sign in and trust the folder.

You’re done when the agent answers when you type hello. Then type /exit.

4.4.1 Two places to type

Now that an agent is installed, there are two places to type, and mixing them up costs beginners more time than anything else.

ana@laptop:~/setup$ pwd                  <- the terminal: commands
❯ Which tools are missing?                <- the agent: requests in plain language

The agent takes over the terminal tab it runs in: what you type there goes to the agent, not to the shell, the program behind the terminal that runs your commands, until you leave with /exit. Commands in this book’s You do boxes, such as quarto preview, go in the terminal; prompts in Ask your coding agent boxes go to the agent. When the agent is busy and you need the terminal, open a second tab, as after the install.

Typing in the wrong place is usually harmless: a prompt typed at $ gives command not found, and a command typed into the agent is read as a request. Look at the line you are on and try again.

Pause and think

The agent is running and the book says to type gh auth login, the GitHub sign-in of Step 5. Where do you type it?

Answer

In a second terminal tab: gh auth login is an interactive sign-in that needs you, and the agent is using the first tab. Leaving the agent with /exit also works, but ends the conversation.

4.5 Step 4: Let the agent install the tools

The remaining tools are Quarto itself, uv, Git and the GitHub command-line tool gh. Each has its own official install method for each system, which is exactly the kind of detail an agent handles well. Start it again in the setup folder, now as one line joined with && (with codex or agy in place of claude if that is your agent, here and in the next steps):

You do
mkdir -p ~/setup && cd ~/setup && claude
Ask your coding agent
Check which of `git`, `curl`, `uv`, `quarto` (1.10 or newer) and the GitHub CLI `gh` are missing on this computer. Install only those, using each tool's official method for my system. Never run `sudo`, or an installer that asks for a password, yourself: print each such command alone in a code block, using full paths, then wait until I say done. Then print every version.
Expect it to run

installs uv with its official installer · Quarto from its release page (or with Homebrew, a package manager for the Mac, if you have it) · gh from GitHub’s own package source · prints versions

Before each command it wants to run, the agent stops and asks, as in Figure 2.4: read the command (the pitfall in Section 2.9 says what to look for), then approve it.

The prompt is written around one limitation: an agent cannot type your password. So it asks the agent to hand back any command that needs one, with full paths, because the second tab you paste it into starts in your home folder. Copy the command (Ctrl+Shift+C, or Command-C on a Mac), paste it in a second tab, type your password when sudo asks (it stays invisible), and then type done in the agent’s tab. On a Mac, the password is your login password.

NoteWhy this works

Quarto has no Ubuntu package in the standard repositories, and Ubuntu’s own gh package is discouraged by GitHub, so a generic apt install would get one tool wrong and the other missing. The prompt’s “each tool’s official method” sends the agent to the right source for each (Quarto’s download page and GitHub’s install instructions for Linux, checked 2026-10-30).

Pause and think

The agent has installed uv. In a terminal tab you opened before that, you type uv --version, and the terminal answers command not found. Did the install fail?

Answer

Probably not. uv’s installer puts it in ~/.local/bin, which a terminal adds to its PATH only when it starts, so a tab opened earlier cannot find it. Open a new tab and try again; only if it fails there is the install at fault.

ImportantTry it

Paste the prompt, approve the commands you have read, and run any sudo command it hands you in a second tab.

You’re done when it prints a version for all five tools. Then type /exit: uv and Quarto are only found by a terminal started after they were installed.

4.6 Step 5: Run the setup check

Open a new tab and start the agent again, so that it sees the newly installed tools:

You do
cd ~/setup && claude
Ask your coding agent
Print the versions of `quarto` (1.10 or newer), `uv`, `gh` and this agent, and run `quarto check` (no Jupyter or LaTeX yet is fine: count it as OK). If `git config --global user.name` or `user.email` is unset, ask me for my name and my GitHub email, then set them. Clone https://github.com/project-delphi/quarto-workshop.git to `~/quarto-workshop` (if it exists, `git pull` only when its working tree is clean) and list its `checkpoints/`. Run `gh auth status`. Run every check even if one fails, then report each as OK or not.

Three parts of this check deserve a word.

quarto check reports Quarto’s own components, including Pandoc and Typst. Its Python and Jupyter lines may say they are missing, and that is fine: each project in this book gets its own Python environment from uv, so there is nothing to install for Python now. No LaTeX is needed either, because PDFs are made with the Typst engine bundled in Quarto.

A fresh Git has no identity, and git commit refuses to run without one. The prompt makes the agent ask you for your name and email, so you type your own; check that what it set is yours, not a placeholder.

To clone is to copy a repository, with its history, to your computer: here the workshop’s, into ~/quarto-workshop. It holds the finished examples, the water dataset, the starter report for Chapter 5 and the checkpoints: snapshots of each project at the end of each hands-on block, which you will use to catch up if you fall behind.

You do

if gh is not “Logged in”: in a second tab, gh auth login → GitHub.com → HTTPS → Yes → log in with a web browser; copy the one-time code to github.com/login/device; then ask the agent to check gh again

ImportantTry it

Run the setup check.

You’re done when the agent reports every check as OK, including gh “Logged in”.

4.7 Step 6: The test run

The setup check proves the tools are installed. The test run proves they work together: the agent can write a file and run commands you approve, uv can build a project environment, Quarto can run Python through it, and Typst can write a PDF.

You do
mkdir -p ~/quarto-test && cd ~/quarto-test && claude
Ask your coding agent
Run `uv init --bare` and `uv add ipykernel nbclient nbformat pyyaml`. Create hello.qmd (html and typst formats): a Python cell computing `6 * 7` and an inline-code sentence showing it. Render it with `uv run quarto render hello.qmd`; check hello.html and hello.pdf both say 42.
Expect it to run

uv init --bare · uv add … · writes hello.qmd · uv run quarto render hello.qmd → hello.html, hello.pdf

You do

/exit, then open the folder: open . (Mac), xdg-open . (Linux) or explorer.exe . (WSL), and open both files

The test run uses three things the next chapters teach, on purpose: it is a check that the tools work together, not a lesson, so you need not understand the file to pass it. Its file will look much like this one, which the agent’s may differ from in detail:

---
title: "Hello"
format:
  html: default
  typst: default
---

```{python}
answer = 6 * 7
```

The answer is `{python} answer`.

Reading it from the top, with where each part is explained:

  1. Settings, between the two --- lines: a title and two formats, a web page and a PDF. They are written in YAML (Section 1.2; in full, Section 7.2).
  2. A code cell, the fenced block whose language is in braces: Python that runs when the file is rendered (Section 7.1).
  3. Inline code, `{python} answer`: the cell’s result, written into the sentence, so the 42 is computed, not typed (Section 7.3).

Chapter 5 then opens a real report of the same kind, which you read and render yourself.

WarningCommon pitfall

Every render prints a line such as [IPKernelApp] WARNING | Kernel is running over TCP without encryption. It is harmless: Quarto talks to the Python kernel, the running Python process that executes the cells, over a local connection on your own computer, and in every dry run the warning came with a successful render and changed nothing in the output.

ImportantTry it

Run the test run and open both outputs.

You’re done when hello.html and hello.pdf both say 42. The folder is disposable: delete ~/quarto-test afterwards. If a file is missing or says something else, see the Python and Jupyter table in Appendix D.

4.8 Without installing anything: a codespace

A codespace is a computer that GitHub runs for you, opened in your browser: a terminal, a file browser and an editor, with nothing installed on your own machine. The workshop’s repository describes one in a dev container file, .devcontainer/devcontainer.json, which lists what to install: Quarto 1.10.20, uv, Git and the GitHub CLI. So in a codespace, Steps 1 and 4 are already done.

You do

on github.com/project-delphi/quarto-workshop: Code → Codespaces → Create codespace on main · wait while it builds · then, in its terminal, cd ~

The repository appears in your home folder as ~/quarto-workshop, so every path in this book works unchanged. From there, follow Step 2, Step 3 with the agent’s Linux command, Step 5 and Step 6 in the codespace’s terminal. Three things differ from a computer of your own:

  • Previews. Start them with quarto preview --port 4848 --host 0.0.0.0 --no-browser; the codespace offers to open the page in a new browser tab.
  • Signing in to GitHub. If gh auth login says that GITHUB_TOKEN is in use, run unset GITHUB_TOKEN first: the codespace’s own token reaches only the workshop’s repository, not repositories you create.
  • Cost. A free personal GitHub account includes 120 hours of Codespaces compute a month, counted twice over on the default two-core machine, so about 60 hours of use, and 15 GB of storage (checked 2026-11-18). Stop the codespace when you finish (the Codespaces page lists it), because a running one uses the allowance.

The environment was built from its dev container file and checked on a local computer (Quarto, uv, Git and the GitHub CLI present; the first report and the test run rendered); a codespace on GitHub’s computers was not tested for this edition.

Summary

  • Everything in the hands-on parts happens on your own machine, so setup proves that the agent, Python, Quarto and Typst work together there.
  • Each step ends with a check you can see; move on only when it passes.
  • Commands go at the terminal’s prompt and requests to the agent; when the agent is busy, open a second tab.
  • A terminal finds only programs it knew of when it started, so after an install, open a new tab before suspecting the install.
  • The agent cannot type your password: it hands commands that need one back to you, and you read every command before you approve it.
  • When a step fails, look in Appendix D, then ask a web chat with the command and the whole error, one fix at a time, and never paste secrets.

The test run was a black box: a file you did not write, settings you have not met, code you have not read. Chapter 5 puts your hands on a real report before any agent does: you copy it, render it yourself, check its numbers against its data and find the wrong one, and record it with Git, so that every later change can be seen and undone. Only then does the agent make its first edit, and you check it. Part II then explains what was in the box: starting from an empty folder, you write the London guide for the tourism office one Markdown construct at a time, and by the end of Chapter 6 it is a web page with written rules for the agent.

Further reading