Skip to content

Releases

kuroshiro: v0.25.0

Choose a tag to compare

@PhyberApex PhyberApex released this 16 Nov 16:02
1bec268

0.25.0 (2026-11-15)

⚠ BREAKING CHANGES

  • ui: a bare deviceId no longer names the owner of a new Screen; send owner: { kind, id }. DeviceGroupMember.deviceModelName and paletteName are now deviceModel and palette.
  • api: Device Groups own a Screen set their members each walk at their own pace (#1798)

Features

  • api: a Plugin Screen reads its own Device's Sensors (#1787) (aa921be)
  • api: Device Groups own a Screen set their members each walk at their own pace (#1798) (7b77072), closes #1793
  • api: dither image-dither elements on an undithered Screen (#1788) (9541366)
  • list TRMNL's released Framework versions in the Plugin's field (#1790) (bf7a8fa)
  • ui: Device Groups list and page, and a grouped Device shows its Group's Screens (#1799) (920421e)
  • ui: show when an active Alert was last reminded (#1789) (4c1f8e6)

Performance Improvements

  • ci: cache the image layers both Docker builds share (#1780) (893de9f)

kuroshiro: v0.24.0

Choose a tag to compare

@PhyberApex PhyberApex released this 14 Nov 14:07
8fb2d8e

0.24.0 (2026-11-14)

⚠ BREAKING CHANGES

  • api: a Template pointing a render page at a private address stops drawing until that host is named in KUROSHIRO_RENDER_ALLOWED_HOSTS.
  • api: crypto.subtle is no longer in a transform's reach. A transform that names it now fails where it used to run. Nothing else of ADR-0055's nineteen globals is withdrawn.

Features

  • api: build a transform's web globals inside its sandbox (#1777) (bdaf015), closes #1750
  • api: refuse a private host on a render page unless an admin named it (#1778) (36f7211), closes #1776

kuroshiro: v0.23.1

Choose a tag to compare

@PhyberApex PhyberApex released this 13 Nov 21:48
6d5ee99

0.23.1 (2026-11-13)

Bug Fixes

  • docs: name usetrmnl/kuroshiro as the repository, image and site source (b92f268)

kuroshiro: v0.23.0

Choose a tag to compare

@PhyberApex PhyberApex released this 11 Nov 09:59
3bbccfb

0.23.0 (2026-11-11)

⚠ BREAKING CHANGES

  • docker: the image now runs as node (uid 1000). An install whose volumes or bind mounts were written by the previous (root) image stops at first start with cannot write to /app/public/…. Start it once as root (--user 0, compose user: "0"), and the entrypoint hands the files to node and drops privileges; or run docker run --rm -v <volume>:/data alpine chown -R 1000:1000 /data per volume (for a bind mount, chown -R 1000:1000 <host dir>). Images built on this one that need root, such as the Home Assistant add-on, must add USER root after FROM. See "Running unprivileged" in the README.

Features

  • the Recipe Gallery, browsing trmnl.com's published Recipes in the admin UI (#1754) (4ad5d2d)

Bug Fixes

  • api: guard render page requests and turn web security back on (#1753) (fbeccb1)
  • api: redact Webhook Tokens from the request log and compare Device API keys in constant time (#1762) (81395b1)
  • api: refuse an /api/setup ID that is not a MAC address (#1760) (461562e)
  • api: refuse cross-site state-changing requests to the admin API (#1756) (28c9c63)
  • api: refuse NAT64, 6to4, reserved, benchmarking and multicast ranges in the demo SSRF guard (#1761) (13845fd)
  • api: serve the admin UI with frame-ancestors and basic security headers (#1763) (e0c8cfe)
  • api: validate Configuration Archive entries, so a Palette id cannot path-traverse the colormap write (#1759) (b595013)
  • deps: resolve patched body-parser, qs, zod, fast-uri and source-map-js (#1736) (7d59f8c)
  • docker: run the image as an unprivileged user, and Chromium sandboxed where the container lets it (#1757) (658984c)
  • shared: set liquidjs parse, render and memory limits so a template cannot freeze the API (#1758) (6eb9542)

kuroshiro: v0.22.0

Choose a tag to compare

@PhyberApex PhyberApex released this 31 Oct 09:11
4f43fc0

0.22.0 (2026-10-31)

Features

  • api: add GET /health probe reporting process and database status (#1576) (dc07f73)
  • firmware: sync official Firmware from TRMNL's per-model firmware feed (#1578) (05946a1)

Bug Fixes

  • api: answer 400 naming the header when a Device request has no ID header (#1679) (87c16dd)
  • api: bound a firmware binary download by a timeout and the firmware upload ceiling (#1642) (5df5830)
  • api: cap Data Source, transform fetch and OAuth token response bodies at 5 MB (#1626) (4530114)
  • api: carry snapshotTakenAt and a File Screen's upload facts through the Configuration Archive (#1689) (b454fd1)
  • api: change the filename sent to the Device when an HTML Screen's markup or Dithering changes (#1630) (efd340e)
  • api: check every redirect and resolved address against the demo-mode SSRF guard (#1624) (001c475)
  • api: connect a demo-mode request to the address the SSRF guard checked, closing the DNS rebinding window (#1690) (05a6e2f)
  • api: convert with a custom Palette's new colours once they change (#1673) (509483b)
  • api: count a multi-line Data Source with a failed line as a failed fetch (#1625) (e4e145e)
  • api: count a Sleep Mode refresh_rate in elapsed seconds across a DST change (#1635) (ff571da)
  • api: fetch External link and mirror images with the demo-mode guard on /display (#1631) (9cb7e92)
  • api: find a Device by its MAC whatever letter case it sends to /api/setup and the polls (#1676) (ecf59b7)
  • api: hold a Schedule window that crosses midnight to the weekday and date it starts on (#1678) (e6dd939)
  • api: keep a Device's API key out of the /display, /current_screen and /setup logs (#1677) (5ef7675)
  • api: keep a Device's one-shot commands when its /display answer cannot be made (#1633) (3f0996a)
  • api: keep a Plugin's Screen modifiers through a Configuration Archive import (#1637) (252a9c2)
  • api: keep Plugin Field order and null defaults through a .trmnlp export and a Configuration Archive (#1682) (4c42561)
  • api: let a Configuration Archive import clear an existing Device's Mirroring and a Plugin's Recipe id (#1638) (d594fa3), closes #1599
  • api: load a Plugin's Fields on every render path (#1623) (5584d0b)
  • api: mark an Alert notified on open while Apprise is unconfigured (#1639) (00015cf)
  • api: reach back a day on the clock for an Offline Alert's last Sleep Mode window end (#1641) (e7f576b)
  • api: read and pick an HTML Screen without its stale stored Render Signal, as Rotation does (#1681) (28c4d8d)
  • api: recognise a Proxied Device whatever letter case its MAC was registered in (#1636) (0739dad)
  • api: redraw a Device's HTML, Plugin and Mashup Screens when its Palette or Device Model changes (#1675) (b845341)
  • api: refuse an archive or .trmnlp whose zip entries unpack past the upload ceiling, before reading any (#1684) (3628d4d)
  • api: refuse Data Source methods other than GET/POST and keep one Template per size on Plugin import (#1627) (fafaae8)
  • api: render a Webhook POST with its own payloadReceivedAt, so data_fetched_utc is not one POST behind (#1688) (872cb98)
  • api: require the Device's Access-Token on POST /api/log and check duplicate entries in the database (#1634) (2088bbf)
  • api: run a transform on a worker thread its timeout terminates (#1604) (207df70)
  • api: send a Proxied Device's mirror poll to TRMNL with one ID header (#1629) (68e99a5)
  • api: serialise webhook POSTs per Plugin so concurrent merges keep every payload (#1620) (f478451)
  • api: stop LoggingInterceptor logging every admin response body (#1640) (1378491)
  • api: write only a polling Device's report, so an admin's edit made during the poll survives (#1680) (c726994)
  • docker: install Corepack before enabling it, node 26 images no longer bundle it (#1581) (141c486)
  • shared: render a missing value through the json filter as null, as TRMNL's to_json does (#1691) (124a7dd)
  • shared: render nothing, not "undefined", when l_date or ordinalize gets a missing value (#1628) (044b472)
  • ui: add one HTML Screen when Ctrl/Cmd+S is pressed again before the first answer (#1651) ([56f75d4](https://github.c...
Read more

kuroshiro: v0.21.0

Choose a tag to compare

@PhyberApex PhyberApex released this 23 Oct 12:53
914ec13

0.21.0 (2026-10-22)

Features

  • alerts: remind Alerts still open on a Reminder Interval (#1490) (3663e01)
  • devices: Manual Rotation, a per-Device setting that advances only on a button press or a Picked Screen (#1482) (11b1601)
  • devices: record the Update-Source header as the Device's last wake source (#1479) (0b55aa0)
  • Dithering switch on Screens and Plugins (#1477) (ce139b3)
  • firmware: "Catch up now" gives the current official Firmware to Devices that are behind (#1475) (b07ac88)
  • firmware: official Firmware is synced once per folder of TRMNL's firmware bucket (#1547) (226aac5)
  • mashup: a Mashup slot raises its own Render Signal (#1551) (8a975d0)
  • plugins: a bare select option is stored under the value TRMNL derives (#1539) (82e1080), closes #1530
  • plugins: a copyable_webhook_url Plugin Field is not an input to fill in (#1543) (246bf1d), closes #1532
  • plugins: a Data Source request is given up after ten seconds (#1541) (4b46920), closes #1535
  • plugins: a Data Source requests each line its URL renders to, and a lone list or text reads as data (#1528) (f112195), closes #1522
  • plugins: a list Plugin Field holds one value per line and reads as a list (#1546) (e653c7e)
  • plugins: a Plugin Field keeps the attributes TRMNL's form builder gives it (#1515) (9a055fb)
  • plugins: a Plugin is rendered once per Screen and told its Device as trmnl.device (#1554) (f7578f9)
  • plugins: a polled iCalendar feed is read as its next thirty days of events (#1548) (d8bf75c)
  • plugins: a polled XML feed and CSV table are read as TRMNL reads them (#1529) (be989b0)
  • plugins: a Template defines its own partials, and a Recipe's shared.liquid tops every layout (#1511) (49c1f75)
  • plugins: a transform keeps Saved State and may fetch (#1514) (1c79685)
  • plugins: a transform reads its Previous Output as trmnl.previous_merge_variables (#1555) (c192a69)
  • plugins: a transform's sandbox has Node's web globals (#1524) (b0bb7c3), closes #1519
  • plugins: a Webhook POST in TRMNL's merge_variables envelope is read as the payload (#1544) (1d5ba69), closes #1533
  • plugins: a webhook Recipe imports as a Webhook Plugin (#1526) (d65f7d2)
  • plugins: an OAuth Recipe imports with a token the admin pastes, refreshed before a poll (#1552) (03a835b)
  • plugins: each line of a Polling URL reads a list or text under data (#1540) (0862926), closes #1531
  • plugins: keep TRMNL's no_screen_padding and dark_mode and draw a Plugin's own Screen with them (#1516) (a854647)
  • plugins: polling_headers in TRMNL's key=value form are read on import (#1542) (80eb118), closes #1534
  • plugins: read a lone Data Source at the root of the context too (#1510) (8d23e04)
  • plugins: run a transform as TRMNL's serverless run(input) (#1513) (11e4fb7)
  • plugins: the template reads when its data was fetched as trmnl.plugin_settings.data_fetched_utc (#1525) (244a7c8), closes #1521
  • shared: TRMNL's custom Liquid filters, so an imported Recipe that uses one renders as on trmnl.com (#1447) (ce5cce5)
  • Wipe, a one-shot blank-image command on a Device (#1481) (5c3634d)

Bug Fixes

  • api: map current firmware board names to their upstream Device Models (#1473) (25671cc)
  • metrics: accept the unit spellings official firmware sends for Sensors (#1484) (f8dbc0a)
  • plugins: import the Recipe archives TRMNL ships today (#1508) (9d47cbf)
  • shared: make the Liquid engine's standard filters follow Ruby Liquid (#1446) (20df7b5)
  • shared: render Liquid dates in the Instance Time Zone and carry it on trmnl.user (#1449) (8274c44)
  • ui: keep the Template plate in its rendering state until the Instance Time Zone is in (#1453) (a80b654)

Performance Improvements

Read more

kuroshiro: v0.20.0

Choose a tag to compare

@PhyberApex PhyberApex released this 15 Oct 16:15
42b8971

0.20.0 (2026-10-15)

Features

  • alerts: batch Alert Sweep Notifications into one digest per Sweep (#1415) (642d006), closes #1383
  • api: carry a Plugin's Framework Version through import, export and archive (#1438) (fc69068)
  • configuration: seed a showcase Configuration Archive on an empty demo-mode boot (#1417) (cda54bb), closes #1384
  • plugins: give a Plugin its own Framework Version (#1433) (509696b)
  • ui: "Show next" and "Back to Order" on a Device's Screen rows (#1414) (50aed7b)
  • ui: add a Plugin's own Framework Version field and draw the preview with it (#1439) (ac6313f)
  • ui: add the Sleep image row to Device Settings (#1430) (8a88ad1)

kuroshiro: v0.19.0

Choose a tag to compare

@PhyberApex PhyberApex released this 11 Oct 18:26
6d41e28

0.19.0 (2026-10-11)

Features

  • api,ci: make the Alert Sweep schedule configurable, speed up the real-API CI journey (#1370) (62972fd), closes #1270
  • api,ui,shared: reshape AlertSummary's subject keys to null references (#1399) (df0cef3)
  • api,ui: regenerate a Device's API key now, and stop Configuration Import from reviving an old one (#1408) (a1e4821)
  • api: let a Device Reset also give the Device a new API key (#1409) (de3e684), closes #1362
  • api: set, clear and serve a Device's Picked Screen in Rotation (#1413) (b60e215)
  • api: store, serve and reconvert a per-Device sleep image (#1403) (b5d2a66)
  • config: carry each Device's own sleep image in the Configuration Archive (#1405) (6be619a)
  • shared: pin the TRMNL framework to an exact version per Instance (#1407) (6175414)
  • ui: clear a select or on/off Field Value back to its default (#1385) (8084f71)
  • ui: tilt the Active Screen's seal 4 degrees askew on the Plate (#1391) (2913081)

Bug Fixes

  • api,ui: carry image-fetch-failed's reason in details, not a parsed message (#1347) (fd2b55f)
  • api,ui: read a Device's deleted Active Screen as deletedScreen, not noScreens (#1372) (a22dc29)
  • api: cap GitHub/Recipe import and External link image downloads (#1369) (0d15aea), closes #1269
  • api: name a Plugin Screen after its Plugin when it is the Current Screen (#1402) (77fffc2), closes #1334
  • api: run migrations exactly once, before any module touches the database (#1400) (974108c)
  • configuration: refuse an Instance Settings archive entry outside SETTING_BOUNDS (#1348) (0e6785b)
  • maintenance: find and clean up stale Fallback Screen renders (#1371) (183427d)
  • ui: add a hook timeout to the browser project's coverage runs (#1393) (a747957)
  • ui: ask before dropping an unsaved Palette or Add Screen form (#1380) (7089775)
  • ui: drag a Screen or Plugin Field row by its grip in Firefox (#1378) (4b93690)
  • ui: keep the Plugin page's Devices section from going bare while Devices load or fail (#1389) (6e7b7ce)
  • ui: mark a custom Palette "· custom" in a Device Model's row (#1386) (e6bee50)
  • ui: reach a relative time's exact time by keyboard and touch (#1374) (2f727d4)
  • ui: report a Plugin or Configuration Archive export's failure (#1381) (63ac075), closes #1279
  • ui: say a failed TRMNL sync check failed, not that it checked (#1387) (c522b29), closes #1283
  • ui: say an unassigned Webhook-kind Plugin keeps its Webhook URL (#1382) (8532cd8), closes #1280
  • ui: settle nine admin UI spec/glossary/code contradictions (#1390) (a8ea4a2)
  • ui: show a failed-load notice when the code editor's chunk cannot be fetched (#1377) (7dc897d)
  • ui: stop two UI specs racing real wall-clock time under coverage (#1404) (1b16668), closes #1359
  • ui: widen the weekday toggle's touch target to 44 px square (#1376) (7cd920f), closes #1275

kuroshiro: v0.18.0

Choose a tag to compare

@PhyberApex PhyberApex released this 09 Oct 12:49
468a70c

The admin UI is rebuilt. 0.18.0 replaces the Vuetify admin UI with a new one at the same address, and reworks most of the admin API underneath it. Devices keep polling as before.

Before you upgrade:

  1. Back up the database. Several migrations delete or rewrite data and their down does not bring it back. 0.17.x cannot import an archive exported by 0.18.0, so the database backup is your only way back to 0.17.x.
  2. Run the pre-upgrade queries below (duplicate Templates, and the four uniqueness checks) to see what the migrations will delete, rename or renumber.
  3. Mount /app/public/firmware if you use Firmware (see "Persisting Firmware binaries" below), and copy the binaries out of the running container before you recreate it.

Instances that run :latest with an auto-updater (Watchtower, Ouroboros, …) pick up 0.18.0, migrations included, on their own. Do the steps above first.

Security

  • A Template could read files from the server (GHSA-4w55-w6pj-8rhq, also fixed in 0.17.2). Up to and including 0.17.1, {% render %}, {% include %} and {% layout %} in a Template rendered files from the server's working directory (in the Docker image /app; outside Docker this can include a .env file). Kuroshiro now has no partials, and such a tag fails the render with A template cannot render "x": Kuroshiro has no partials. A Template that relied on it stops rendering (#1241, #1295).
  • Housekeeping's cleanup only deletes inside its two folders. POST /api/maintenance/cleanup accepted any absolute path that merely contained uploads or public/screens/devices, so one request could delete files elsewhere the server could write. A path now has to resolve inside the devices or the uploads folder (#1115).
  • Password Field Values no longer leak in fetch errors or after a retype. A failed scheduled fetch stored, showed and logged its error with a password Field Value in plain text; it is now hidden everywhere and the server log names only the Data Source (#1323). Retyping a password Plugin Field to another type now drops its stored value instead of answering it in plain text (#1324).

The admin UI is new

  • The Vuetify admin UI is gone; the rebuilt one replaces it at the same address, also under a Home Assistant ingress prefix (#1255). Page addresses changed, so old bookmarks to pages (e.g. the "Maintenance" page, now Instance → Housekeeping) land on the new UI's "not found".
  • The static Fallback Screen images moved from the UI package to packages/api/assets/screens; the Docker image still serves them at /screens/{error,noScreen,sleep,welcome}.png. Installs built from source must run the API's copy step (#1216).

New

  • Instance Settings: the three Alert Rule thresholds and the two Retention ages can be set in the UI (Instance → Instance Settings). A saved value wins; clearing it falls back to the KUROSHIRO_ALERT_* / KUROSHIRO_*_RETENTION_DAYS variable, else the built-in default. Instance Settings travel in the Configuration Archive (#1051, #1202).
  • Firmware Auto-Update, an Instance Setting, off by default: each newly synced official Firmware becomes the target of every eligible Device (not mirrored, no push pending, compatible Device Model). It never replaces a pending assignment, never assigns custom Firmware, and acts from the next new official version on (#1056). A pending Firmware push and a pending Device Reset can now be cancelled from Device Settings (#1311, #1313).
  • Redacted Archive: Configuration Export can replace every secret (Data Source header values, Device API keys and mirror API keys, password Field Values, Webhook Tokens) with a placeholder (GET /api/config/export?redact=true). Importing one keeps the target's existing secret, or falls back with a warning (#1055).
  • Recipe Update Check: a Plugin imported from a Recipe keeps a Recipe Snapshot and can check its Recipe for changes, then apply only the Update Items you pick (GET /api/plugins/:id/recipe-update, POST /api/plugins/:id/recipe-update/apply). A Plugin imported before this release has no Recipe Snapshot, so its first check lists every difference from the Recipe, your own edits included, and applying one replaces your version; "Apply nothing and save the Recipe Snapshot" records the baseline without changing the Plugin (#1057, #1058, #1249). A Recipe with strategy: none now imports as a Poll-kind Plugin with no Data Sources (#1326).
  • Render Signals: a plugin, html or Mashup Screen whose page sets window.TRMNL_SKIP_DISPLAY is passed over in Rotation for that poll (skip); one that sets window.TRMNL_SKIP_SCREEN_GENERATION keeps showing its previous image (hold) (#1310, #1315).
  • Device preview: the Template editor and Edit HTML can draw the preview as the Device would show it, dithered to its Device Model and Palette through the same path as /display ("See it as … shows it"). One preview renders at a time per Instance (POST /api/device-preview, #1342).
  • Device Simulator (Instance → Device Simulator) makes the firmware's setup and /display calls from the browser for troubleshooting. Its calls are real: an unknown MAC registers a Device, and a poll advances that Device's Rotation and consumes anything pending for it (#1247).
  • /metrics gains one gauge per Device Sensor kind (kuroshiro_device_sensor_temperature_celsius, …_humidity_percent, …_pressure_hpa, …_carbon_dioxide_ppm) and kuroshiro_data_source_fetch_failure_streak per fetch-mode Data Source (#1309).

Persisting Firmware binaries

Firmware binaries (uploaded custom Firmware and the synced official one) are written to /app/public/firmware, which was not in the documented volume, so recreating the container lost them. The daily sync does not download a version it already recorded, so a lost official binary stays lost (Devices targeting it get a 404) until the next official release. Mount it next to the Device images (#1300; see "Persisting data" in the README):

services:
  app:
    volumes:
      - kuroshiro_data:/app/public/screens/devices
      - kuroshiro_firmware:/app/public/firmware
volumes:
  kuroshiro_data:
  kuroshiro_firmware:

A new volume starts empty. To keep the binaries you have, copy them out of the running container before upgrading (docker cp <container>:/app/public/firmware ./firmware) and back into the new one afterwards.

The API now also logs a warning at startup for every KUROSHIRO_* variable it does not read, naming the replacement for old names (KUROSHIRO_POSTGRES_* → KUROSHIRO_DB_*, KUROSHIRO_API_PORT → KUROSHIRO_PORT). Such a variable was always ignored; the warning only makes it visible (#1300).

Before you upgrade: migrations that delete or rewrite data

Run these queries against the database before upgrading to see what the migrations will change. Each one returns no rows (or 0) when that migration has nothing to fix.

  • Duplicate Templates are deleted (#1212, migration 1787250000000-OneTemplatePerSize). A Plugin keeps one Template per size. A Plugin without a full Template has its earliest Template made full; every later Template of a size the Plugin already has is deleted for good ("earliest" is the table's row order). To count what would be deleted:
    SELECT COUNT(*) FROM "plugin_template" later
    WHERE EXISTS (
      SELECT 1 FROM "plugin_template" earlier
      WHERE earlier."pluginId" = later."pluginId"
        AND earlier."layout" = later."layout"
        AND earlier."ctid" < later."ctid"
    );
  • Four "only one of" rules become database constraints (#1330, migration 1787280000000-UniqueAssignmentFirmwarePaletteOrder). Duplicates only a race could have created are resolved first, and each change is logged at startup:
    • Plugin Assignment per Plugin and Device: the Assignment whose Screen comes first in the Order is kept; the others are deleted with their Screens and those Screens' images, and the Order is closed up.
    • Firmware per version: a custom Firmware is kept over an official one, then the earliest; Devices targeting a dropped row are moved to the kept one. The dropped row's file stays on disk.
    • Custom Palette name (case-insensitive): later same-named Palettes are renamed <name> (2), (3), …
    • Screen Order per Device: an affected Device's Screens are renumbered 1..N in their current order.
    -- Plugin Assignm...
Read more

kuroshiro: v0.17.2

Choose a tag to compare

@PhyberApex PhyberApex released this 05 Oct 06:21
38e912e

0.17.2 (2026-10-05)

Bug Fixes

  • api: refuse Liquid partials so a Template cannot read files from the server (#1295) (0394f5a), closes #1260