# How to install Reefy

Flash a USB drive, boot a PC, and adopt your first Reefy device.

Reefy does not require a traditional installation. Flash the Reefy image to a
USB drive and boot the PC from it. Reefy runs directly from the USB drive,
leaving internal storage available for encrypted application data.

## What you need

- An x86-64 PC with at least 4 GB of RAM
- An 8 GB or larger USB drive
- Ethernet or supported Wi-Fi for first connection
- Another computer for downloading and flashing the image
- [Balena Etcher](https://etcher.balena.io/) for Windows, macOS, or Linux

Read [supported hardware](/docs/supported-hardware) before buying hardware
specifically for Reefy.

## 1. Download the image

Sign in to the [Reefy dashboard](/dashboard) and start the image download. The
downloaded raw image contains the bootstrap identity used to associate a newly
booted device with your account. Treat it as private account material.

## 2. Flash the USB drive

With [Balena Etcher](https://etcher.balena.io/), select the downloaded
`reefy.raw` file, select the USB drive, and start the flash. Etcher validates
the completed write before you boot the target PC.

On Linux or macOS, experienced operators can use:

```bash
sudo dd if=reefy.raw of=/dev/sdX bs=4M status=progress conv=fsync
```

Replace `/dev/sdX` with the whole USB device, not one of its partitions. This
command overwrites the selected drive.

## 3. Boot the target PC

Insert the USB drive and open the firmware boot menu. Common keys are `Esc`,
`F12`, `F11`, or `Del`. Select the UEFI entry for the USB drive.

If the firmware refuses to boot the image, disable Secure Boot. Reefy's image
is prepared for a future signed Secure Boot chain, but the public image is not
currently signed for arbitrary factory keys.

## 4. Connect the device

Ethernet is the simplest first-boot path. Reefy starts its control plane and
connects outbound to the service. No inbound port forwarding is required.

The device should appear in the dashboard as pending. First boot is usually
fast, but firmware initialization and network conditions vary by machine.

## 5. Adopt it

Open the pending device, choose **Adopt**, and give it a name. Adoption creates
the device identity, prepares encrypted storage, and sends the initial desired
state.

After adoption, install an application from the catalog. Return to the
[Reefy technical overview](/docs) for details about applications, storage,
backups, and remote access.

## Common problems

### The USB drive is missing from the boot menu

Confirm that USB boot is enabled, try another USB port, and prefer a direct
motherboard port over a hub. Reflash the image if the drive is detected by
another computer but not bootable.

### The device boots but never appears

Use Ethernet if possible. Confirm the network provides DHCP and outbound HTTPS
and MQTT connectivity. Networks with captive portals cannot complete an
unattended first connection.

### The machine returns to its old operating system

Use the one-time firmware boot menu or move the Reefy USB entry above the
internal disk in UEFI boot order.