Alpha · set up a node
One command,
then four answers.
You need a computer that stays on and the coordinates of a place. A sensor is optional. The install itself takes two minutes; the rest is downloads. Nothing here can damage the machine: everything runs in containers, and deleting one folder removes it all.
If that works and the node starts, you can stop reading. The rest of this page is what to do when it doesn't, and what to do next.
Before you start
What you need.
A computer that stays on
Almost anything
An x86 Linux machine first: Ubuntu, Debian, or Arch and Omarchy. A Mac works too — macOS 13.0 or newer on Apple Silicon, 13.5 on Intel — and so does Windows 10 22H2 through WSL2. Raspberry Pi is untested, and the database image has no arm64 build. An old laptop with the lid shut is a good node, and if macOS has stopped supporting it, Linux on that same laptop is the answer rather than the end — curl -fsSL planetai.fab.city/preflight | bash reads the machine in four seconds, installs nothing, and prints the exact commands for it. It needs to be on to keep watching, and about 2 GB free.
Docker
Installed once
On Linux the installer adds Docker itself, and says so before it does — on a fresh machine that is the biggest download of the whole install, so it is step 1 of 7 with the clock running. On a Mac: macOS 14 or newer, OrbStack is lighter than Docker Desktop and free for personal use; below 14, Colima is the one that installs, and the preflight prints its line. You do not have to open anything first: if a runtime is installed and can run on that macOS, the installer starts it and waits.
A place
Typed as words
"Kuta Selatan", "Poblenou", "Mayur Vihar, Delhi". The installer finds the coordinates and time zone. No sensor is needed to begin: a node with none still reads a global air-quality model at your location.
A sensor makes it much more interesting. Any of these work, and you can mix them:
| Smart Citizen | The kit number from its smartcitizen.me address. Give the installer your username instead and it finds every kit on your account. |
| AirGradient | Its hostname or IP on your WiFi. Read directly, never through their cloud. |
| PurpleAir | Its IP address, from your router. Also read directly. |
| Nothing yet | Fine. Add one later with planetai setup, which will keep everything you already have. |
Two minutes, plus downloads
Install.
Open Terminal (macOS: ⌘-space, type "terminal"). Paste one line. The installer asks four questions and does everything else.
# macOS · Linux (x86) · Windows (WSL2)
curl -fsSL planetai.fab.city/install | bash
1 & 2
A name, and where it is
A short name — bayu-2, lab-roof — which appears in every alert, so pick something the household recognises. Then the place, typed as words. If several places share a name it lists them and you choose. It shows you the coordinates and time zone it found before doing anything.
3 & 4
What it is for, and your sensor
A home, a business, a community or lab node, or a district. It sets the defaults. Then which sensor you have, if any. It shows the whole plan and asks before installing.
What you will see: a line about your platform, a slow first build of one to three minutes, a doctor: block of ticks, then Done! A cross next to telegram connected is expected — that is the next step. A cross next to database or node answers means stop and look at the troubleshooting below.
Within five minutes the node has its first readings. On the very first start it also pulls three months of air-quality history and forty years of climate normals for your coordinates, so it has something to say immediately.
Two minutes each
Get the alerts, then prove they work.
planetai telegram
Message @BotFather in Telegram, send /newbot, paste the token it gives you. Then send your new bot any message; the node finds the rest itself and sends you a hello.
planetai test-alert
Fires a real alert within a minute, so you see the whole path: a rule becomes a message becomes your phone. It prints an alert number.
planetai act 3
Tells the node you did something about alert 3. This is the measurement nobody else has: not what the air was, but whether anyone acted.
planetai homeassistant
If you already run Home Assistant, every sensor and the latest alert appear there as entities with no configuration on that side. Automations live in Home Assistant; the node never touches your devices.
The five commands worth knowing
Everyday.
| planetai status | Is it alive, what has it read, what fired, and your ρ so far. The one to run first, always. |
| planetai doctor | Every check, with the fix named next to anything that failed. |
| planetai logs | What the node is doing right now. Ctrl-C to stop watching. |
| planetai update | Backs up, fetches the current version, migrates the database, rebuilds, verifies. Refuses to continue if the backup fails. |
| planetai ui | The dashboard: the room's number as a sentence, the day as a chart, every sensor with a note, the sea, the land, the weather. Settings live here too, behind a token this command prints. |
| planetai agent local | Puts a small model on this machine. From then on the Telegram bot answers questions: how is the air, how big is the swell, is the node healthy. |
| planetai run place gaps | The mapping briefing: what the satellite sees that nobody has drawn, which buildings have no type, which places have no hours. Bring it to a mapping afternoon. |
| planetai storage | Where the data is, where the nightly backups go, and the token a NAS uses to collect them. |
Run planetai on its own for the full list, including the mesh radios, packs, Home Assistant, IPFS and restore.
What a good week looks like
planetai status shows no errors and a rising reading count./act 12 closed the windows) or with the button on the dashboard.backups folder from last night.Things that have actually gone wrong
When it breaks.
Every line below is something that happened to a real node, not a hypothetical. Start with planetai doctor, which names the fix for most of them.
| Nothing installs | Docker is not running. Open OrbStack or Docker Desktop and wait for it to say it is ready, then run the install line again. It is safe to re-run. |
| "command not found: planetai" | Close the terminal and open a new one. The installer adds it to your path, which existing windows do not pick up. |
| "port is already in use" | Something else uses 8080. Open the settings with planetai config, set APP_PORT=8081, then planetai restart. |
| No alerts at all | Normal for the first hours if the air is fine — the node only speaks when something should change. Prove the path works with planetai test-alert. |
| Alerts every few minutes | The thresholds do not suit your place. Tell us; do not suffer it. This is the single most useful thing a tester can report. |
| The sensor shows nothing | planetai sensors lists what the node can see. A Smart Citizen kit must be publishing (check its page on smartcitizen.me); an AirGradient or PurpleAir must be on the same network as the node. |
| Telegram says nothing | Send your bot a message first — a bot cannot start a conversation with you. Then run planetai telegram again. |
| It stopped after a power cut | The containers restart themselves, but the computer must boot and log in on its own. On a Mac: System Settings → General → Login Items, and Energy → start up again after a power failure. |
| Settings changed nothing | planetai restart after editing. And check there is no space after the = in the settings file; NAME= value is not the same as NAME=value. |
When you ask us for help
Send the output of these three, which is almost always enough:
planetai status
planetai doctor
planetai logs # the last twenty lines are plenty
Not your settings file: it holds your bot token and database password. If you paste a log anywhere, check it for a line containing api.telegram.org/bot first.
Worth knowing
What it does with your data.
Readings stay on your machine
The database lives in a container on your computer. Nothing sends raw readings anywhere. If you later point the node at a community node, what travels upward is hourly averages, never the underlying rows — and you decide whether to do that at all.
What it fetches
Public data for your coordinates: a European air-quality model, NASA climate normals, and — if you turn them on — your city's open-data portal and nearby public sensors. All free, none of it requiring an account.
What we would like back
Nothing automatic. What helps is you telling us: which alerts were wrong, which were useful, what broke, and whether anyone actually did anything differently. That last one is the whole experiment.
Removing it
planetai stop stops it, keeping your data. To remove everything: docker compose down -v in the node folder, then delete the folder. Nothing is left behind on the machine.
Alpha
You are early.
This is an alpha. One node has run in Bali since 2 September 2026 and a handful of test machines have followed. Installing one makes you part of the experiment: you will hit things we have not, and what you tell us decides what gets fixed first. Write to info@fab.city with what broke, what helped and what did not.