A standalone frame

The simplest way to run FrameOS is to run only the frame. No backend, no account: a Raspberry Pi boots a FrameOS SD image, you connect it to WiFi from your phone, and from then on you manage it through the web app the frame serves itself. This is the right starting point if you want one frame, want it quickly, and want nothing else in the picture.

If you later want more - several frames in one place, compiled Nim apps, a build server - you can hand the same frame to a self-hosted backend (Adopt frame) or to FrameOS Cloud (link it with the code on its display). Nothing needs reflashing.

1. Flash a generic image

Download the image for your board from the latest release:

Flash it with Raspberry Pi Imager ("Use custom image") or balenaEtcher - both read the .img.gz as is. Connect the display, insert the card, power up.

2. Set it up from your phone

With no WiFi configured, the frame starts a hotspot called FrameOS-Setup (password frame1234). Join it from your phone or laptop and open http://10.42.0.1:8787/ (the panel shows the same address). The setup page asks for:

• your WiFi network and password;
• the display - every driver is in the image, so you pick your panel here, plus rotation and any driver extras (VCOM for an IT8951 panel, for instance);
• a name and an admin password for the frame;
• Manage via: choose Nothing (standalone). The other two options enroll the frame with FrameOS Cloud or point it at a self-hosted backend - you can change your mind later from the admin page.

Save, and the Pi joins your network. If the WiFi password was wrong, the frame keeps trying for about 90 seconds before the FrameOS-Setup hotspot comes back. On HDMI you watch it happen: the FrameOS status screen draws the boot steps as they go ("Checking network…", "Network connected. Loading scenes…"). E-ink panels get the same screen once the frame is up: its name, display and resolution, IP address, time zone, how it is managed (standalone), and the frame's URL.

3. Open the admin page

Browse to http://<frame-ip>:8787/admin (the status screen shows the address) and sign in with the admin password. This is a full management UI served by the frame itself:

• Scenes: install from the built-in sample and gallery repositories (add the scene store as one more), upload a scene ZIP, or build your own in the same node-graph scene editor the backend has. Scenes are interpreted, so there is nothing to compile - save, and it is live.
• Settings: everything under Useful settings - access mode, QR code, time zone, nightly reboot, metrics, the display driver.
• Schedule, Logs, Metrics, Assets - the same panels a backend shows for the frame, running against the device.
• Settings → FrameOS upgrade: the frame downloads a new release itself, verifies the signature, and swaps it in on the next reboot.

The control page at http://<frame-ip>:8787/c and the HTTP API work exactly as on any other frame, and the QR code on the display points at them.

What you give up

Only what needs a build machine or a second computer: compiled scenes and custom Nim apps, the backend's Terminal, headless Chromium screenshots, managing several frames from one screen, and the backend's library of scene templates and fonts. JavaScript apps, code nodes, state fields, all ~40 built-in apps, schedules and images of any size are all there.

To change the display later without the web UI, the FrameOS binary has a small CLI you can run over SSH, if you enabled root login:

cd /srv/frameos/current
./frameos set-display --device=pimoroni.inky_impression_13 --rotate=90
./frameos driver-setup

Next step

Want to see a few more frames at once, or build apps in Nim? Install the backend and adopt this frame. Want to manage it from anywhere without hosting anything? Link it to FrameOS Cloud.