{"id":26907138,"url":"https://github.com/usetrmnl/byos_laravel","last_synced_at":"2026-02-03T23:11:07.114Z","repository":{"id":280999629,"uuid":"942927441","full_name":"usetrmnl/byos_laravel","owner":"usetrmnl","description":"A self-hosted, community-driven server (BYOS) with Recipe support in PHP's Laravel framework","archived":false,"fork":false,"pushed_at":"2026-01-29T07:04:24.000Z","size":6852,"stargazers_count":195,"open_issues_count":12,"forks_count":49,"subscribers_count":7,"default_branch":"main","last_synced_at":"2026-01-29T22:56:02.321Z","etag":null,"topics":["byos","trmnl","trmnlserver"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/usetrmnl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE.md","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":null,"dco":null,"cla":null},"funding":{"custom":["https://trmnl.com/?ref=laravel-trmnl"]}},"created_at":"2025-03-04T22:43:47.000Z","updated_at":"2026-01-29T06:59:55.000Z","dependencies_parsed_at":"2025-12-07T12:08:01.304Z","dependency_job_id":null,"html_url":"https://github.com/usetrmnl/byos_laravel","commit_stats":null,"previous_names":["usetrmnl/byos_laravel"],"tags_count":89,"template":false,"template_full_name":null,"purl":"pkg:github/usetrmnl/byos_laravel","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usetrmnl%2Fbyos_laravel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usetrmnl%2Fbyos_laravel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usetrmnl%2Fbyos_laravel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usetrmnl%2Fbyos_laravel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/usetrmnl","download_url":"https://codeload.github.com/usetrmnl/byos_laravel/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usetrmnl%2Fbyos_laravel/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29060673,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-03T22:28:58.191Z","status":"ssl_error","status_checked_at":"2026-02-03T22:28:56.515Z","response_time":96,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["byos","trmnl","trmnlserver"],"created_at":"2025-04-01T11:37:53.895Z","updated_at":"2026-02-03T23:11:07.108Z","avatar_url":"https://github.com/usetrmnl.png","language":"PHP","funding_links":["https://trmnl.com/?ref=laravel-trmnl","https://www.buymeacoffee.com/bnussbau","https://github.com/sponsors/bnussbau/"],"categories":["PHP","👾 Extra's"],"sub_categories":[],"readme":"## TRMNL BYOS (PHP/Laravel)\n\n[![tests](https://github.com/usetrmnl/byos_laravel/actions/workflows/test.yml/badge.svg)](https://github.com/usetrmnl/byos_laravel/actions/workflows/test.yml)\n\nTRMNL BYOS Laravel is a self-hostable implementation of a TRMNL server, built with Laravel.\nIt allows you to manage TRMNL devices, generate screens using **native plugins** (Screens API, Markup), **recipes** (130+ from the [OSS community catalog](https://bnussbau.github.io/trmnl-recipe-catalog/), 700+ from the [TRMNL catalog](https://trmnl.com/recipes), or your own), or the **API**, and can also act as a **proxy** for the native cloud service (Core). With over 50k downloads and 200+ stars, it’s the most popular community-driven BYOS.\n\n![Screenshot](README_byos-screenshot.png)\n![Screenshot](README_byos-screenshot-dark.png)\n\n* 👉 [more Screenshots](screenshots/SCREENSHOTS.md)\n\n### Key Features\n\n* 📡 Device Information – Display battery status, WiFi strength, firmware version, and more.\n* 🔍 Auto-Join – Automatically detects and adds devices from your local network.\n* 🖥️ Screen Generation – Supports Plugins (including Mashups), Recipes, API, Markup, or updates via Code.\n  * Support for TRMNL [Design Framework](https://trmnl.com/framework)\n  * Compatible open-source recipes are available in the [community catalog](https://bnussbau.github.io/trmnl-recipe-catalog/)\n  * Import from the [TRMNL community recipe catalog](https://trmnl.com/recipes)\n  * Supported Devices\n    * TRMNL OG (1-bit \u0026 2-bit)\n    * SeeedStudio TRMNL 7,5\" (OG) DIY Kit\n    * Seeed Studio (XIAO 7.5\" ePaper Panel)\n    * reTerminal E1001 Monochrome ePaper Display\n    * Custom ESP32 with TRMNL firmware\n    * E-Reader Devices\n      * KOReader ([trmnl-koreader](https://github.com/usetrmnl/trmnl-koreader))\n      * Kindle ([trmnl-kindle](https://github.com/usetrmnl/byos_laravel/pull/27))\n      * Nook ([trmnl-nook](https://github.com/usetrmnl/trmnl-nook))\n      * Kobo ([trmnl-kobo](https://github.com/usetrmnl/trmnl-kobo))\n    * Android Devices with [trmnl-android](https://github.com/usetrmnl/trmnl-android)\n    * Raspberry Pi (HDMI output) [trmnl-display](https://github.com/usetrmnl/trmnl-display)\n* 🔄 TRMNL API Proxy – Can act as a proxy for the native cloud service (requires TRMNL Developer Edition).\n    * This enables a hybrid setup – for example, you can update your custom Train Monitor every 5 minutes in the morning, while displaying native TRMNL plugins throughout the day.\n* 🌙 Dark Mode – Switch between light and dark mode.\n* 🐳 Deployment – Dockerized setup for easier hosting (Dockerfile, docker-compose).\n* 💾 Flexible Database configuration – uses SQLite by default, also compatible with MySQL or PostgreSQL \n* 🛠️ Devcontainer support for easier development.\n\n![Devices](README_byos-devices.jpeg)\n\n### Support ❤️\nThis repo is maintained voluntarily by [@bnussbau](https://github.com/bnussbau).\n\nSupport the development of this package by purchasing a TRMNL device through the referral link: https://trmnl.com/?ref=laravel-trmnl. At checkout, use the code `laravel-trmnl` to receive a $15 discount on your purchase.\n\nor\n\n[![\"Buy Me A Coffee\"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/bnussbau)\n\n[GitHub Sponsors](https://github.com/sponsors/bnussbau/)\n\n### Hosting\n\nRun everywhere, where Docker is supported: Raspberry Pi, VPS, NAS, Container Cloud Service (Cloud Run, ...).\nFor production use, generate a new APP_KEY (`php artisan key:generate --show`) and set the environment variable `APP_KEY=`. For personal use, you can disable registration (see section Environment Variables).\n\n#### Docker Compose\nDocker Compose file located at: [docker/prod/docker-compose.yml](docker/prod/docker-compose.yml).\n\n##### Backup Database\n```sh\ndocker ps #find container id of byos_laravel container\ndocker cp {{CONTAINER_ID}}:/var/www/html/database/storage/database.sqlite database_backup.sqlite\n```\n\n##### Updating via Docker Compose\n```sh\ndocker compose pull\ndocker compose down\ndocker compose up -d\n```\n\n#### VPS\nIf you’re using a VPS (e.g., Hetzner) and prefer an alternative to native Docker, you can install Dokploy and deploy BYOS Laravel using the integrated [Template](https://templates.dokploy.com/?q=trmnl+byos+laravel).\nIt’s a quick way to get started without having to manually manage Docker setup.\n\n#### PikaPods\nYou can vote for TRMNL BYOS Laravel to be included as PikaPods Template here: [feedback.pikapods.com](https://feedback.pikapods.com/posts/842/add-app-trmnl-byos-laravel)\n\n#### Umbrel\nUmbrel is supported through a community store, [see](http://github.com/bnussbau/umbrel-store).\n\n#### Other Hosting Options\nLaravel Forge, or bare metal PHP server with Nginx or Apache is also supported.\n\n#### Requirements\n\n* PHP \u003e= 8.2\n* ext-imagick\n* puppeteer [see Browsershot docs](https://spatie.be/docs/browsershot/v4/requirements)\n\n### Local Development\n\nsee [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)\n\n\n### Demo Plugins\n\nRun the ExampleRecipesSeeder to seed the database with example plugins:\n\n```bash\nphp artisan db:seed --class=ExampleRecipesSeeder\n```\n\n* Zen Quotes\n* This Day in History\n* Weather\n* Train Departure Monitor\n* Home Assistant\n* Sunrise/Sunset\n\n### Usage\n\n#### Environment Variables\n\n| Environment Variable          | Description                                                                                                                                 | Default           |\n|-------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|-------------------|\n| `TRMNL_PROXY_BASE_URL`        | Base URL of the native TRMNL service                                                                                                        | https://trmnl.app |\n| `TRMNL_PROXY_REFRESH_MINUTES` | How often should the server fetch new images from native service                                                                            | 15                |\n| `REGISTRATION_ENABLED`        | Allow user registration via Webinterface                                                                                                    | 1                 |\n| `SSL_MODE`                    | SSL Mode, if not using a Reverse Proxy ([docs](https://serversideup.net/open-source/docker-php/docs/customizing-the-image/configuring-ssl)) | `off`             |\n| `FORCE_HTTPS`                 | If your server handles SSL termination, enforce HTTPS.                                                                                      | 0                 |\n| `PHP_OPCACHE_ENABLE`          | Enable PHP Opcache                                                                                                                          | 0                 |\n| `TRMNL_IMAGE_URL_TIMEOUT`     | How long TRMNL waits for a response on the display endpoint. (sec)                                                                          | 30                |\n| `APP_TIMEZONE`                | Default timezone, which will be used by the PHP date functions                                                                              | UTC               |\n\n#### Login\n\nIf your environment is local, you can access the server at `http://localhost:4567` and login with user / password\n`admin@example.com` / `admin@example.com`, otherwise register. With environment variable `REGISTRATION_ENABLED` you can control, if registration is allowed.\n\n### ➕ Add Your TRMNL Device\n\n##### Auto-Join (Local Network)\n\n1. Switch on the “Permit Auto-Join” toggle in the header. For that to work only one user can be registered.\n2. New devices on your local network will be detected and added automatically when connecting to the server.\n\n✅ This is the easiest way to connect your devices with minimal effort.\n\n##### Manually\n\n1.\tOpen the Devices page:\n      👉 http://localhost:4567/devices\n2.\tClick “Add New Device”.\n3.\tRetrieve your TRMNL MAC Address and API Key:\n- You can grab the TRMNL Mac Address and API Key from the TRMNL Dashboard\n- Alternatively, debug incoming requests to /api/setup to determine them\n\n\n### ⚙️ Configure Server for Device\n\n#### 📌 Firmware Version 1.4.6 or Newer\n\n* Setup device\n* After entering Wifi credentials, choose \"Custom Server\"\n* Point to the URL of your server\n\n#### Firmware Older Than 1.4.6\n\nIf your device firmware is older than 1.4.6, you need to flash a new firmware version to point it to your server.\n\nSee this YouTube guide: [https://www.youtube.com/watch?v=3xehPW-PCOM](https://www.youtube.com/watch?v=3xehPW-PCOM)\n\n### ☁️ Activate fresh TRMNL Device with Cloud Proxy\n\n1) Setup the TRMNL as in the official docs with the cloud service (connect one of the plugins to later verify it works)\n2) Setup Laravel BYOS, create a user and login\n3) In Laravel BYOS in the header bar, activate the toggle \"Permit Auto-Join\"\n4) Press and hold the button on the back of your TRMNL for 5 seconds to reactivate the captive portal (or reflash).\n5) Go through the setup process again, in the screen where you provide the Wi-Fi credentials there is also option to set the Server URL. Use the local address of your Laravel BYOS\n6) The device should automatically appear in the device list; you can deactivate the \"Permit Auto-Join\" toggle again.\n7) In the devices list, activate the toggle \"☁️ Proxy\" for your device. (Make sure that the queue worker is active. In the docker image it should be running automatically.)\n8) As long as no Laravel BYOS plugin is scheduled, the device will show your cloud plugins.\n\n###### Troubleshooting\n\nMake sure that your device has a Developer license, you should be able to verify by calling the `https://trmnl.app/api/display` endpoint.\n\n* [https://docs.usetrmnl.com/go/private-api/introduction](https://docs.usetrmnl.com/go/private-api/introduction)\n* [https://docs.usetrmnl.com/go/private-api/fetch-screen-content](https://docs.usetrmnl.com/go/private-api/fetch-screen-content)\n\n### 🖥️ Generate Screens\n\n#### Markup via Web Interface\n\n1.\tNavigate to Plugins \u003e Markup in the Web Interface.\n2.\tEnter your markup manually or select from the available templates.\n3.\tSave and apply the changes.\n\n* Available Blade Components are listed here: [laravel-trmnl-blade | Blade Components](https://github.com/bnussbau/laravel-trmnl-blade/tree/main/resources/views/components)\n\n#### 🎨 Blade View\n* Edit `resources/views/trmnl.blade.php`\n    * Available Blade Components are listed here: [laravel-trmnl-blade | Blade Components](https://github.com/bnussbau/laravel-trmnl-blade/tree/main/resources/views/components)\n* To generate the screen, run\n\n```bash\nphp artisan trmnl:screen:generate\n```\n\n#### Generate via API\nYou can dynamically update screens by sending a POST request.\n\n* Send a POST request to `/api/screen` with the following payload\n\n##### Header\n\n`Authorization` `Bearer \u003cTOKEN\u003e`\n\n##### Body\n\n```json\n{\n    \"markup\": \"\u003ch1\u003eHello World\u003c/h1\u003e\"\n}\n```\n\n### Releated Work\n* [bnussbau/laravel-trmnl-blade](https://github.com/bnussbau/laravel-trmnl-blade) – Blade Components on top of the TRMNL Design System\n* [bnussbau/trmnl-pipeline-php](https://github.com/bnussbau/trmnl-pipeline-php) – Browser Rendering and Image Conversion Pipeline with support for TRMNL Models API\n* [bnussbau/trmnl-recipe-catalog](https://github.com/bnussbau/trmnl-recipe-catalog) – A community-driven catalog of public repositories containing trmnlp-compatible recipes.\n\n\n### 🤝 Contribution\nContributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n\n### License\n[MIT](LICENSE.md)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fusetrmnl%2Fbyos_laravel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fusetrmnl%2Fbyos_laravel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fusetrmnl%2Fbyos_laravel/lists"}