OrgAI Lab — Workshop Setup Guide

Everything you need to get started. Follow the steps in order.

You don’t need to pay for anything. All tools you install here (Node.js, Git, Claude Code) are free. During the workshop, Claude Code usage is covered by NHH through shared API keys. You do not need to create an account or enter payment details.

Before you start: What is a terminal?

A terminal is a text-based window where you type commands. Instead of clicking buttons, you type a command and press Enter. You’ll use it to install tools and run the platform.

You don’t need to understand the commands. Just copy and paste them exactly as shown.

How to open a terminal

macOS:

Press Cmd + Space to open Spotlight
Type Terminal and press Enter

Windows:

Press the Windows key
Type PowerShell and press Enter
A blue window should appear. This is your terminal

Windows note: All Windows instructions in this guide are for PowerShell (the blue window). Do not use the older “Command Prompt” (black window). Some commands won’t work there.

Keep your terminal open throughout the setup. All commands below should be typed (or pasted) into this window.

Prerequisites (install at home before the workshop if possible)

Install these before the workshop if possible:

1. Node.js

Node.js is a program that runs the OrgAI Lab platform. You don’t interact with it directly, it just needs to be installed.

Go to nodejs.org
Click the green “Get Node.js” button
The download page picks the right version for your machine. Check that it says Windows Installer (.msi) or macOS Installer (.pkg), then download
Run the installer and accept all defaults

After installing, verify it by pasting this into your terminal and pressing Enter:

node --version

You should see a version number starting with v24 or higher (e.g., v24.x.x). Version v22 also works.

2. Git for Windows (Windows only)

Windows users also need Git installed:

Go to git-scm.com/install/windows
Click “Click here to download” and run the installer
Accept all defaults
Verify that bash is available (Claude Code needs this). Open a new PowerShell and type:
```
bash --version
```
You should see something starting with GNU bash, version 5. If you get an error, bash is not on PATH. Run this:
```
$env:Path += ";C:\Program Files\Git\bin"
```
Try bash --version again. If it still fails (e.g., if you installed Git without admin rights), try instead:
```
$env:Path += ";$env:USERPROFILE\AppData\Local\Programs\Git\bin"
```
This PATH change only applies to the current terminal window. If you open a new PowerShell, you’ll need to run it again. You can permanently add the folder to PATH via “Edit environment variables for your account” in Windows Settings.

Mac users can skip this, as Git is already installed.

Step 1 — Install Claude Code (done during the workshop)

Claude Code is the AI tool you’ll use during the workshop. Paste the command for your operating system into your terminal:

Windows: Installer can’t find bash? Go back to prerequisite 2 (Git for Windows) and verify that bash --version works in your terminal. You can also set the path directly: $env:CLAUDE_CODE_GIT_BASH_PATH="C:\Program Files\Git\bin\bash.exe" (or "$env:USERPROFILE\AppData\Local\Programs\Git\bin\bash.exe" without admin rights).

PATH warning after install? If the installer says .local\bin is not in your PATH, add the folder it mentions to your user PATH (search “environment variables” in Windows settings), then restart PowerShell before continuing.

macOS:

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

Windows (PowerShell):

irm https://claude.ai/install.ps1 | iex

After it finishes, verify the installation:

claude --version

If it prints a version number, you’re good. If you get an error, close your terminal, open a new one, and try claude --version again.

Already have Claude Code installed? Great, skip the install command and just verify with claude --version. You don’t need to log out or change your account. The setup script in Step 3 sets environment variables that automatically switch Claude Code to the workshop’s shared keys for this terminal session. Your personal account is not affected and will work normally in any other terminal.

Step 2 — Download OrgAI Lab

The download URLs will be provided by the instructor. You need two links: one for the platform (a .tar.gz file) and one for the setup script.

Paste the commands below, replacing the entire <PLATFORM_URL> (including the < and >) with the link from the instructor:

macOS:

curl -fsSL "<PLATFORM_URL>" -o orgai-lab.tar.gz
mkdir -p ~/orgai-lab
tar -xzf orgai-lab.tar.gz -C ~/orgai-lab --strip-components=1

Windows (PowerShell):

curl.exe -fsSL "<PLATFORM_URL>" -o orgai-lab.tar.gz
mkdir -Force $env:USERPROFILE\orgai-lab | Out-Null
tar -xzf orgai-lab.tar.gz -C $env:USERPROFILE\orgai-lab --strip-components=1

These commands download a compressed file, create a folder, and unpack the platform into it. You don’t need to understand the details. Just paste and press Enter.

Step 3 — Run the workshop setup script

Download the setup script into your orgai-lab folder, replacing the entire <SETUP_SCRIPT_URL> (including the < and >) with the link from the instructor. Then run it.

The setup script does two things:

