Way Back Home
๐ Way Back Home
Ask AI about Way Back Home
Powered by Claude ยท Grounded in docs
I know everything about Way Back Home. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
-
๐ Way Back Home

An immersive AI workshop platform where participants learn to build intelligent agents while rescuing a stranded space explorer.
Way Back Home is a hands-on workshop experience that teaches Google Cloud AI technologies through an engaging narrative. Participants crash-land on an alien planet and must use AI to identify themselves, analyze their surroundings, and coordinate rescue efforts.
๐ฎ The Experience
You're a space explorer whose ship has crashed on an uncharted planet. Your rescue beacon is offline, and you're scattered across the surface with other survivors. To get home, you must:
| Level | Mission | AI Skills Learned |
|---|---|---|
| Level 0 | Generate your explorer identity | Multi-turn image generation, Gemini (Nano Banana) |
| Level 1 | Pinpoint your crash location | Multi-agent systems, MCP servers, ADK, parallel processing |
| Level 2 | Process incoming SOS signals | Event-driven agents, A2A communication (coming soon) |
| Level 3 | Coordinate group rescue | Agent orchestration, consensus protocols (coming soon) |
| Level 4 | Coordinate group rescue | Agent orchestration, consensus protocols (coming soon) |
| Level 5 | Coordinate group rescue | Agent orchestration, consensus protocols (coming soon) |
๐ ๏ธ Technology Stack
| Component | Technologies |
|---|---|
| Frontend | Next.js 14, Three.js, React Three Fiber, Tailwind CSS |
| Backend | FastAPI, Firestore, Firebase Storage, Cloud Run |
| AI/ML | Vertex AI, Gemini 2.5 Flash, Veo 3.1 |
| Agents | Google ADK, MCP (Model Context Protocol), Google Cloud MCP servers |
| Infrastructure | Google Cloud Run, Cloud Build, Artifact Registry |
๐ Quick Start
For Workshop Participants
-
Access Cloud Shell at console.cloud.google.com
-
Clone and setup:
git clone https://github.com/google-americas/way-back-home.git cd way-back-home -
Start with Level 0:
./scripts/setup.sh cd level_0 -
Follow the codelab: Level 0 Instructions
For Workshop Hosts
See Deployment Guide below for running your own instance.
๐ Documentation
| Component | Description |
|---|---|
| Level 0 README | Avatar generation with multi-turn image AI |
| Level 1 README | Multi-agent crash site analysis |
| Backend README | Mission Control API documentation |
| Frontend README | 3D map visualization |
๐๏ธ Architecture Overview
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Way Back Home โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ โ
โ Participant Journey โ
โ โโโโโโโโโโโโโโโโโโโ โ
โ โ
โ โโโโโโโโโโโโ โโโโโโโโโโโโ โโโโโโโโโโโโ โโโโโโโโโโโโ โ
โ โ Level 0 โโโโโถโ Level 1 โโโโโถโ Level 2 โโโโโถโ Level 3 โ โ
โ โ Identity โ โ Location โ โ SOS โ โ Rescue โ โ
โ โโโโโโโโโโโโ โโโโโโโโโโโโ โโโโโโโโโโโโ โโโโโโโโโโโโ โ
โ โ โ โ
โ โผ โผ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ Backend API (Cloud Run) โ โ
โ โ โข Participant registration โข Evidence storage โ โ
โ โ โข Location confirmation โข Event management โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ โ โ
โ โผ โผ โ
โ โโโโโโโโโโโโ โโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โFirestore โ โ Firebase โ โ Frontend (Next.js) โ โ
โ โ โ โ Storage โ โ โข 3D planet visualization โ โ
โ โโข events โ โโข avatars โ โ โข Real-time participant โ โ
โ โโข users โ โโข evidenceโ โ tracking โ โ
โ โโโโโโโโโโโโ โโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
๐ Deployment
Deploy Your Own Instance
-
Prerequisites:
- Google Cloud project with billing enabled
- Firebase project (Firestore + Storage + Auth)
- Domain names (optional, for custom URLs)
-
Clone and configure:
git clone https://github.com/google-americas/way-back-home.git cd way-back-home # Configure your project gcloud config set project YOUR_PROJECT_ID -
Run infrastructure setup:
./scripts/setup-infrastructure.sh -
Deploy all services:
Note: On your first deployment, Cloud Run will generate unique URLs for your services. After the build finishes, you must redeploy the frontend once more using these specific URLs to ensure the 3D map can communicate with the API.
# First deployment (to generate URLs) gcloud builds submit --config cloudbuild.yaml # Get and save your URLs export API_BASE_URL=$(gcloud run services describe way-back-home-api --format='value(status.url)') export MAP_BASE_URL=$(gcloud run services describe way-back-home-frontend --format='value(status.url)') # Redeploy frontend with the actual URLs gcloud builds submit --config cloudbuild.yaml \ --substitutions=_API_BASE_URL=$API_BASE_URL,_MAP_BASE_URL=$MAP_BASE_URL,_DEPLOY_BACKEND=false
Environment Configuration
Create a set_env.sh in project root:
export GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project)
export REGION="us-central1"
export API_BASE_URL=$(gcloud run services describe way-back-home-api --format='value(status.url)')
export MAP_BASE_URL=$(gcloud run services describe way-back-home-frontend --format='value(status.url)')
๐ Workshop Hosting Guide
Before the Workshop
-
Deploy backend and frontend to your GCP project. Ensure you pass your Cloud Run service URLs to the
substitutionsflag ingcloud builds submit. -
Configure Admin Access: The API requires callers of admin endpoints to be registered in the
adminsFirestore collection.- Go to Firebase Console > Firestore.
- Create a collection named
admins. - Create a document where the Document ID is your email (e.g.,
your-name@google.com). - Add a field
active: true(boolean).
-
Create an event using one of the following methods:
Method A: Firestore (Manual - Recommended for quick start)
Create a document in the events collection with the following structure:
- Collection:
events - Document ID:
bwai-mycity(or your chosen event code) - Fields:
active:true(boolean)code:"bwai-mycity"(string)created_at:[Current Timestamp](timestamp)created_by:"admin"(string)description:""(string)max_participants:500(number)name:"Build With IA - GDG SJC"(string)participant_count:0(number)
Method B: CLI (Recommended for automated setup)
Use the provided Python script to create an event directly in Firestore using your authenticated gcloud credentials:
python3 scripts/create_event.py your-event-code "Your Workshop Name" --project YOUR_PROJECT_ID
Method C: API
-
Retrieve a Firebase ID Token from the terminal:
# 1. Get your Google Identity Token ID_TOKEN=$(gcloud auth print-identity-token) # 2. Exchange it for a Firebase ID Token (requires Firebase Web API Key) # You can find your API Key in the Firebase Console > Project Settings API_KEY="YOUR_FIREBASE_WEB_API_KEY" curl -s -X POST "https://identitytoolkit.googleapis.com/v1/accounts:signInWithIdp?key=${API_KEY}" \ -H "Content-Type: application/json" \ -d "{\"postBody\": \"id_token=${ID_TOKEN}&providerId=google.com\", \"requestUri\": \"http://localhost\", \"returnIdpCredential\": true, \"returnSecureToken\": true}" | jq -r .idToken -
Call the Admin API:
curl -X POST https://api.yourdomain.dev/admin/events \ -H "Authorization: Bearer $FIREBASE_TOKEN" \ -H "Content-Type: application/json" \ -d '{"code": "your-event-code", "name": "Your Workshop Name"}' -
Generate QR codes pointing to your event URL.
-
Test the full flow with a sample participant.
During the Workshop
- Share the event code with participants
- Direct them to the Level 0 Codelab
- Monitor the live map at
https://yourdomain.dev/e/your-event-code - Celebrate as beacons light up across the planet!
Cost Estimates
| Component | Approximate Cost |
|---|---|
| Level 0 (per participant) | ~$0.08 (2 images) |
| Level 1 (per participant) | ~$0.15 (images + video + agent calls) |
| Cloud Run (idle) | ~$0/month (scales to zero) |
| Firestore (500 participants) | < $1/month |
๐ค Contributing
Contributions are welcome! Please read our contributing guidelines before submitting PRs.
Development Setup
# Backend
cd dashboard/backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8080
# Frontend
cd dashboard/frontend
npm install
npm run dev
๐ License
Apache 2.0 - See LICENSE for details.
๐ Acknowledgments
- Built with Google ADK (Agent Development Kit)
- Powered by Vertex AI and Gemini
- 3D visualization with React Three Fiber
Ready to find your way back home? Start with Level 0 ๐
