Getting started
There are three ways in: play the release build on a Fire TV, run everything locally in a browser, or deploy your own backend on AWS. Pick the one that fits.
Play it on a Fire TV
You need a Fire TV device on the same Wi-Fi as your phones, and adb on your computer. It ships with the Android SDK platform tools.
- On the Fire TV, open Settings > My Fire TV > Developer Options and turn on ADB debugging and Apps from Unknown Sources.
- Find the device IP in Settings > My Fire TV > About > Network.
- Download
cadabra-v1.0.apkfrom the v1.0 release. - Connect, install and launch:
adb connect <fire-tv-ip>:5555
adb install -r cadabra-v1.0.apk
adb shell monkey -p com.maanavkrishna.cadabra -c android.intent.category.LEANBACK_LAUNCHER 1- Scan the QR code on the TV with a phone, or open the controller URL on screen and type the 4-letter code.
The first launch after an install takes about 10 seconds to reach the home screen while the WebView warms up. Later launches are quick.
Run it locally
No Fire TV and no AWS account needed. You need Node.js 20 or newer.
- Clone and install:
git clone https://github.com/MaanavKrishna/cadabra.git
cd cadabra
npm install- Run the tests (633 of them, no AWS needed):
npm test- Start the TV app and the phone controller in two terminals:
npm --prefix apps/tv run devnpm --prefix apps/controller run devIn the TV app the arrow keys are the remote's D-pad, Enter is Select, and Esc or Backspace is Back. Space is Play/Pause and M is Menu.
To look at one scene on its own, open /render-demo.html?game=physics&look=toybox on the TV dev server. look=neon|toybox|cosmos|retro restyles any scene.
Deploy your own backend
The backend is one AWS CDK stack in ap-south-1: API Gateway WebSocket, three Lambdas, DynamoDB, S3 and CloudFront, Secrets Manager and a Bedrock guardrail.
You need: Node.js 20+, an AWS account with credentials (aws login), and for the TV app JDK 17 and the Android SDK 34.
- Change the account id in
apps/backend/deploy.shto your own. - If your account's Bedrock Claude quotas are 0 (common on new accounts), store an Anthropic API key for the fallback path:
aws secretsmanager create-secret --region ap-south-1 \
--name cadabra/anthropic-api-key --secret-string "sk-ant-..."- Deploy the stack, the phone site and the TV app:
bash apps/backend/deploy.sh # CDK bootstrap if needed, then cdk deploy
bash apps/controller/deploy.sh # vite build, S3 sync, CloudFront invalidation
scripts/tv-install.sh <fire-tv-ip> # bundles the TV web app into the Android shell, adb install- Smoke-test the live AI paths:
npx tsx apps/backend/scripts/smoke-forge.ts
npx tsx apps/backend/scripts/smoke-tweak.tsRepository layout
| Path | What is in it |
|---|---|
apps/android | Kotlin Fire TV shell: leanback launcher, full-screen WebView, key mapping |
apps/tv | TV web app: PS5-style UI, party flow, tweak and remix, Arcade, trophies |
apps/controller | Phone web app: join, avatars, Idea Storm, vote, tweak, per-game controls |
apps/backend | CDK stack and Lambdas: rooms, the Forge AI designer, tweak, host captions, Arcade |
packages/spec | Zod contracts: GameSpec, world physics, wire protocol, the 7 built-in games |
packages/engine | Deterministic runtime, 9 blocks, planck physics layer, bots, playtest gate |
packages/render | PixiJS game view, 4 looks, physics views, procedural music and sfx |
packages/couchpad | Phone-as-controller transport and widgets, also its own repo |
Next steps
- Read the Architecture to see how the TV, the phones and AWS fit together.
- Browse the Game kit to see what the AI designer can build with.