Getting started

IsotopeAI runs as a single Node process on your own device. This guide covers installation on each supported platform, the first run, and how to verify the install actually works.

Requirements #

There are no runtime npm dependencies. package.json lists zero dependencies and zero devDependencies — everything the server needs is in the Node standard library.

Android via Termux #

Termux is a first-class target. The installer detects it and wires up home-screen shortcuts automatically.

1. Install Termux

   Install from F-Droid or GitHub releases. Do not use the Play Store build — it is deprecated and cannot install current packages.

2. Install prerequisites

   pkg update && pkg upgrade -y
   pkg install -y nodejs-lts git

3. Clone and run setup

   git clone https://github.com/Suydev/isotope-code
   cd isotope-code
   ./install-termux.sh

   This installs the isotope command, creates ~/.isotope/ for state and logs, and offers to set up Termux:Widget shortcuts.

4. Start it

   isotope start

   Then open http://127.0.0.1:3000 in your Android browser.

Linux and macOS #

git clone https://github.com/Suydev/isotope-code
cd isotope-code
./setup.sh

setup.sh verifies Node, scaffolds .env from .env.example if it is missing, installs the isotope CLI onto your PATH, and starts the server. Pass --no-start to configure without launching.

Windows #

Use PowerShell:

git clone https://github.com/Suydev/isotope-code
cd isotope-code
.\install.ps1

Or Command Prompt with setup.bat. Both install isotope.bat / isotope.ps1 equivalents of the CLI.

Point it at your database #

A fresh install writes a .env pre-filled with a shared demo project so the app boots immediately. For your own data, replace those two values:

# .env
SUPABASE_URL=https://your-project-ref.supabase.co
SUPABASE_ANON_KEY=your-anon-public-key
PORT=3000

Then restart:

isotope restart

Every variable is documented in Configuration. Creating the schema is covered in Supabase setup.

Verify the install #

Three checks, in increasing depth:

# 1 — is the server responding?
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3000/__isotope/ping
# expect: 200

# 2 — version, git SHA and live service-worker cache name
curl -s http://127.0.0.1:3000/api/version

# 3 — full dependency and configuration report
isotope doctor

Then read the log for patch warnings. A healthy start produces around 52 […Patch] lines and zero anchor failures:

grep -iE 'anchor not found|String not found' ~/.isotope/logs/server.log
# expect: no output

First login #

Open the app and create an account. On signup the server creates your row in public.users, and database triggers immediately seed six satellite tables — profile, stats, points, onboarding, presence and community enrolment.

If any of those rows were missing you would see an empty leaderboard or a non-functional community tab, so the triggers exist to make that impossible. Details in Database → triggers.

Email and password is the only sign-in method enabled out of the box. Google sign-in works but needs an OAuth client, a consent screen and a redirect list — and the button is hidden until you configure it, because a visible button that fails on click is worse than no button. The full walk-through is in Supabase setup → Google sign-in.

Next steps #