Kuroshiro is an open-source BYOS (Bring Your Own Server) solution for the TRMNL ecosystem. Our goal is to give you more flexibility and control over your TRMNL experience, whether you're self-hosting for fun, learning, or customization. Kuroshiro bundles a NestJS API and a Vue.js UI into a single Docker image, ready to run alongside your own Postgres database.
Heads up! Kuroshiro is still in alpha and not feature complete. Things are moving fast, and breaking changes may happen. Updates might require you to wipe your data and start fresh. Until we reach version 1.0.0, backward compatibility is not guaranteed. Please keep this in mind if you decide to try it out!
Kuroshiro is for anyone who wants to experiment, self-host, and shape their own TRMNL experience:
- Self-hosted: Your data, your rules, your server.
- All-in-one: API (NestJS) + UI (Vue 3 + Vuetify) bundled together.
- Plug & Play: Just add Postgres and go!
- Fun to use: Modern, intuitive, and built for tinkerers and pros alike.
- Auto Provisioning: Devices set up themselves—like magic!
- Device Management: Rename, reset, tweak refresh rates, and more.
- Live Device Insights: WiFi, battery, firmware, and real-time previews.
- Mirroring: See what's on your official TRMNL server, right here.
- Screens Galore: Add screens via link or upload, cache them, or fetch fresh every time.
- Virtual Device: Test without hardware—because why not?
Want to see Kuroshiro in action before diving in? We've got you covered! Check out our live demo at kuroshiro-demo.phyberapex.de where you can:
- Explore the interface - Navigate through device management, screen creation, and all the core features
- Test virtual devices - Play around with the virtual device feature to see how screens render
- Try screen creation -
Upload images(This is not supported in the demo), add external links, or craft custom HTML screens - See real-time updates - Watch how the system handles device communication and screen management
Note: The demo will reset once a day, so you can explore freely without worrying about breaking anything. It's the perfect playground to get a feel for Kuroshiro before setting up your own instance!
Kuroshiro is built on a modern, robust tech stack designed for performance, developer experience, and maintainability. Here's what powers the magic under the hood:
Why this foundation? We chose pnpm for lightning-fast package management and efficient monorepo handling. PostgreSQL gives us rock-solid data reliability with advanced features for complex queries. Docker ensures consistent deployments across any environment, and Vitest provides blazing-fast testing with excellent TypeScript support.
The backend powerhouse: NestJS brings enterprise-grade architecture with decorators, dependency injection, and built-in TypeScript support—perfect for building scalable APIs. TypeORM handles our database operations with elegant Active Record patterns and automatic migrations, making data management a breeze.
Frontend excellence: Vue 3 delivers reactive, component-based UI development with incredible performance and developer ergonomics. Vuetify provides beautiful Material Design components out of the box, ensuring a polished, accessible interface. Vite powers our build process with instant hot module replacement and optimized production builds.
We're constantly working to make Kuroshiro even better! Here's what's on our roadmap, organized by priority:
- Device Logs Viewer - View logs directly from your TRMNL devices for better debugging and monitoring
- Refresh Rate UI Controls - Adjust device refresh rates directly from the web interface
- Screen Management - Switch active screens and reorder them directly in the UI
- Liquid Template Syntax - Add Liquid templating support for dynamic HTML screens
- Maintenance Dashboard - Clean up unused images and manage disk space efficiently
- Recipes Support - Pre-built screen templates and configurations you can easily apply
- Screen Mashups - Combine multiple screens into custom layouts
- System Logs Viewer - Internal system logging and monitoring capabilities
- Smart Image Caching - Intelligent caching algorithms to optimize storage and performance
- Screen Playlists - Create playlists that cycle through multiple screens automatically
Want to contribute? Pick a feature from the roadmap and help us build it! Check out our contribution guidelines below.
Overview
Device Details
Virtual Device
HTML Preview
Kuroshiro is built for Docker. Just bring your own Postgres database and you're set!
We build these tags automatically:
| Tag | Content |
|---|---|
| next | Always build from the latest code changes in main |
| latest | The newest released version |
| x.x.x | Specific version that has been built and can be found in GitHub releases |
For local hacking or deployment inspiration, check out docker-compose.yml. It spins up everything you need—API, UI, and Postgres—so you can get started in seconds.
packages/api— The NestJS backendpackages/ui— The Vue 3 + Vuetify frontend
- Clone this repo
- Install dependencies:
pnpm install - Create a
.envfile (useenv.exampleand replace${MY_IP}) - Run Kuroshiro:
- With Docker:
docker-compose up(full local stack) - Or, start Postgres manually and run:
pnpm run dev
- With Docker:
If you enable mirroring and provide the MAC and apikey, Kuroshiro fetches the current screen (api/current_screen) from the official server—mirroring always takes priority. If the given MAC to mirror matches with the one of the device itself we are entering "proxy-mode" where we get the current display from the actual endpoint (display) and forward all the headers back and forth.
Screens can be added after your device fetches a screen at least once (so we know its size!).
Upload a file and Kuroshiro uses Imagemagick to fit, fill, and convert it to black and white. Stored locally, ready to go.
Provide a URL and Kuroshiro fetches, converts, and serves it. Cache it for speed, or fetch fresh every time—your choice!
Provide HTML you can make use of the TRMNL framework. You can use the tool "HTML Preview" to help generate HTML.
We love contributions! Jump in:
- Open issues or join discussions for bugs, ideas, or questions
- Fork, branch, and submit pull requests (PRs)—all PRs welcome!
- Please follow our Code of Conduct and code style
- Run all tests before submitting a PR
- We use release-please! Use Conventional Commits for your commit messages to enable automatic versioning and changelogs.