Session setup

Complete four checks before the workshop: tools, account, deployed starter, and Docker. Your first working result is a browser page that says pong.

Bring your own Cloudflare account with Workers Paid. Create an account if needed. Workers Paid starts at $5 USD/month, plus applicable usage; AI and container usage is billed to your account. No model API keys are needed.

One setup, two ways to follow it

Already comfortable with your tools? Run the commands and compare the results. Open any help you need.

0 of 4 checks confirmedYour finish line ↓

Tick each check after it succeeds. Your place is saved in this browser.

1. Get the lab running

Use Git Bash on Windows, Terminal (zsh) on macOS, or Bash on Ubuntu. Call this window Terminal A.

node --version
npm --version
git --version
curl --version

Look for: Node 24.11+ within Node 24 (recommended), or 22.19+ within Node 22; the other commands each print a version. Missing something? Install only the missing tools.

Help me choose a terminal and Node version

On Windows, open Git Bash from Start; in VS Code choose the Git Bash terminal profile. The commands in this guide use Bash-style syntax, not PowerShell. On macOS use the default Terminal app; on Ubuntu use Terminal.

Already have a supported Node version? Keep it. Volta is the recommended installer if you need Node, not an extra requirement for an existing setup. Node 23 and other major versions are not supported for this workshop. Run one command block at a time and wait for the terminal prompt to return.

Download the starter and check it builds:

cd "$HOME"
git clone --branch main https://github.com/omkarkhair/field-trip-agent.git
cd field-trip-agent
npm ci && npm run typecheck && npm run build
git status --short

Look for: installation, typecheck, and build finish successfully; git status --short prints nothing. Open field-trip-agent in your editor.

What am I installing, and where do I run commands?

npm ci installs the exact lab dependencies, including Wrangler 4.143.0. Use the project-local npx wrangler throughout the session; no global Wrangler installation is needed. Audit notices do not require changing the workshop’s lockfile or pinned versions.

In VS Code, use File → Open Folder and select field-trip-agent in your home folder. Run the remaining commands from this folder. If that folder already exists, ask a facilitator to check it is a clean main starter before reusing it.

I have a supported Node version, a successful build, and the clean lab open in my editor.

2. Connect your Cloudflare account

In the dashboard, select your workshop account and confirm Billing → Subscriptions → Workers Paid. Then, in Terminal A:

npx wrangler login && npx wrangler whoami

Authorize Wrangler in the browser using the login for that same account.

Your workshop account

Save your Cloudflare account ID

Copy the 32-character Account ID next to your workshop account in npx wrangler whoami, then save it here to fill the guide's commands.

What does the Wrangler output look like?

Example only — copy the ID from your own terminal, not this example.

Account Name	Account ID
Your workshop account	`0123456789abcdef0123456789abcdef`

Find the account ID in the Cloudflare dashboard

Open the Cloudflare dashboard and select your own account prepared for the workshop.
Open Search (or press ⌘K on macOS / Ctrl+K on Windows or Linux). Type Copy account ID and select that result to copy the ID.
Return to this page, paste the ID below, and click Use this account.

You can also open Workers & Pages → Account Details and click the copy button next to Account ID.

Run this block after saving your account ID:

export CLOUDFLARE_ACCOUNT_ID="<your-account-id>"
npm run check && npx --no-install wrangler whoami --account "$CLOUDFLARE_ACCOUNT_ID"
npx --no-install wrangler ai models list --search gemma-4-26b-a4b-it --json
npx --no-install wrangler containers list --json

Look for: All good, your chosen account/membership, the model @cf/google/gemma-4-26b-a4b-it, and a successful Containers JSON response (an empty list is fine). Resolve any errors before ticking the check.

Help me confirm billing, permissions, and the account ID

Account ID: copy all 32 characters beside your workshop account in the whoami table. If several accounts appear, use the one you prepared for this session. Saving it here fills command snippets; you still need to run the export in each terminal.
Billing: a website Pro/Business plan is separate from Workers Paid, which Containers requires. If you cannot view billing, ask your account administrator to confirm an active Workers Paid subscription for your saved account ID. Wrangler has no subscription-check command.
Permissions: your membership must allow Worker/Durable Object deployment, Workers AI use, and Container/image management. If Wrangler cannot display your roles, confirm them in the dashboard or with your account administrator.

These API commands confirm read access. A real AI reply is tested in checkpoint 1; container image upload and execution are tested in checkpoint 5’s Live deploy tab. Neither an API list nor pong proves those runtime permissions.

Workers Paid is confirmed, the account ID is saved, and all account/API checks succeeded.

3. Deploy and see pong

Your deployment URL

Set your workers.dev subdomain once

Find Your subdomain in Workers & Pages. Save the part before .workers.dev, or paste your full deployed URL.

No workers.dev subdomain shown yet?

Follow the workers.dev setup prompt in Workers & Pages. Choose an available name and complete registration. Once the dashboard shows your registered address, copy its subdomain into the field below.

