Setup and safety

Outcome

By the end of this lesson you will have six tools installed and one safe AWS credential set up. AWS stands for Amazon Web Services, the cloud platform this course deploys to. You will confirm the install with a set of version checks, and you will prove your AWS identity is correct with a single command. Nothing in this lesson creates a billable cloud resource, so you can finish it for free.

The six tools are Git (tracks file changes), Node.js (runs the website build and the AWS deployment tool), uv (installs Python and Python packages), Python (runs the agent code), the AWS CLI (talks to AWS from your terminal), and the AWS CDK (turns code into cloud infrastructure). CLI stands for Command-Line Interface. CDK stands for Cloud Development Kit.

Mental model

In a visual automation tool you connect connectors and sign in to each service once before you build a workflow. This lesson is that same “install the connectors and sign in” step, moved to a coding toolchain.

The tools map cleanly to ideas you already use:

• Git is your version history, like the run/version history of a saved workflow, but for the files on your computer.
• The AWS CLI and the AWS CDK are the connectors to AWS. The CLI runs one-off commands; the CDK describes the cloud resources you want and creates them for you later in the course.
• The AWS credential you set up is your signed-in connection to AWS.

Where the analogy stops: a visual tool usually stores one long-lived login per connector. In this course you will use short-lived credentials that expire on their own. That is safer, because a leaked short-lived credential stops working within hours instead of staying valid forever.

Prerequisites and cost

• A computer where you can install software (macOS, Windows, or Linux).
• A web browser and an email address.
• An AWS account you are allowed to use for learning. A separate sandbox account is strongly preferred so tutorial resources never mix with anything important.

Cost: none in this lesson. You only install local tools and configure a login. No AWS resource is created, so nothing can bill you yet. Later lessons that call a model do cost a small amount, and each of those lessons says so before you run anything.

Verified on 2026-07-15 against the primary sources in docs/research-log.md (tool minimum versions, region and model availability, and the AWS credential procedure).

Steps

Follow these in order. Each install has an official download page; use the official page rather than a search-result link.

1. Install Git. Download it from git-scm.com/downloads and accept the defaults. Git records changes to files so you can undo mistakes and see history.

2. Install Node.js (version 22.12 or newer). Download the LTS build from nodejs.org. LTS stands for Long-Term Support, the stable line. The course website build needs Node 22.12 or newer, and it does not support odd-numbered Node versions such as 23.

3. Install uv. Follow the official install guide. uv manages Python and Python packages for you, so you do not have to install Python separately by hand.

4. Install Python 3.12 with uv. In a terminal, run the two commands in the sample below. The first downloads a managed Python 3.12; the second is the version check.

5. Install the AWS CLI (version 2). Follow the official install guide. This is the tool that runs AWS commands from your terminal.

6. Install the AWS CDK. With Node.js installed, run npm install -g aws-cdk. npm is Node’s package installer and comes with Node. The CDK turns TypeScript code into AWS infrastructure in a later lesson.

7. Set up a short-lived AWS credential with IAM Identity Center. IAM stands for Identity and Access Management, the AWS service that controls who can do what. IAM Identity Center gives you a login that produces credentials which expire automatically. Do not create a long-lived access key as your default; long-lived keys do not expire and are the most common cause of leaked cloud access. Configure the login by running aws configure sso and following the prompts, then sign in with aws sso login. The two “go deeper” videos below walk through the Identity Center setup and are worth watching if this step is new to you.

8. Set an AWS cost guardrail. In the AWS Billing console, create a small monthly budget (for example, a few US dollars) with an email alert. This does not stop spending, but it warns you early if a later lesson leaves something running. Keep every lesson in the us-east-1 region (N. Virginia); the course’s model and services are confirmed available there.

9. Point the AWS CLI at us-east-1. During aws configure sso, set the default region to us-east-1 so later commands land in the right place.

Smallest code sample

