Setup

Set up your machine before the workshop day. It takes about twenty minutes, most of it downloads. When you are done, one command tells you whether everything will work on the day:

uv run --no-sync python setup-check/check.py

If anything stays red, see If something stays red.

Prerequisites

Python is not on this list: uv installs Python 3.12 for the project.

What	Minimum	Needed from	Notes
uv	0.8.15	Module 0	Already installed? Run uv self update.
Docker Engine with Compose v2	20.10, Compose 2.0	Module 0	Runs the shop locally. No Docker allowed at work? Use the shared instance.
A coding agent	current release	Module 2	Agents update themselves; no lab depends on a specific version. See Coding agent.
Node.js	20.19	Module 5	22 LTS recommended. Needed by OpenSpec.
OpenSpec	1.13.1	Module 5	See Node.js and OpenSpec.
GitHub CLI (gh)	2.40, signed in	Module 7	See GitHub CLI.
Azure CLI, Jira Cloud	-	Module 7	Optional tracks only. See Optional tracks.

Install

1. Fork this repository on GitHub, then clone your fork. Lab 9 runs GitHub Actions on it.

2. Install the pinned Python environment:

   uv sync --locked

   Every package comes from uv.lock, at exactly the version the workshop was tested with. If uv reports that its version does not match, run uv self update. Do not install anything with pip.

Browsers

Install the browser the tests use:

uv run --no-sync rfbrowser install chromium

On Linux, add --with-deps to install the system libraries Chromium needs (this asks for sudo).

• Never run rfbrowser init. This project uses Browser Library's batteries package, which brings its own Node.js runtime. rfbrowser init installs a second, separate set of Node packages on top of it. If you ran it, undo it with uv run --no-sync rfbrowser clean-node, then install the browser again.
• The browser lives inside .venv. If you delete or recreate .venv, install the browser again.

The local shop

The system under test is the demo shop, pinned to one version in shop/compose.yaml.

docker compose -f shop/compose.yaml up -d                  # start: http://localhost:9090
docker compose -f shop/compose.yaml up -d --force-recreate # a freshly seeded shop
docker compose -f shop/compose.yaml down                   # stop

Restarting keeps the shop's data; recreating reseeds it. uv run --no-sync python -m shop status shows the version and what is active.

The shared instance

If you cannot run Docker, use the shared workshop instance instead. Put two lines in .env (copy .env.example to start):

SHOP_URL=https://demoshop.makrocode.de
SHOP_SPACE=your-github-handle

Everyone on the shared instance works in their own space, named after their GitHub handle, so your presets, cart and orders never affect anyone else. Run tests with the shared profile:

uv run robotcode -p shared robot <path>

Without a space, the run stops before its first test and tells you what to set.

Coding agent

The workshop is demonstrated with Claude Code. Codex and GitHub Copilot work for every lab. Install one and sign in before the workshop, following its vendor's instructions.

Agent	Spec-driven workflow in Module 5
Claude Code	/opsx:propose, /opsx:apply, /opsx:archive, /opsx:explore
Codex	$openspec-propose and the other openspec-* skills
GitHub Copilot	/opsx-propose and the other opsx-* prompts

AGENTS.md is the project context every agent reads; CLAUDE.md only imports it.

RobotCode

Always run RobotCode through uv: uv run robotcode .... That is the RobotCode installed in this project, which sees the project's libraries at their pinned versions. A RobotCode installed globally (with pipx or uv tool) cannot see them. setup-check warns if one would start when you type robotcode alone.

Agent plugins and skills

Two labs install Robot Framework expertise into your agent. Nothing needs installing before the workshop; the labs give the commands. They are named here so that everyone gets the same versions:

What	Version	Lab	Installed
Robot Framework Agent Skills	content v1.2.0, installer rf-agentskills 0.6.0	3	into the repository, with uvx rf-agentskills@0.6.0 install --agent <agent> --scope project --project . --what skills
The RobotCode agent plugin robotcode	the marketplace at commit 7c753f8adca1 (2026-09-21)	4	from the marketplace: into the repository for Claude Code, for your user in Codex and GitHub Copilot

The plugin's marketplace publishes no versions, so you cannot pin it. claude plugin list shows the commit you installed. If it differs from the one above, the labs still work, but your agent's advice may differ in details from the facilitator's.