Saving a name on this workshop page fills the guide's commands and browser-test links; it does not register that name with Cloudflare.

Help me find my URL and open the second terminal

In your workshop account, open Workers & Pages. Register a workers.dev subdomain if prompted. If it shows your-team.workers.dev, save your-team above. This is different from your 32-character Account ID. Your preview should read https://field-trip-agent.your-team.workers.dev.

Open a second window with the same shell. In VS Code use Terminal → New Terminal. Call it Terminal B: it runs deployment and verification commands. Terminal A runs the local server when you use Local dev. Keeping these two windows is useful throughout the workshop.

Open a second terminal with the same shell: Terminal B. Select the lab folder and your account:

cd "$HOME/field-trip-agent"
export CLOUDFLARE_ACCOUNT_ID="<your-account-id>"

Live deploy
Local dev

In Terminal B:

npm run deploy
sleep 5
curl https://field-trip-agent.<subdomain>.workers.dev/api/ping

Look for: pong in the terminal and at this browser link:

Save your workers.dev subdomain to open this test ↗https://field-trip-agent.<subdomain>.workers.dev/api/ping

If deployment prints a different URL, save that full URL above and rerun the curl command with the updated address.

In Terminal A, start the server and leave it running:

npm run dev

Wait for VITE ... ready and http://localhost:5173/. In Terminal B:

curl http://localhost:5173/api/ping

Look for: pong. Local dev is useful for troubleshooting; complete Live deploy too to confirm you can deploy to your account.

Open the local starter ping in your browser ↗http://localhost:5173/api/ping

The chat UI gets its agent in checkpoint 1. For now, pong is the goal.

My URL is saved and the deployed starter returns pong in the terminal and browser.

4. Prepare Docker

Start Docker Desktop (or Docker Engine on Ubuntu). In Terminal B:

docker info --format '{{.OSType}}' && docker buildx version

Look for: linux and a Buildx version. Then download the lab’s image:

docker pull --platform linux/amd64 cloudflare/sandbox:0.12.10

Look for: Downloaded newer image or Image is up to date. Keep Docker running for the session.

Why do I need Docker now, and what if it fails?

Docker is used for the Sandbox in checkpoint 5. Downloading its image before the session avoids a long wait during the lab. The explicit linux/amd64 platform also works on Apple Silicon; 0.12.10 matches the workshop’s Sandbox SDK.

If Docker is missing, use your operating system’s installation instructions. If the daemon cannot be reached, open Docker Desktop and wait for the engine to start, then retry. On Windows choose Linux containers / WSL 2. On Ubuntu, docker info must work as your ordinary user, without sudo, for Wrangler to use it.

Docker runs Linux containers, Buildx works, and the pinned Sandbox image is downloaded.

Stuck? Get help with the failed check

If a check fails, keep the output visible and contact the facilitator before the session. Share your operating system, failing command, and full error; for account issues include the account ID too.

Find the fix for a common error

What you see	What to do next
`command not found` or wrong Node version	Install the missing tool, reopen the correct terminal, and rerun its check.
`field-trip-agent` already exists	Ask a facilitator to confirm it is a clean `main` starter.
Wrangler’s browser does not open	Open the authorization URL printed by Wrangler in your Cloudflare browser.
Wrong account, missing account, or `401`	Rerun `npx wrangler login` with the correct login. Check for a `CLOUDFLARE_API_TOKEN` environment value overriding it.
`403`, upgrade prompt, or product disabled	Confirm Workers Paid, AI/Containers access, and membership permissions with your account administrator. Complete any dashboard setup prompts.
Quota or rate-limit error	Check account usage/quota; wait and retry if it is a temporary rate limit.
`npm run check` has a red failure	Follow the hint below it, then rerun the check.
Docker cannot connect	Start Docker, wait for its engine, and rerun the Docker check.

Use port 5180 if 5173 is busy

In Terminal A, stop the server with Ctrl+C, then run:

npm run dev -- --port 5180

In Terminal B:

curl http://localhost:5180/api/ping

Use http://localhost:5180 in the browser and in later local smoke-test commands.

Prefer to read ahead? Download the workshop deck →

Install missing tools

Open installation instructions for Windows, macOS, or Ubuntu

Choose one operating-system tab. Install only the tools you are missing; run each block in order and wait for its prompts to finish. Return to step 1 after Node, npm, Git, and curl are ready. Complete the Docker steps before the workshop as well; VS Code is optional if you already have an editor.

On a managed computer where installation is blocked, show the output to a facilitator for the session’s installation path. Installers may request an administrator password. Docker Desktop’s commercial-use terms may require your organization’s paid subscription.

Use Windows PowerShell (5.1 or 7) on a supported Windows 11 x64 computer. The installation commands below are PowerShell commands; the rest of the guide uses Git Bash, which comes with Git for Windows.

1. Install Volta. If winget is missing, install or update App Installer from the Microsoft Store.

winget install --id Volta.Volta --exact --source winget --accept-source-agreements --accept-package-agreements

