Set up your machine

Author

Sadamori Kojaku

Published

August 25, 2026

Reading these notes needs nothing, and neither does the code in them: every hands-on page carries a Run this notebook link that opens in your browser and fetches Python for you.

This page is for the work you hand in. The Pair Notebook and the group mini-project both live in a GitHub repository on your own computer, and both need the same things: a terminal, git, a GitHub login, two small runtimes, one environment variable, and pi — the AI agent your tutor runs on.

About twenty minutes, once per machine. Do it before the second week. Getting stuck here is not part of any assignment — ask in #network-science on Discord.

1. Open a terminal

A terminal is an app where you type commands instead of clicking. Every command on this page goes in one.

Press ⌘ + Space, type Terminal, press enter. The shell it opens is zsh, which is what the commands below assume.

Start menu → type Terminal → open Windows Terminal (it starts PowerShell).

Step 2 also installs Git Bash, a second terminal that understands the same commands as macOS. Everything on this site is written for Git Bash, so once you have it, prefer it: Start menu → type Git Bash. Your home folder there is /c/Users/<you>. Where a command differs between the two, this page says so.

Five commands get you anywhere:

Command What it does
pwd prints which folder you are in right now
ls lists what is in that folder (dir in PowerShell)
cd some-folder goes into some-folder
cd .. goes back up one folder
cd ~ goes to your home folder

Two habits that save a lot of typing: press Tab to finish a name you have half-typed, and press ↑ to bring back the command you just ran. To paste, use ⌘ + V on macOS and Ctrl + Shift + V (or a right-click) on Windows.

2. Install the tools

Four installs, whatever your operating system. Run the command for your system in the terminal you just opened.

Install What it is for Windows macOS
git keeps the history of your work, and hands it in winget install Git.Git xcode-select --install
GitHub CLI signs git in to GitHub winget install GitHub.cli brew install gh
Node.js 24+ your AI tutor runs on it winget install OpenJS.NodeJS brew install node
uv fetches Python and runs the notebooks winget install astral-sh.uv brew install uv

winget ships with Windows 11, so a Windows machine is ready to run those four commands as they stand.

NotemacOS: brew: command not found

brew is Homebrew, and it is not on a new Mac. Install it once — paste this in, press enter, and answer the prompts (it asks for your password and takes a few minutes):

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

The installer finishes by printing two or three commands to run — run them, or brew will still be missing in your next terminal. Then:

brew install gh node uv

Prefer not to install Homebrew? Every tool has an installer of its own: Node.js has a macOS .pkg at nodejs.org, uv installs with curl -LsSf https://astral.sh/uv/install.sh | sh, gh has a .pkg on its releases page, and git comes with xcode-select --install.

Close the terminal and open a new one — a terminal never notices programs that were installed after it started. Then check all four:

git --version
gh --version
node --version   # v24 or newer
uv --version

Four version numbers means you are done. command not found means either the install did not finish, or this window was open while it ran.

3. Sign in to GitHub

  1. Create an account at github.com if you do not have one. Pick a username you do not mind classmates seeing: your assignment repositories are named after it.

  2. Watch your Binghamton email for an invitation to the course’s GitHub organization, and accept it. Until you do, no grade can reach you: enrollment here is GitHub membership, not the class list.

  3. Sign git in to GitHub, once per machine:

    gh auth login

    Answer GitHub.com → HTTPS → Login with a web browser, and paste the code it shows into the page it opens. This is what makes git clone and git push work silently. GitHub stopped accepting account passwords from git in 2021, so without this step a push fails with a confusing authentication error.

  4. Tell git whose commits these are:

    git config --global user.name "Your Name"
git config --global user.email "you@binghamton.edu"

4. Set your course API key

An environment variable is a named value your terminal hands to every program it starts. Your AI tutor reads one called NETSCI_API_KEY; that key is how it reaches the course’s language models, so you never need an account or a credit card of your own.

Where the key comes from. The instructor issues one key per student and sends it to your Binghamton email in the first week. It looks like sk-nsci-…, and it is yours alone — its usage is logged against your name. If it has not arrived before your first Pair Notebook session, or you have lost it, email the instructor: keys are reissued, never looked up.

