{"id":50013497,"url":"https://github.com/frameos/frameos","last_synced_at":"2026-06-26T20:00:43.256Z","repository":{"id":188218722,"uuid":"669318006","full_name":"FrameOS/frameos","owner":"FrameOS","description":"Operating system for single function smart frames","archived":false,"fork":false,"pushed_at":"2026-06-21T23:14:35.000Z","size":257883,"stargazers_count":439,"open_issues_count":10,"forks_count":13,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-06-21T23:18:40.802Z","etag":null,"topics":["framebuffer","hdmi","inky","inkyimpression","pimoroni","raspberry-pi","waveshare","waveshare-epaper"],"latest_commit_sha":null,"homepage":"https://frameos.net/","language":"Nim","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FrameOS.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2023-07-21T22:58:16.000Z","updated_at":"2026-06-21T22:59:13.000Z","dependencies_parsed_at":"2023-09-22T05:09:38.501Z","dependency_job_id":"cf11d4e9-a7d6-42fd-8221-0407c135c2bb","html_url":"https://github.com/FrameOS/frameos","commit_stats":null,"previous_names":["mariusandra/frameos","frameos/frameos"],"tags_count":32,"template":false,"template_full_name":null,"purl":"pkg:github/FrameOS/frameos","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FrameOS%2Fframeos","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FrameOS%2Fframeos/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FrameOS%2Fframeos/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FrameOS%2Fframeos/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FrameOS","download_url":"https://codeload.github.com/FrameOS/frameos/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FrameOS%2Fframeos/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34831250,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-26T02:00:06.560Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["framebuffer","hdmi","inky","inkyimpression","pimoroni","raspberry-pi","waveshare","waveshare-epaper"],"created_at":"2026-05-20T02:02:46.828Z","updated_at":"2026-06-26T20:00:43.251Z","avatar_url":"https://github.com/FrameOS.png","language":"Nim","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FrameOS\n\nFrameOS is an **operating system for single function smart frames**. \n\nIt's meant to be deployed on a Raspberry Pi, and can be used with a variety of e-ink and traditional displays. It's designed for both screens that update **60 seconds per frame**, and for screens that update **60 frames per second**.\n\nThink smart home calendars, meeting room displays, thermostats, industrial dashboards, public advertisement screens, and more.\n\nTo get started:\n\n1. Install the [FrameOS backend](https://frameos.net/guide/backend), a dockerized python app, which is used to deploy apps onto individual frames via SSH.\n\n2. Read the [device hardware guide](https://frameos.net/devices/) for your screen type. Typically you'll just need to connect the display to a Raspberry Pi, install the OS, and make sure it's reachable over the network. \n\n3. Once connected, deploy our prebuilt scenes, or code your own directly inside the backend.\n\n4. Finally, for a professional look, 3d print a case around your frame.\n\n![](https://frameos.net/assets/images/walkthrough-c32e7b67dd9a6f14ebef743755b0fc8e.gif)\n\n\n## Development with Flox\n\nIf you use [Flox](https://flox.dev), this repo now ships a checked-in environment. Running `flox activate` bootstraps the core toolchains and installs the repo-local development dependencies for Python, pnpm, and Nim.\n\n```bash\nflox activate\npnpm dev\n```\n\nThe activation hook creates a local `.venv`, installs `backend/requirements.txt`, runs `pnpm install --frozen-lockfile` for the workspace, and installs the Nim dependencies for `frameos/` and `frameos/remote/`.\n\nIf you want Redis managed by Flox as well, start it with:\n\n```bash\nflox services start redis\n```\n\n\n\n## Supported platforms\n\nSupported are all the most common e-ink displays out there.\n\n- Pimoroni e-ink frames\n- Waveshare e-ink\n- Framebuffer HDMI output\n- Web server kiosk mode\n\n[See the full list here!](https://frameos.net/devices/)\n\n## FrameOS backend\n\nThe FrameOS backend is where you set up your frames. You can run it continuously on a server, or locally on your computer when needed. You'll just miss out on log aggregation if the backend is offline. The frames run independently.\n\nRead more in [the documentation](https://frameos.net/guide/backend).\n\n### Quick install\n\nThe easiest way to install the FrameOS backend on a Mac or Debian/Ubuntu Linux is to run the following installation script:\n\n```bash\nbash \u003c(curl -fsSL https://frameos.net/install.sh)\n```\n\n### Running via Docker manually\n\n```bash\n# running the latest release\nSECRET_KEY=$(openssl rand -base64 32)\nmkdir -p db\ndocker run -d -p 8989:8989 \\\n    -v ./db:/app/db \\ \n    --name frameos \\\n    --restart always \\\n    -e SECRET_KEY=\"$SECRET_KEY\" \\\n    frameos/frameos\n\n# SD card image generation works in the default container without Docker privileges.\n# If you want to speed up source builds with cross-compilation, enable Docker access.\n# This lets FrameOS spin up containers for the various build environments.\n# Alternatively, skip this, and configure a remote build server, or build on devices directly.\nSECRET_KEY=$(openssl rand -base64 32)\nmkdir -p db\nmkdir -p /tmp/frameos-cross\ndocker run -d -p 8989:8989 \\\n    -v ./db:/app/db \\\n    -v /tmp/frameos-cross:/tmp/frameos-cross \\\n    -v /var/run/docker.sock:/var/run/docker.sock \\\n    --privileged \\\n    --name frameos \\\n    --restart always \\\n    -e SECRET_KEY=\"$SECRET_KEY\" \\\n    -e TMPDIR=/tmp/frameos-cross \\\n    frameos/frameos\n\n# update daily to the latest release\ndocker run -d \\\n    --name watchtower \\\n    -v /var/run/docker.sock:/var/run/docker.sock \\\n    containrrr/watchtower \\\n    --interval 86400 \\\n    frameos\n\n# one time update\ndocker run \\\n    -v /var/run/docker.sock:/var/run/docker.sock \\\n    containrrr/watchtower \\\n    --run-once \\\n    frameos\n\n# running a local dev build via docker\nSECRET_KEY=$(openssl rand -base64 32)\ndocker build -t frameos .\ndocker run -d -p 8989:8989 \\\n    -v ./db:/app/db \\\n    -v /tmp/frameos-cross:/tmp/frameos-cross \\\n    -v /var/run/docker.sock:/var/run/docker.sock \\\n    --privileged \\\n    --name frameos \\\n    --restart always \\\n    -e SECRET_KEY=\"$SECRET_KEY\" \\\n    -e TMPDIR=/tmp/frameos-cross \\\n    frameos\n```\n\n### Cross-toolchain build container images\n\nCross-compilation uses prebuilt toolchain containers from Docker Hub at `frameos/frameos-cross-toolchain` when possible, which avoids rebuilding the toolchain image for every target.\n\nThe workflow `.github/workflows/frameos-cross-toolchain.yml` builds and publishes these images.\n\nThe image name is resolved as:\n\n- `{repo}:{base}_{version}-{platform}-{tag}`\n- `base` is the Linux distro (`debian`, `ubuntu`, ...)\n- `version` is the distro version (for example `bookworm` or `26.04`)\n- `platform` is the docker platform with `/` replaced by `_` (for example `linux_amd64`, `linux_arm64`, `linux_arm_v7`)\n- `tag` defaults to `latest`\n\nYou can override the default behavior with environment variables:\n\n- `FRAMEOS_CROSS_TOOLCHAIN_IMAGE`: full Docker image override (can be a Python format template using `slug`, `base`, `platform`, and `tag`)\n- `FRAMEOS_CROSS_TOOLCHAIN_IMAGE_REPO`: image repository (default `frameos/frameos-cross-toolchain`)\n- `FRAMEOS_CROSS_TOOLCHAIN_IMAGE_TAG`: image tag used by the default resolver (default `latest`)\n- `FRAMEOS_CROSS_TOOLCHAIN_FORCE_LOCAL_BUILD=1`: force rebuilding the toolchain image locally, even if a remote tag exists\n- `FRAMEOS_CROSS_TOOLCHAIN_SKIP_PULL=1`: skip pulling remote images and only use local/locally built images\n\nExample for local iteration on a new toolchain image:\n\n```bash\nexport FRAMEOS_CROSS_TOOLCHAIN_IMAGE=frameos/frameos-cross-toolchain:debian_trixie-linux_arm_v7-my-wip\nexport FRAMEOS_CROSS_TOOLCHAIN_FORCE_LOCAL_BUILD=1\n```\n\n### Buildroot image cache\n\nBuildroot SD image generation supports a cached Buildroot image with dependency packages preinstalled and the Buildroot tarball preloaded at `/frameos-buildroot`.\n\nYou can control the cached image with:\n\n- `FRAMEOS_BUILDROOT_IMAGE`: optional full image name override (supports `{slug}`, `{base}`, `{version}`, and `{tag}` placeholders)\n- `FRAMEOS_BUILDROOT_IMAGE_REPO`: image repository (default `frameos/frameos-buildroot`)\n- `FRAMEOS_BUILDROOT_IMAGE_TAG`: image tag (default `latest`)\n- `FRAMEOS_BUILDROOT_FORCE_LOCAL_BUILD=1`: force rebuilding the Buildroot image locally\n- `FRAMEOS_BUILDROOT_SKIP_PULL=1`: skip pulling cached images from the registry\n- `FRAMEOS_BUILDROOT_DOCKER_IMAGE`: base image used when building `frameos-buildroot` (default `debian:bookworm`)\n- `FRAMEOS_BUILDROOT_IMAGES_DIGESTS_PATH`: path to the digest manifest (default `buildroot-images.json` in repo root)\n- `FRAMEOS_BUILDROOT_FRAMEOS_PARTITION_SIZE`: `/srv/frameos` ext4 partition size (default `1G`)\n- `FRAMEOS_BUILDROOT_ASSETS_PARTITION_SIZE`: `/srv/assets` FAT32 partition size (default `512M`)\n\nBuildroot-specific output cache keys include the resolved cache image, so changing image configuration invalidates stale output directories automatically.\n\nGenerated SD images use separate partitions for boot, root, FrameOS runtime data, and assets:\n\n- `p1`: FAT32 boot partition\n- `p2`: ext4 root filesystem\n- `p3`: ext4 `/srv/frameos`\n- `p4`: FAT32 `/srv/assets`\n\nOn first boot, Buildroot images expand themselves to fit the target SD card\nbefore `/srv/frameos` and `/srv/assets` are mounted. The root partition stays at\nthe image size, `p3` grows to 2 GiB on cards 4 GiB and larger, and `p4` is\nrecreated to fill the remaining space. On cards smaller than 4 GiB, `p3` stays\nat 1 GiB and `p4` still takes the rest.\n\nExample:\n\n```bash\nexport FRAMEOS_BUILDROOT_IMAGE_REPO=frameos/frameos-buildroot\nexport FRAMEOS_BUILDROOT_IMAGE_TAG=latest\nexport FRAMEOS_BUILDROOT_FORCE_LOCAL_BUILD=1\n```\n\nThe corresponding GitHub workflow is `.github/workflows/frameos-buildroot.yml` and triggers on pushes to `main` when `backend/tools/buildroot.Dockerfile` changes. It writes `buildroot-images.json` with digest data used by runtime image resolution.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fframeos%2Fframeos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fframeos%2Fframeos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fframeos%2Fframeos/lists"}