Network Boot Your Raspberry Pi

Boot a Pi 4 or Pi 5 from ipxe.cloudcompute.com. No SD card OS required.

Boot Tracking

-
Successful Boots
-
Today

Recent Boots

Loading...

Machine Registry

IDMACStateRoleLast SeenAssign
Loading...

What You Need

A Raspberry Pi 4 or 5 with ethernet connected to a network with internet access, plus our Docker bootstrap container running on the same network.

Pi 3 and older have limited network boot support and are not recommended. Pi 4 and Pi 5 have UEFI firmware that works with iPXE.

Setup Steps

Setting up a Pi 4 as a frame? The frame setup page offers a prebuilt, generic card image that replaces steps 1–3 below: no firmware download, no UEFI setup screen, no bootstrap container. Write it, plug in Ethernet, power on, and watch the machine check in. There is a step-by-step walkthrough of what that looks like.

1. Prepare the Pi's SD card Pi 4 Pi 5

You need a minimal SD card with UEFI firmware. Download the latest Raspberry Pi UEFI firmware:

# Download Pi 4 UEFI firmware
curl -LO https://github.com/pftf/RPi4/releases/latest/download/RPi4_UEFI_Firmware_v1.38.zip

# Or Pi 5 UEFI firmware
curl -LO https://github.com/worproject/rpi5-uefi/releases/latest/download/RPi5_UEFI_Release_v0.3.zip

# Format SD card as FAT32 and extract firmware to it
# On macOS:
diskutil eraseDisk FAT32 BOOT /dev/diskN
unzip RPi4_UEFI_Firmware_*.zip -d /Volumes/BOOT/

2. Configure UEFI for Network Boot

Insert the SD card into the Pi, connect a monitor, and power on. You'll see the UEFI setup screen.

# In UEFI Setup:
# 1. Go to Boot Maintenance Manager → Boot Options
# 2. Change Boot Order: move "UEFI PXEv4" to first
# 3. (Optional) Disable "Limit RAM to 3 GB" under Device Manager
# 4. Save and exit

The Pi will now try network boot first on every power-on.

3. Start the Bootstrap Container

On any machine on the same network (your laptop, a server, another Pi), run:

# bootstrap.env (mode 600, outside any repo):
#   BOOTSTRAP_TOKEN=<random, 32+ chars — same value as the Worker secret>
#   BOOTSTRAP_ALLOWED_MACS=<this machine's MAC, comma-separated for more>
#   BOOTSTRAP_CLIENT_CIDR=192.168.1.0/24

# From the repo root (reads the same variables from the environment):
docker compose up

# Or standalone:
docker run --net=host --cap-add=NET_ADMIN \
  --env-file ./bootstrap.env \
  -e IPXE_SERVER_URL=https://ipxe.cloudcompute.com \
  -e DHCP_RANGE=192.168.1.0 \
  ghcr.io/fairchild/ipxe-bootstrap

This runs dnsmasq in proxy DHCP mode — it won't interfere with your existing router/DHCP — but it answers PXE only for allowlisted MACs, serves iPXE over TFTP, and runs a small boot proxy on :8080 that relays each machine's boot request to the Worker with the bootstrap bearer. The container fails closed if BOOTSTRAP_TOKEN or BOOTSTRAP_ALLOWED_MACS is missing.

4. Power On the Pi

With ethernet connected and the bootstrap container running:

# Boot chain:
# 1. Pi UEFI firmware → PXE DHCP request (answered only for an allowlisted MAC)
# 2. dnsmasq responds with iPXE ARM64 binary (ipxe-arm64.efi)
# 3. Pi loads iPXE via TFTP
# 4. iPXE does DHCP again, gets the non-secret bootstrap.ipxe via TFTP
# 5. bootstrap.ipxe chains to the local boot proxy on :8080
# 6. Proxy adds the bearer, fetches /boot.ipxe from the Worker over HTTPS
# 7. Boot menu appears — or the role/install script if this MAC is assigned
# 8. Check-in recorded ✓

Default: the ephemeral RAM node (Discovery) boots after the countdown and registers the Pi. Arrow up to pick Debian or sbnb instead. The bearer never leaves the bootstrap host; the Pi only ever sees a short-lived, one-use nonce.

5. Verify Check-in

Once booted, the OS can do a richer check-in from userspace:

# From the booted Pi:
curl -X POST https://ipxe.cloudcompute.com/api/checkin \
  -H "Content-Type: application/json" \
  -d '{"mac":"'$(cat /sys/class/net/eth0/address)'","target":"debian","stage":"os"}'

Check this page to see your Pi appear in the boot log above.

Troubleshooting

Pi doesn't PXE boot

Verify UEFI boot order has PXEv4 first. Check the bootstrap container logs: docker compose logs -f. You should see DHCP requests from the Pi's MAC address — and an offer after each one. A request with no offer means the MAC isn't in BOOTSTRAP_ALLOWED_MACS; dnsmasq ignores non-allowlisted clients silently.

iPXE loads but menu fails

iPXE needs HTTPS support. Stock iPXE from boot.ipxe.org includes HTTPS. If using custom builds, ensure DOWNLOAD_PROTO_HTTPS was enabled.

Assigned Pi gets the menu instead of its role

The role/install branch is served only when the request carries the bootstrap bearer. Confirm the Pi booted through the bootstrap proxy (its serial log shows a chain to http://<bootstrap host>:8080/boot.ipxe), and that BOOTSTRAP_TOKEN is the same value in the container's env file and the Worker secret. A wrong or missing token isn't an error — it's the public menu.

Debian installer starts but can't download packages

The Pi needs internet access. Verify the Pi can reach deb.debian.org. Check your router's DHCP is assigning a gateway and DNS.