Tronbyt

Run a Tronbyt server as a toes app. Tronbyt is a self-hosted replacement for Tidbyt's cloud — it renders Starlark apps into WebP frames and pushes them to Tidbyt LED displays over your local network.

This app spawns the Tronbyt Go binary as a subprocess and proxies all traffic (HTTP + WebSocket) through Bun. The Go server handles everything — web dashboard, device connections, app rendering. Bun sits in front and makes it a good toes citizen.

Tidbyt device → tronbyt.toes.local → toes (port 80) → Bun (PORT) → Go binary (port 8000)

Install

1. Deploy to your toes server

git remote add toes http://git.toes.local/tronbyt
git push toes main

Pushing to the git remote deploys the app, runs bun install, and starts it automatically.

2. The binary

The Go binary auto-downloads from GitHub releases on first start if it's not already present. It's gitignored since it's platform-specific and ~50MB.

To download manually:

curl -L -o bin/tronbyt-server-linux-arm64 \
  https://github.com/tronbyt/server/releases/latest/download/tronbyt-server-linux-arm64
chmod +x bin/tronbyt-server-linux-arm64

3. First boot

On first start, the Go server clones the community Starlark apps repo into DATA_DIR/system-apps/. This can take a while on a Pi. With PRODUCTION=true (the default), it also downloads firmware for OTA device updates.

All data (SQLite DB, cloned apps, firmware) is stored in the app's DATA_DIR, which persists across restarts and deploys.

4. Create an account

Visit http://tronbyt.toes.local/auth/register to create your user account, then log in and click "New Tronbyt" to add a device.

Configure your Tidbyt

1. Flash your Tidbyt with Tronbyt firmware (see firmware flashing docs)
2. During device setup, set the Image URL to:

   http://tronbyt.toes.local/<device-id>/next
   

   The device ID is assigned when you add the device in the Tronbyt web dashboard.

Important: The Image URL must be the full path including /<device-id>/next — the device uses it exactly as-is.

Environment Variables

Set these through toes env tronbyt to override defaults:

Variable	Default	Description
PRODUCTION	true	Enables firmware downloads for OTA updates
SINGLE_USER_AUTO_LOGIN	true	Auto-login without password (good for home network)
SYSTEM_APPS_AUTO_REFRESH	true	Auto-refresh community apps repo every 12h

How the binary is managed

• On first start, src/binary.ts downloads the platform-appropriate binary (tronbyt-server-{darwin|linux}-{arm64|amd64}) into bin/
• The binary runs as a child process listening on TCP port 8000, with stdout/stderr inherited (logs show up in toes)
• src/proxy.ts forwards all HTTP and WebSocket traffic from the toes-assigned PORT to the Go binary on port 8000
• On shutdown (SIGTERM from toes), the app forwards SIGTERM to the Go process
• Health checks poll http://127.0.0.1:8000/health — the /ok endpoint reports "starting" until the Go server is ready

Troubleshooting

Add App page is empty (no community apps)

The Go server clones https://github.com/tronbyt/apps.git into DATA_DIR/system-apps/ on first boot. If that clone fails (network issue, permissions), you get 0 apps and the 12h auto-refresh won't fix a broken git state. Fix it manually:

cd /home/toes/data/toes/tronbyt/system-apps/
git fetch origin '+refs/heads/*:refs/remotes/origin/*'
git checkout -b main origin/main   # or: git reset --hard origin/main
chown -R toes:toes .                # must be owned by the toes user

Then restart tronbyt: POST http://toes.local/api/apps/tronbyt/restart, then POST http://toes.local/api/apps/tronbyt/start.

Go binary not starting

Check logs: sudo journalctl -u toes | grep tronbyt. Verify port 8000 is bound: ss -tlnp | grep 8000. The binary can take 30+ seconds to start when loading ~1000 community apps.

File permission errors

Everything under DATA_DIR must be owned by the toes user. Fix with sudo chown -R toes:toes /home/toes/data/toes/tronbyt/.