# Installing Élise OS — instructions for coding agents

You are a coding agent (Claude Code, Codex, Cursor, or similar) helping a person install
Élise OS, a local-first home system that helps families look out for a relative who lives
alone. Follow these instructions step by step. Speak to the person in their language, in
plain words: they may not be technical.

Official sources only: https://github.com/Elise-OS/EliseOS and https://eliseos.paulbreton.dev.
Do not download Élise from anywhere else.

## Rules

1. Explain what you are about to do before each step, in one or two sentences.
2. Ask for explicit confirmation before any command that uses `sudo`, installs packages,
   or writes to a disk or memory card. Never guess which disk to write to.
3. Never ask the person for a password, token or private key, and never paste one into a
   command. Let `sudo` prompt them directly in the terminal.
4. Do not change firewall, SSH or network settings beyond what the official installer does.
5. Stop and ask if anything does not match these instructions (unknown OS, unexpected
   error, a port already in use by another service).
6. Élise is in a testing phase. It is not a medical device or an emergency service; say
   so once if the person seems to expect that.

## The person's message

The person usually pastes a message generated by https://eliseos.paulbreton.dev/installer/.
Its "situation" lines tell you which path to follow (A, B or C), where you are running,
the storage, the network, the TV and the Zigbee stick, and whether they or you write the
storage. Trust those lines for the plan, but still check the machine: if what you see
contradicts them, say so and ask before continuing.

## 1. Find out where Élise should run

If the message does not say, ask the person, or check the current machine:

```bash
uname -m
cat /etc/os-release 2>/dev/null | head -5
docker --version 2>/dev/null; docker compose version 2>/dev/null
free -g | head -2
df -h / | tail -1
```

Then choose one path:

| Situation | Path |
| --- | --- |
| This machine runs Ubuntu Server 24.04 (AMD64 or ARM64) | **A — Ubuntu installer** (recommended, complete) |
| The person wants a dedicated Raspberry Pi 4 or 5 and you are on their computer with the memory card plugged in | **B — Raspberry Pi image** |
| Another Linux machine that already runs Docker (NAS, home server) | **C — Docker Compose** (core only, no TV screen) |
| macOS or Windows without Docker | Explain that Élise needs a Raspberry Pi or a Linux server, and offer path B |

Recommended hardware: 8 GB of memory (4 GB minimum, too tight for the TV screen and video calls), 32 GB of storage with 16 GB free.

## A — Ubuntu Server 24.04

Requirements: Ubuntu Server 24.04 LTS, AMD64 or ARM64, ports 8080, 18080 and 8555 free.

Check the ports:

```bash
ss -ltn | grep -E ':(8080|18080|8555) ' || echo "ports free"
```

After confirmation, run the official installer. It verifies the Sigstore signature of the
release, installs Docker, Tailscale and Avahi, then starts Élise and waits until it is healthy:

```bash
curl -fsSL https://github.com/Elise-OS/EliseOS/releases/latest/download/install-elise.sh | sudo bash
```

Check the result:

```bash
curl -fsS http://127.0.0.1:8080/api/v1/system/health
```

A healthy answer contains `"status":"ok"`. Give the person the address
`http://<hostname>.local:8080` (from `hostname`), or `http://<LAN IP>:8080`.

## B — Raspberry Pi 4 or 5 image