These are the version checks and the identity check. Run each one in a terminal from any directory. The Python check runs from inside the agent/ folder of this course, because uv reads the pinned Python version there.

git --version
node --version
uv --version
aws --version
cdk --version

# Install and check Python 3.12 (run these from the repository's agent/ folder)
uv python install 3.12
uv run python --version

# Prove which AWS identity your terminal is using
aws sts get-caller-identity

The placeholder values you will see in the identity output are explained in the next section. sts stands for Security Token Service, the AWS service that answers “who am I signed in as.”

Expected output

Each version check prints one line. The exact numbers depend on when you install, so treat the format as the checkpoint, not the specific version. These are real outputs from a machine set up for this course; yours may show newer versions:

git version 2.43.0
v22.22.3
uv 0.11.15 (x86_64-unknown-linux-gnu)
aws-cli/2.x.x Python/3.x.x ...
2.1131.0 (build 1e9a1e1)

Python 3.12.3

Any Git 2.x, Node 22.12 or newer (or 24 LTS), uv 0.11 or newer, AWS CLI 2.x, and a CDK 2.x line all pass. The Python line must start with 3.12.

The identity check prints JSON (JavaScript Object Notation, a common text format for structured data). This is the shape of the output; your Account, UserId, and Arn values are specific to your account and login, so the exact strings will differ (output shape; exact values vary per account):

{
    "UserId": "<YOUR_USER_ID>",
    "Account": "<YOUR_12_DIGIT_ACCOUNT_ID>",
    "Arn": "arn:aws:sts::<YOUR_12_DIGIT_ACCOUNT_ID>:assumed-role/<YOUR_ROLE_NAME>/<YOUR_SESSION>"
}

<YOUR_12_DIGIT_ACCOUNT_ID> is the account you signed in to. Arn stands for Amazon Resource Name, a unique identifier for the identity you are using. If the account number matches the sandbox account you meant to use, this lesson’s checkpoint has passed.

One common failure

Symptom: you install a tool, then a version check prints command not found (macOS or Linux) or 'git' is not recognized as an internal or external command (Windows).

Diagnosis: the tool installed correctly, but your current terminal does not know where to find it. A terminal reads its list of program locations (the PATH) once when it starts. If you installed the tool after opening the terminal, that terminal has a stale PATH.

Fix: close the terminal completely and open a new one, then run the version check again. A fresh terminal reloads PATH and finds the tool. If it still fails, the installer may not have added the tool to PATH; re-run the installer and accept the option to add it to PATH, or follow the tool’s official “add to PATH” instructions for your operating system.

A second common failure is aws sts get-caller-identity returning Unable to locate credentials or an expired-token error. Short-lived credentials expire on purpose. Run aws sso login again to refresh them, then retry the identity check.

Why this works

Two habits in this lesson remove a whole class of problems before they start.

Pinning tool versions and checking them means every later command runs on a known toolchain. Most “it works on my machine but not yours” problems come from mismatched versions; a version check at the start makes a mismatch visible immediately instead of ten steps later.

Using a short-lived credential and confirming it with aws sts get-caller-identity means you know exactly which account and identity your terminal will act as before you run anything that touches the cloud. That single confirmation prevents the worst beginner mistake: running a command against the wrong account.

Verify it yourself

1. Close every open terminal and open a brand-new one.
2. Run all five version checks (git, node, uv, aws, cdk) plus uv run python --version from the agent/ folder. Confirm each prints a version line in the expected format.
3. Run aws sts get-caller-identity and confirm the Account value is the sandbox account you intended to use.
4. Open the AWS Billing console and confirm your budget and email alert exist.

If all four pass, you are ready for Lesson 1. You have installed the toolchain and proven your identity without creating anything billable.

Cleanup

Nothing to clean up. This lesson creates no billable or privileged cloud resource. The budget alert you set is free and worth keeping for the rest of the course. Your short-lived AWS credentials expire on their own; if you want to end a session early, run aws sso logout.