Set it once, in the file your shell reads at startup, so every future terminal has it.

Add this line to the end of ~/.zshrc (macOS) or ~/.bashrc (Git Bash), with your own key in place of the dots:

export NETSCI_API_KEY="sk-nsci-..."

Rather not open an editor? This appends the same line for you, creating the file if it does not exist. Put your own key in first, then paste the whole command:

echo 'export NETSCI_API_KEY="sk-nsci-..."' >> ~/.zshrc   # ~/.bashrc in Git Bash

Then open a new terminal and check:

echo $NETSCI_API_KEY

Run this once. setx only affects terminals opened afterwards, so the window you type it in will not see it:

setx NETSCI_API_KEY "sk-nsci-..."

Then close the window, open a new one, and check:

echo $env:NETSCI_API_KEY

Your key printed back means it is set. Nothing printed means either this window was open before you set it, or the line went into a file this shell does not read.

Paste the key on one line, with nothing around it. A key that arrives in an email is often wrapped onto two lines; join it back up.

WarningNever put the key in a file inside an assignment folder

You hand in assignments by pushing that folder to GitHub. A key committed there is a key that has to be revoked and reissued. Keeping it in your shell profile — which lives in your home folder, not in any repository — keeps it out of your history.

5. How your work is collected

The course uses Classroom 50 to hand out and collect assignments. Accepting one creates a private GitHub repository that belongs to you. You copy it to your computer, work in it, and push it back. There is no upload button anywhere.

Copy it down once per assignment:

git clone <the repository URL Classroom 50 created for you>
cd <the folder it made>

Then, every time you want to save and send what you have done:

git add -A                     # take every file you changed
git commit -m "what I did"     # save a snapshot, with a note
git push                       # send the snapshots to GitHub

git status prints what has changed and whether it has been sent yet. Run it whenever you are unsure.

Three things worth knowing:

  • Committing saves; pushing sends. Work you committed but never pushed is on your laptop only, and nobody else can see it.
  • Push often. The history shows when the work happened, and for the Pair Notebook that is part of what is read: three short sittings count exactly as much as one long one.
  • In a Pair Notebook session you never type these. You say hand it in to your tutor and it runs all three for you.

6. Install pi, your AI agent

pi is an AI agent that runs in your terminal. You type what you want in plain words; it reads the files in the folder you started it in, edits them, runs commands, and tells you what it did. There is no web page and no chat window, and nothing is copied back and forth: it is already inside the folder your work is in.

Your Pair Notebook tutor is pi, with the course’s teaching toolkit loaded. The same pi, started in any other folder, is an ordinary coding assistant — use it on the mini-project, the final project, or anything else you write.

Install it once, from any folder:

npm install -g @earendil-works/pi-coding-agent

Same command on Windows and macOS — this is what the Node.js in step 2 was for. Then open a new terminal and check:

pi --version

Point it at the course models

A fresh pi knows how to talk to language models but has an account with none of them. One script hands it the course’s. It ships inside every Pair Notebook repository, so clone your first one (step 5) and run this inside that folder:

node setup-pi.mjs

It is the same command on Windows and macOS. It registers the course models in ~/.pi/agent/models.json — a file in your home folder, so this is once per machine and not once per assignment — tells pi that this folder is yours, downloads the notebook’s Python packages so your first session starts fast, and makes one real request so you find out here, not mid-lesson, whether your key works. It is safe to re-run, it backs up any models.json you already had, and it leaves your other providers alone.

ImportantIt will look like it has hung. It has not.

The package download is a few hundred megabytes and takes a couple of minutes on a slow connection. That is the slowest part of the whole setup, and it happens exactly once. Leave it alone until it finishes.

NoteIf pi ever asks “Trust project folder?”

Answer Trust, the first option. It is asking whether this folder may set up your tutor, and this folder is your own assignment. The setup script normally answers it for you, so you will only see the question if you skipped the script or moved the folder. If you answered “Do not trust” by mistake, your tutor will start but have no notebook and no tools; run pi --approve once to undo it.