Sets up Claude Code keys in your terminal session (so you can run claude)
Writes platform keys to a file (.env) so the platform can use the AI evaluation features

macOS:

cd ~/orgai-lab
curl -fsSL "<SETUP_SCRIPT_URL>" -o workshop-setup.sh
source ./workshop-setup.sh

Important (macOS): You must use source before the command. If you just type ./workshop-setup.sh, the API keys will not be available in your terminal.

Windows (PowerShell):

cd $env:USERPROFILE\orgai-lab
curl.exe -fsSL "<SETUP_SCRIPT_URL>" -o workshop-setup.ps1
Get-Content .\workshop-setup.ps1 -Raw | iex

You should see a green confirmation message with the resource name and model versions. If you don’t, ask the instructor for help.

Step 4 — Start the platform

You need two terminal windows: one for the platform and one for Claude Code. The platform runs continuously in its own terminal. The terminal you have been using becomes Terminal 1 (for Claude Code).

Open a new terminal window — this becomes Terminal 2 (for the platform):

macOS: press Cmd + N in Terminal
Windows: open PowerShell from the Start menu again

Start the platform in Terminal 2:

macOS:

cd ~/orgai-lab
./start.sh

Windows (PowerShell):

cd $env:USERPROFILE\orgai-lab
.\start.ps1

Your browser should open automatically to the setup page. If it doesn’t, open your browser and go to http://localhost:3000/setup.

You do not need to run the setup script again in this terminal. The platform reads its keys from the .env file that the setup script created in Step 3.

Step 5 — Verify everything works

On the setup page, check that:

All health checks show green checkmarks
The getting-started guide is visible

Then, switch back to Terminal 1 (where you ran the setup script) and type:

claude --version

If it prints a version number, you’re ready for the workshop! You now have:

Terminal 1 — for running Claude Code (claude)
Terminal 2 — running the platform (leave it open)

Troubleshooting

Problem	Solution
`claude: command not found`	Close your terminal, open a new one, and try again. If it still fails: macOS — run `echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc`, then try `claude --version`. Windows — check that the folder the installer mentioned is in your PATH (see PATH warning in Step 1). If nothing helps, re-run the install command from Step 1.
`node: command not found`	Install Node.js from nodejs.org (see Prerequisites above).
Node.js version too old	Run `node --version`. If below v22, download the LTS version from nodejs.org.
Authentication errors (Claude Code)	Make sure you ran the setup script (Step 3) in the same terminal where you’re running `claude`. If you closed that terminal, open a new one and run the setup script again.
AI evaluation not running	The platform reads keys from the `.env` file created by the setup script. If it’s missing, run the setup script (Step 3) again, then restart the platform.
Claude Code install fails — can’t find bash (Windows)	Go back to prerequisite 2 and run `bash --version`. If it fails, run `$env:Path += ";C:\Program Files\Git\bin"` (or `$env:Path += ";$env:USERPROFILE\AppData\Local\Programs\Git\bin"` without admin) and try again. Alternative: `$env:CLAUDE_CODE_GIT_BASH_PATH="C:\Program Files\Git\bin\bash.exe"`.
Script won’t run (Windows)	Use `Get-Content .\workshop-setup.ps1 -Raw \| iex` instead of `. .\workshop-setup.ps1`. This bypasses execution policy restrictions.
Platform won’t start	Check that Node.js is installed: `node --version`. You need v22 or higher.
Port already in use	Close the program using port 3000 and try again. You can also set a different port: run `PORT=4000 ./start.sh` (macOS) or `$env:PORT=4000; .\start.ps1` (Windows) before starting.
Something else	Run `claude doctor` in your terminal for a diagnostic check, or ask the instructor.

Good to know

Claude Code keys only last for your current terminal session. If you close the terminal where you ran the setup script, open a new one and run the setup script (Step 3) again before using claude.
Platform keys persist in a file. The platform reads its keys from the .env file created by the setup script. You can restart the platform without re-running the setup script.
The platform and Claude Code are independent. You can restart one without affecting the other.
Please don’t share the API keys outside this workshop.
Need to update the platform? If the instructor asks you to download a new version, stop the platform (press Ctrl + C in Terminal 2) and run:

macOS:

cd ~/orgai-lab
curl -fsSL "<PLATFORM_URL>" -o orgai-lab.tar.gz
tar -xzf orgai-lab.tar.gz -C ~/orgai-lab --strip-components=1
./start.sh

Windows (PowerShell):

cd "$env:USERPROFILE\orgai-lab"
curl.exe -fsSL "<PLATFORM_URL>" -o orgai-lab.tar.gz
tar -xzf orgai-lab.tar.gz --strip-components=1
.\start.ps1

Replace <PLATFORM_URL> with the new link from the instructor. You do not need to re-run the setup script.