Node.js and OpenSpec

Install Node.js 22 LTS (at least 20.19), then OpenSpec at the pinned version:

npm install -g @fission-ai/openspec@1.13.1
openspec --version   # 1.13.1

GitHub CLI

Install the GitHub CLI and sign in with gh auth login. Module 7 files an issue with it, and Module 9 runs on your fork.

Optional tracks

• Azure CLI (az), for the Azure DevOps variant of Module 7.
• A free Jira Cloud site, for the Jira stretch goal of Module 7.

Skip both if you do not use them at work; setup-check only warns.

Healing API key

Module 8 heals drifted locators with robotframework-heal. The facilitators will tell you before the workshop whether your workshop needs an LLM for it. If it does, add three settings to .env:

HEAL_MODEL=...
HEAL_BASE_URL=...
HEAL_API_KEY=...

Set a spending cap on the key before you use it. An agent or a healing run can make many requests quickly. Never commit .env, and never paste its content into an issue.

robotframework-heal reads .env itself, and its HEAL_* values there override the same variables in your shell. That is the opposite of SHOP_URL and SHOP_SPACE, where your shell wins. To try another model for a single run, change .env rather than exporting the variable.

CI and the triage agent (Module 9)

Module 9 runs this repository's GitHub Actions on your fork. Enable Actions there before the workshop: open the fork's Actions tab and confirm. Nothing else is needed: without any secret, a failing pull request still gets a comment that lists the failed tests.

To have an agent add the root cause to that comment, set one of these as secrets of your fork, under Settings > Secrets and variables > Actions or with gh secret set <NAME>:

You have	Secrets
a Claude subscription	CLAUDE_CODE_OAUTH_TOKEN, created with claude setup-token
an Anthropic API key	ANTHROPIC_API_KEY
any OpenAI-compatible endpoint, for example your healing key	TRIAGE_MODEL, TRIAGE_BASE_URL and TRIAGE_API_KEY

The stretch goal of Lab 9 uses your healing settings as secrets too: HEAL_MODEL, HEAL_BASE_URL and HEAL_API_KEY.

Set a spending cap on every key before you add it. The workflows cap the agent's turns and tokens, but a key without a cap is a key without a limit.

Platforms

Tested: Windows x64, macOS 13 or newer (Apple silicon and Intel), and Linux x64 and arm64 with glibc 2.28 or newer. On other platforms (for example Windows on Arm, or macOS before 13), the batteries package has no build: remove robotframework-browser-batteries from your environment and run rfbrowser init instead, which needs Node.js and npm. Tell the facilitators before the workshop.

Corporate proxies

Set HTTPS_PROXY (and NO_PROXY=localhost,127.0.0.1) before installing. The setup downloads from:

• pypi.org and files.pythonhosted.org (Python packages)
• github.com and *.githubusercontent.com (Python itself, via uv)
• ghcr.io and pkg-containers.githubusercontent.com (the shop image)
• registry.npmjs.org (OpenSpec)
• cdn.playwright.dev and playwright.download.prss.microsoft.com (Chromium)
• demoshop.makrocode.de (the shared instance)

Check everything

uv run --no-sync python setup-check/check.py            # the full check
uv run --no-sync python setup-check/check.py --offline  # without network access

Keep --no-sync: plain uv run would repair the environment before checking it, and hide what is wrong. Every failed check prints a fix and the section of this guide to read.

If something stays red

Open an issue in this repository and paste the output of:

uv run --no-sync python setup-check/check.py --json

The output never contains your keys or tokens. Before the workshop there is also an optional drop-in setup call.

For maintainers: changing a pinned version

Change these together, in one pull request:

1. The pin in pyproject.toml ([project] dependencies, or [tool.workshop] for tools outside Python), then uv lock.
2. The shop tag in shop/compose.yaml: always a version tag, never edge or sha-....
3. The numbers in this guide's prerequisites table.
4. For a new RobotCode, Robot Framework or Browser version: run the examples of docs/robotcode.md again, and update its output and traps.

setup-check reads its expectations from uv.lock, [tool.workshop] and shop/compose.yaml, so it needs no edit. Run it afterwards on a clean machine.