Close PowerShell, open a new PowerShell window, and install the tested Node release:

volta install node@24.19.0

2. Install Git:

winget install --id Git.Git --exact --source winget --accept-source-agreements --accept-package-agreements

Close PowerShell and open Git Bash from Start. Return to step 1 to check Node, npm, Git, and curl.

3. Install Docker Desktop before the workshop. Back in PowerShell:

winget install --id Docker.DockerDesktop --exact --source winget --accept-source-agreements --accept-package-agreements

4. Enable WSL 2 if Docker asks for it. In PowerShell → Run as administrator:

wsl --install --no-distribution

Restart Windows if prompted. If WSL is already installed but Docker asks for a newer version, run wsl --update in administrator PowerShell instead. Hardware virtualization must be enabled; a facilitator can help with Docker’s Windows requirements.

Open Docker Desktop from Start, complete its first-run prompts, use the Linux containers / WSL 2 backend, and wait for the engine to be running. Close your old terminals and open Git Bash from Start for the Docker check and all remaining workshop commands. In VS Code, select Git Bash as the terminal profile. Do not run the Linux installation tab inside WSL for this Windows setup.

Optional: install VS Code if you need an editor. In PowerShell:

winget install --id Microsoft.VisualStudioCode --exact --source winget --accept-source-agreements --accept-package-agreements

Use Terminal with zsh, the macOS default shell. This route uses Homebrew; check its supported macOS versions if your computer is running an older release.

1. Install Homebrew if brew --version does not work:

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

Finish any Command Line Tools installation and run the Next steps printed by Homebrew to add brew to your shell. Confirm brew --version works before continuing; the instructions differ between Apple Silicon and Intel Macs.

2. Install Git, then install Volta and the tested Node release:

brew install git
curl https://get.volta.sh | bash
export VOLTA_HOME="$HOME/.volta"
export PATH="$VOLTA_HOME/bin:$PATH"
volta install node@24.19.0

The Volta installer updates your zsh startup configuration. The two export commands make Volta available immediately in the current terminal. Return to step 1 to check Node, npm, Git, and curl.

3. Install and launch Docker Desktop before the workshop:

brew install --cask docker-desktop
open -a Docker

Complete Docker’s first-run prompts and wait for the engine to be running. If Docker was already installed, open it from Applications. Then run the Docker check.

Optional: install VS Code if you need an editor:

brew install --cask visual-studio-code

Use Bash on Ubuntu 22.04 or 24.04, with sudo access and systemd, on x86-64 or ARM64. These commands are for a workshop development machine with no existing Docker installation. If Docker is already installed, run the Docker check first. For another distribution or conflicting Docker packages, use Docker’s installation instructions with a facilitator.

1. Install Git, then install Volta and the tested Node release. The Volta installer updates ~/.bashrc; this command also activates Volta in the current Bash terminal.

sudo apt-get update
sudo apt-get install -y ca-certificates curl git
(set -o pipefail; curl https://get.volta.sh | bash)
export VOLTA_HOME="$HOME/.volta"
export PATH="$VOLTA_HOME/bin:$PATH"
volta install node@24.19.0

Return to step 1 to check Node, npm, Git, and curl.

2. Add Docker’s official Ubuntu package repository:

sudo install -m 0755 -d /etc/apt/keyrings
(set -o pipefail; curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo tee /etc/apt/keyrings/docker.asc > /dev/null)
sudo chmod a+r /etc/apt/keyrings/docker.asc
(set -o pipefail; printf 'Types: deb\nURIs: https://download.docker.com/linux/ubuntu\nSuites: %s\nComponents: stable\nArchitectures: %s\nSigned-By: /etc/apt/keyrings/docker.asc\n' "$(. /etc/os-release && printf '%s' "$VERSION_CODENAME")" "$(dpkg --print-architecture)" | sudo tee /etc/apt/sources.list.d/docker.sources > /dev/null)

3. Install and start Docker, then enable access for your login user:

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
sudo usermod -aG docker "$(id -un)"

Membership in the docker group grants root-level access to this computer. Log out of your desktop session and log back in for the group change to apply, then open a new Bash terminal. sudo docker info succeeding is not enough: Wrangler needs docker info to work as your ordinary login user.

4. Install VS Code if you need an editor. On Ubuntu Desktop with Snap enabled:

sudo snap install code --classic

If Snap is unavailable, use the official VS Code Linux package.

After installation, reopen the shell listed in step 1 and rerun the failed check. Return to step 1 for Node, npm, Git, and curl, or Prepare Docker for Docker.

Finish these four checks before the session

Use the checkboxes above to track your results. This page cannot inspect your computer or account.

Next: 1. Hello agent →

Session setup

Session setup

1. Get the lab running

2. Connect your Cloudflare account

Save your Cloudflare account ID

3. Deploy and see pong

Set your workers.dev subdomain once

4. Prepare Docker

Stuck? Get help with the failed check

Install missing tools

How is this page working for you?

Thanks for helping us improve.