The backend

The backend is the control panel for your frames. You use it to design scenes, deploy them over SSH, and manage them through FrameOS Remote when they connect back to the backend. It's a single self-hosted web app - there is no hosted cloud version and no account to sign up for anywhere.

A few things worth knowing up front:

• The backend needs network access to your frames for first deploys and direct status checks (SSH and HTTP). After FrameOS Remote is installed, frames can also connect back to the backend over an outbound WebSocket.
• The backend does not need to stay running. Frames work fully standalone after a deploy. Keeping it running gets you log aggregation, metrics, and one-click redeploys.

Quick install

The easiest way to install on a Mac or a Debian/Ubuntu Linux machine:

bash <(curl -fsSL https://frameos.net/install.sh)

The script installs Docker if needed, then runs the frameos/frameos container on port 8989.

Home Assistant add-on

If you run Home Assistant, FrameOS is one click away:

1. Go to Settings → Add-ons → Add-on Store in Home Assistant.
2. Click the ⋮ menu in the top right corner and select Repositories.
3. Add https://github.com/FrameOS/frameos-home-assistant-addon.
4. Find FrameOS in the add-on list, click Install, then Start.
5. Optionally enable Start on boot and Watchdog.
6. Click Open Web UI.

Running via Docker manually

This is what the install script does under the hood:

# generate a stable secret key
SECRET_KEY=$(openssl rand -base64 32)
mkdir -p db

# run the latest release
docker run -d --name frameos --restart always \
    -p 8989:8989 \
    -v ./db:/app/db \
    -e SECRET_KEY="$SECRET_KEY" \
    frameos/frameos:latest

Then open http://localhost:8989 and create your local account.

To keep the container automatically up to date, add watchtower:

docker run -d --name watchtower \
    -v /var/run/docker.sock:/var/run/docker.sock \
    containrrr/watchtower --interval 86400 frameos

Faster builds with Docker access

SD card image generation works in the default container without extra privileges. If you also want the backend to cross-compile FrameOS from source in local build containers (instead of using precompiled binaries or building on the device), give it access to Docker:

SECRET_KEY=$(openssl rand -base64 32)
mkdir -p db /tmp/frameos-cross

docker run -d --name frameos --restart always \
    -p 8989:8989 \
    -v ./db:/app/db \
    -v /tmp/frameos-cross:/tmp/frameos-cross \
    -v /var/run/docker.sock:/var/run/docker.sock \
    --privileged \
    -e TMPDIR=/tmp/frameos-cross \
    -e SECRET_KEY="$SECRET_KEY" \
    frameos/frameos:latest

This is optional: for common targets FrameOS ships precompiled binaries, and you can also configure remote SSH build servers, or build on the frame itself, under Settings → Builds.

Local development with Flox

Use this path when you want to work on FrameOS itself instead of running the released Docker image. The repository ships a checked-in Flox environment that installs the Python, Node, pnpm, Nim and Redis tooling used by the backend and frontend.

git clone https://github.com/FrameOS/frameos.git
cd frameos
flox activate
pnpm dev

flox activate creates a repo-local .venv, installs backend/requirements.txt, runs pnpm install --frozen-lockfile, and installs the Nim dependencies for both the frame runtime and FrameOS Remote. The activation hook reruns only when the lockfiles or package definitions change.

pnpm dev opens an mprocs dashboard with the local services:

• backend - FastAPI on http://localhost:8989 with DEBUG=1.
• worker - the ARQ background worker used for deploys and builds.
• vite - the live frontend on http://localhost:8616, proxying /api and /ws to the backend.
• kea - frontend type generation in watch mode.
• redis - local Redis for jobs, logs, websockets and Remote connections.

Open http://localhost:8616 once the backend and Vite panes are ready. In development mode the backend runs database migrations before startup and creates a local .env with a development SECRET_KEY if you do not already have one.

If you prefer to run processes manually, start Redis with either the redis pane in pnpm dev or Flox services:

flox services start redis
pnpm run dev:backend
pnpm run dev:worker
pnpm --dir frontend run dev

Next step

Time to prepare your Raspberry Pi: set up the Raspberry.