The person needs a Raspberry Pi 4 with 8 GB of memory (or a Pi 5), a 32 GB card or SSD, and
Raspberry Pi Imager (https://www.raspberrypi.com/software/).

1. Find the latest release and download the image and its checksum:

   ```bash
   VERSION=$(basename "$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/Elise-OS/EliseOS/releases/latest)")
   curl -fLO https://github.com/Elise-OS/EliseOS/releases/download/$VERSION/elise-os-$VERSION-raspberry-pi-arm64.img.xz
   curl -fsSLO https://github.com/Elise-OS/EliseOS/releases/download/$VERSION/elise-os-$VERSION-raspberry-pi-arm64.img.xz.sha256
   shasum -a 256 -c elise-os-$VERSION-raspberry-pi-arm64.img.xz.sha256
   ```

   (`sha256sum -c` on Linux.) The image is about 1.6 GB.

   On Windows, use PowerShell and `curl.exe` (not the `curl` alias), then compare the
   hashes yourself:

   ```powershell
   $Version = (Invoke-RestMethod https://api.github.com/repos/Elise-OS/EliseOS/releases/latest).tag_name
   $Image = "elise-os-$Version-raspberry-pi-arm64.img.xz"
   curl.exe -fLO "https://github.com/Elise-OS/EliseOS/releases/download/$Version/$Image"
   curl.exe -fsSLO "https://github.com/Elise-OS/EliseOS/releases/download/$Version/$Image.sha256"
   $Expected = (Get-Content "$Image.sha256").Split(" ")[0]
   (Get-FileHash $Image -Algorithm SHA256).Hash.ToLower() -eq $Expected.ToLower()
   ```

   `True` means the file is intact. If the GitHub API is rate-limited, open
   https://github.com/Elise-OS/EliseOS/releases/latest and read the tag (for example `v0.1.12`).

2. Writing the storage. By default, the person writes it with the Raspberry Pi Imager
   window: tell them the full path of the downloaded file, then guide them ("Use custom" →
   the file, then the storage). In Imager's settings they set the hostname `elise`, their
   Wi-Fi, country and time zone. They type the Wi-Fi password themselves.

   Write the storage yourself only if the person's message or the person asks you to, and
   only on macOS or Linux (on Windows, always use Imager):

   - List the disks and show them to the person: `diskutil list external physical` on
     macOS, `lsblk -d -o NAME,SIZE,MODEL,TRAN,RM` on Linux.
   - Have the person name the disk by its size and model. Never pick it yourself, never
     use the system disk, and stop if the size does not match a card or SSD of 32 GB or more.
   - Confirm twice, quoting the disk name and size, then write:

     ```bash
     # macOS (disk4 is an example)
     diskutil unmountDisk /dev/disk4
     xz -dc elise-os-$VERSION-raspberry-pi-arm64.img.xz | sudo dd of=/dev/rdisk4 bs=4m
     diskutil eject /dev/disk4

     # Linux (sdX is an example)
     xz -dc elise-os-$VERSION-raspberry-pi-arm64.img.xz | sudo dd of=/dev/sdX bs=4M conv=fsync status=progress
     ```

   - A raw write skips Imager's customisation: Wi-Fi is not configured, so the box must be
     connected with a network cable for its first boot. Say so before writing.
   - For an NVMe SSD on a Pi 5, the person connects it through a USB adapter. If the Pi
     does not boot from it afterwards, point them to Imager's "Bootloader" utility image
     (NVMe/USB boot option).

3. They insert the card in the Raspberry Pi, connect it to the router (or rely on Wi-Fi)
   and, optionally, to the TV over HDMI, then power it on.

4. After a few minutes they open http://elise.local on a phone or computer on the same
   network. A "Preparing Élise" page shows progress, then an assistant creates the
   administrator account.

## C — Docker Compose (existing Docker host)

Requirements: Docker Engine 23+, Docker Compose v2.24.4+, Linux AMD64 or ARM64, ports 8080
and 8555 free. This path installs the Élise core only: no TV screen, no automatic updates,
no Tailscale integration. Tell the person before starting.

```bash
VERSION=$(basename "$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/Elise-OS/EliseOS/releases/latest)")
mkdir -p ~/elise && cd ~/elise
curl -fsSLO https://github.com/Elise-OS/EliseOS/releases/download/$VERSION/elise-runtime-$VERSION.tar.gz
curl -fsSLO https://github.com/Elise-OS/EliseOS/releases/download/$VERSION/elise-runtime-$VERSION.tar.gz.sha256
sha256sum -c elise-runtime-$VERSION.tar.gz.sha256
tar -xzf elise-runtime-$VERSION.tar.gz
cp .env.example .env
sed -i "s/^MICHEL_VERSION=.*/MICHEL_VERSION=$VERSION/" .env
bash scripts/detect-zigbee-adapter.sh --write-env .env
docker compose -p elise -f compose.yaml -f compose.release.yaml up -d
curl -fsS http://127.0.0.1:8080/api/v1/system/health
```

If an image pull answers `denied`, the machine probably holds an expired `ghcr.io` login:
the images are public. Suggest `docker logout ghcr.io` and retry.

## 4. Finish

- Give the person the address to open, and explain that the first page creates the
  administrator account (it only works from the home network).
- The USB Zigbee stick can be plugged in at any time; Élise detects it.
- For access away from home, point them to the remote access guide:
  https://eliseos.paulbreton.dev/docs/start/remote-access/
- Full guide: https://eliseos.paulbreton.dev/docs/start/