When it prints You are set, you are done. From then on, in any folder, the whole command is:

pi

Packages worth having

On its own pi can read, write and run things, and little else. Packages add to it, one command each:

pi install npm:pi-web-access

Five that earn their keep. None of them is required for any assignment in this course:

Package What it adds
pi-web-access web search, fetching a page, reading a PDF or a YouTube video — no key of its own needed
context-mode keeps long sessions coherent: what it reads is filed away and searched back, instead of being carried around
@ayulab/pi-rewind /rewind — jump back to an earlier point in the session, your files with it
@juicesharp/rpiv-ask-user-question lets the agent put a multiple-choice question to you instead of guessing
@juicesharp/rpiv-btw /btw — a one-off side question that leaves the main conversation untouched

All five in one command:

for p in pi-web-access context-mode @ayulab/pi-rewind @juicesharp/rpiv-ask-user-question @juicesharp/rpiv-btw; do pi install "npm:$p"; done
foreach ($p in "pi-web-access","context-mode","@ayulab/pi-rewind","@juicesharp/rpiv-ask-user-question","@juicesharp/rpiv-btw") { pi install "npm:$p" }

pi list prints what you have, pi update brings them all up to date, and pi remove npm:<name> takes one back out. They live in your home folder, so they follow you into every project — if one ever makes a session behave oddly, pi config turns packages on and off.

The tutor’s toolkit installs itself

The Pair Notebook’s own two packages are not on that list, and you never install them by hand. The assignment folder’s .pi/settings.json pins them, and pi fetches them the first time you run it there:

"packages": [
  "git:github.com/sk-classroom/pi-pair-notebook@v0.5.6",
  "npm:@juicesharp/rpiv-ask-user-question@2.4.0"
]

That first start therefore takes a few seconds longer than every one after it.

If the fetch fails and you want to install them by hand 
pi install git:github.com/sk-classroom/pi-pair-notebook@v0.5.6
pi install npm:@juicesharp/rpiv-ask-user-question@2.4.0
pi list     # both should be listed

Use the same version tags as the folder — a module and its toolkit are tested together.

You are set. What now?

  • Pair Notebook — your first assignment. Once step 6 is done, a single word starts every session.
  • Group Mini-Project — the in-class team assignment, and the one rule about accepting it that decides whether your team is a team.

Optional: run a module notebook on your own machine

The Run this notebook link on each hands-on page needs nothing installed. If you would rather run one locally, uv does the rest — it fetches Python and the packages listed inside the notebook itself:

git clone https://github.com/skojaku/adv-net-sci.git
cd adv-net-sci
uvx marimo edit --sandbox notebooks/m02-small-world/coding.py

uvx runs a tool without installing it permanently, and --sandbox builds a throwaway environment from the dependency list at the top of the notebook, so nothing is added to your system Python. The first run takes a minute while Python and the packages arrive; later runs are instant.

marimo is a reactive notebook: change one cell and every cell that depends on it recomputes, so what you see on screen is always what the code says. It is also a plain .py file, which is why git can track it.

Optional: GitHub Copilot

Students get GitHub Copilot Pro for free. It suggests code as you type in VS Code and in marimo (how to enable it). Using it is entirely up to you — the Pair Notebook is read for your reasoning, which no autocomplete can supply.

If something goes wrong

What you see What it means What to do
command not found right after installing something this terminal was open while the install ran close it, open a new one
pi: command not found, in a new terminal too the global npm install did not finish run it again and read what it prints: npm install -g @earendil-works/pi-coding-agent
brew: command not found (macOS) Homebrew is not installed the box in step 2
git asks for a username and password when you push git is not signed in to GitHub gh auth login
repository not found when cloning you are signed in as the wrong account, or you never accepted the assignment gh auth status, then accept the assignment again
echo $NETSCI_API_KEY prints nothing the variable is not set in this window reread step 4, then open a new terminal
winget is not recognized (Windows 10) winget ships with Windows 11 install App Installer from the Microsoft Store, or use each tool’s own installer

Anything else: ask on Discord. Setup problems are not part of any assignment, and someone else has usually hit the same one.