Getting Started

Getting Started with Race Condition

This skill walks through setting up Race Condition for local development. Some steps are fully automatable (installing dependencies, building code). Others require the developer to act in a browser or terminal (GCP auth, API key creation). Each step is marked AUTO or MANUAL.

Prerequisites Check

Run make check-prereqs to verify required tools. If any are missing, tell the developer what to install before continuing.

Setup Workflow

Step 1: Clone the repo (AUTO)

git clone https://github.com/GoogleCloudPlatform/race-condition.git
cd race-condition

Skip if the developer already has the repo.

Step 2: GCP authentication (MANUAL)

These commands are interactive (browser OAuth). Tell the developer to run them:

gcloud auth login --update-adc
gcloud config set project PROJECT_ID

Ask for their GCP project ID. They need a project with billing enabled and Owner access (or roles/aiplatform.user at minimum).

Step 3: Enable required APIs (AUTO)

gcloud services enable \
  aiplatform.googleapis.com \
  generativelanguage.googleapis.com \
  cloudresourcemanager.googleapis.com \
  pubsub.googleapis.com \
  iam.googleapis.com

gcloud auth application-default set-quota-project PROJECT_ID

API enablement takes 1-2 minutes to propagate. If 403 errors appear on first start, wait a minute and run make restart.

Step 4: Initialize the project (AUTO)

make init

This checks prerequisites, creates .env from .env.example, installs Python deps (uv sync), installs and builds web frontends, starts Docker infrastructure (Redis, Pub/Sub emulator, PostgreSQL), and builds Go services.

Step 5: Configure .env (AUTO)

Replace the placeholder project ID:

# macOS
sed -i '' 's/your-gcp-project-id/ACTUAL_PROJECT_ID/g' .env

# Linux
sed -i 's/your-gcp-project-id/ACTUAL_PROJECT_ID/g' .env

Detect the OS and use the correct sed variant.

Step 6: Start the simulation (AUTO)

make start

Once started:

• Frontend (3D): http://localhost:9119
• Admin dashboard: http://localhost:9100
• Tester UI: http://localhost:9112

Step 7: Google Maps API key (MANUAL, optional)

The Planner works without a Maps key but produces better routes with one.

1. Enable APIs:

   gcloud services enable apikeys.googleapis.com \
     agentregistry.googleapis.com cloudapiregistry.googleapis.com \
     mapstools.googleapis.com places.googleapis.com weather.googleapis.com
   

2. Create a key at https://console.cloud.google.com/apis/credentials. Restrict to: Cloud API Registry API, Maps Grounding Lite API, Places API (New), Weather API.

3. Add to .env: GOOGLE_MAPS_API_KEY=AIza...

4. Run make restart.

Troubleshooting

Next Steps

• Run tests with make test
• To modify an agent, edit files in agents/ and run make restart
• To understand the architecture, use the exploring-the-codebase skill
• To set up a contributor workflow, use the contributing skill