Set up StonePi

Prepare your Pi

On your computer with Raspberry Pi Imager, then at the Pi. Once only.

1. Check your hardware

   StonePi supports Raspberry Pi 4 and Raspberry Pi 5.

   • Recommended: Raspberry Pi 4 Model B with 4 GB of memory, or better
   • A microSD card of 32 GB or more
   • The official power supply for your Pi
   • Ethernet, or your Wi-Fi name and password
   • A computer with a microSD card reader

   You'll end up with two passwords: one for the Pi itself, which you choose in step 4 and use to connect in step 6, and one for StonePi's web sign-in, which the installer creates and shows you at the end.

2. Get Raspberry Pi Imager

   Raspberry Pi Imager is the official free tool to format and write the operating system onto your microSD card.

   Detecting your system… Official Raspberry Pi release

   Download Raspberry Pi Imager Direct download

   Other operating systems: Windows (.exe) · macOS (.dmg) · Ubuntu / Debian (.deb) · All downloads

3. Choose the device and OS

   In Imager, pick:

   Device

   Raspberry Pi 4 or Raspberry Pi 5

   OS

   Raspberry Pi OS (other) → Raspberry Pi OS Lite (64-bit)

   Storage

   Your microSD card

   The desktop edition works too, but Lite leaves more memory for your apps. It must be the 64-bit version.

4. Customise before writing

   When Imager asks "Would you like to apply OS customisation settings?", choose Edit Settings and fill in:

   Hostname

   stonepi

   Username

   Your choice, for example your first name. You'll use it to connect in step 6.

   Password

   Your choice. Keep it somewhere safe: this is the Pi password you'll need in step 6.

   Wi-Fi

   Network name, password and country. Skip this if you're using Ethernet.

   Locale

   Your time zone and keyboard layout

   SSH

   Enable, with password authentication (needed for step 6)

   Writing erases everything on the card. Check the Storage choice is your microSD card, not a USB stick or another drive, and copy off anything you want to keep first.

   Click Save, then click Yes to write the card. Writing and verifying takes a few minutes.

5. Start the Pi

   Put the card in the Pi, connect Ethernet if you're using it, and plug in the power. Give it about 3 minutes for its first start.

Install StonePi

On your computer, connected to the Pi over SSH. One-time setup.

1. Run the StonePi installer

   Your Pi has no screen or keyboard, so you control it from your computer over your home network, using SSH (a secure text connection). You only need it this once: after this, everything happens in your browser.

   Open a command window on your computer to connect to the Pi. If you're not sure how, choose your computer's system below:

   Windows (PowerShell / Command Prompt) macOS (Terminal) Linux (Terminal)

   Enter the username and hostname you set in Step 4 (this updates the commands below):

   Pi Username Pi Hostname

   1. Connect to your Pi:

   ssh pi@stonepi.local

   Copy

   What happens when you connect:

   Security fingerprint check (first time connecting): You'll likely see a security prompt like:

   The authenticity of host 'stonepi.local' can't be established. ED25519 key fingerprint is SHA256:.... Are you sure you want to continue connecting (yes/no/[fingerprint])?

   Type the word yes and press Enter. (This is normal security verification the first time any computer connects to a new device.)

   Password prompt: Next, enter the Pi password you set in step 4.

   Nothing appears as you type your password. No dots or asterisks, and the cursor doesn't move. That's normal in PowerShell and Terminal: type it and press Enter.

   Having trouble connecting?

   stonepi.local can't be found

   Check your computer is on the same home network as the Pi, wait another minute and try again. If it still fails, find the Pi's IP address in your router's device list and use that instead, for example ssh you@192.168.1.50 or http://192.168.1.50/.

   "Connection refused" or "Connection timed out"

   1. The Pi may still be starting. The first start takes a few minutes; wait two more and try again.

   2. SSH may be off. If it wasn't enabled in Imager (step 4), the Pi won't accept connections: re-flash the card with SSH enabled.

   3. The Pi may not be on the network. Check the Ethernet cable, or that the Wi-Fi name, password and country in step 4 were right. If the Pi isn't in your router's device list, re-flash with the correct Wi-Fi details.

   SSH rejects the password, or nothing appears as you type

   1. Password typing is invisible: In Terminal and PowerShell, no characters or dots show when typing passwords. Type your password and press Enter.

   2. Which password? Use the Pi username and password you set in Raspberry Pi Imager (step 4), not the web dashboard admin password.

   3. If you forgot the password, re-flash the microSD card and set a new one in step 4.

   SSH says "REMOTE HOST IDENTIFICATION HAS CHANGED"

   If you re-flashed your microSD card, or previously connected to another Raspberry Pi using the same name (stonepi.local), your computer detects the security fingerprint has changed and blocks the connection for safety.

   To fix this, clear the old remembered key by running this command in your computer's PowerShell or Terminal:

   ssh-keygen -R stonepi.local

   Copy

   If connecting using an IP address instead of stonepi.local, run ssh-keygen -R <your-pi-ip>.

   Then run your ssh command again and type yes when prompted.

   Connecting from a different or second computer

   Each computer maintains its own known devices list. The first time you connect from any new machine, SSH will ask the fingerprint check (Are you sure you want to continue connecting?). Type yes and press Enter.

   2. Run the StonePi installer:

   Once connected, paste this single line and press Enter:

   curl -fsSL https://stonepi-install.vercel.app/install.sh | sudo bash

   Copy

   It runs as administrator, so you may want to read the script first. It's plain text: it checks your Pi, downloads the release listed in manifest.json, verifies its checksum and runs that release's installer.

   This takes 15 to 25 minutes. StonePi downloads packages and sets up its services, security settings and the household apps.

   The window can sit on one step for several minutes. Leave it open until you see the summary below.

   If the window closes or the connection drops, connect again with ssh and run the same command. The installer picks up where it stopped.

   What success looks like

   The installer ends with a summary like this (your passwords and address will be different):

   Your StonePi is ready. Open: http://stonepi.local/ or: http://192.168.1.50/ Sign in as admin with password your-admin-password … Recover (emergency console, if the Dashboard is down): http://stonepi.local/recover/ Sign in as stonepi with password your-recover-password

   Save both passwords now, in a password manager or somewhere safe. The admin one signs you in to StonePi in step 7; the stonepi one opens Recover if the Dashboard is ever down.

   If it says "StonePi is installed, but … ready check(s) failed", scroll up to the FAIL lines, or run the same install command again.

Open StonePi

Any browser on your home network: phone, tablet or computer.

1. Open StonePi

   On any computer, tablet or phone on the same home network, open your web browser and go to:

   http://stonepi.local/

   Copy

   Sign in with the web administrator account the installer created:

   Web Address

   http://stonepi.local/

   Username

   admin

   Password

   The one shown at the end of the install (it's random for each Pi). Lost it? On the Pi run sudo cat /etc/stonepi/initial-admin.txt

   This is StonePi's web sign-in, not your Pi password. Change it after you sign in, under Settings → General → Your password.

   Remote access is optional. To reach StonePi away from home, set up Tailscale later under Settings → Network. Nothing else needs it.

curl -fsSL https://stonepi-install.vercel.app/install.sh | sudo bash -s -- --reinstall