@tovex/toast

One-command Raspberry Pi web terminal deployment with Cloudflare Tunnel.

Each run auto-assigns the next available tov-sysN name, deploys a full web terminal platform, and registers the device in a live fleet registry.

What it does

1. Auto-names the device tov-sys1, tov-sys2, … (queries Cloudflare for existing tunnels)
2. Creates a Cloudflare Tunnel and configures ingress to the local web terminal
3. Sets DNS — tov-sysN.yourdomain.com as a proxied CNAME
4. Deploys the device registry at tov.yourdomain.com (Cloudflare Worker + KV)
5. Builds and installs rpi-webterm — Node.js + Express + Socket.IO + node-pty + React + xterm.js
6. Installs systemd services for both the web terminal and cloudflared
7. Registers the device in KV so it immediately appears on tov.yourdomain.com

Usage

# Interactive — prompts for Cloudflare credentials and admin password
sudo npx @tovex/toast

# Non-interactive (CI / headless)
sudo CF_API_TOKEN=xxx CF_ACCOUNT_ID=xxx CF_ZONE=yourdomain.com \
     ADMIN_USER=admin ADMIN_PASS=yourpassword \
     npx @tovex/toast

# With a custom working directory
sudo npx @tovex/toast /opt/webterm

Credentials via GitHub (optional, zero-prompt)

If the GitHub CLI (gh) is installed and authenticated on the machine, the installer automatically fetches the Cloudflare credentials (CF_API_TOKEN, CF_ACCOUNT_ID, CF_ZONE) from a private GitHub repo — no manual paste needed. Access is gated by GitHub auth: only authenticated accounts with read access to the private repo can retrieve them.

# Default repo / file (override with env vars):
GH_SECRETS_REPO=Bibin-VR/tovex-secrets
GH_SECRETS_FILE=tov-cloudflare.env

The file is a plain .env:

CF_API_TOKEN=cfut_...
CF_ACCOUNT_ID=...
CF_ZONE=yourdomain.com

Precedence: explicit environment variables → GitHub repo → interactive prompt. Set SKIP_GH_CREDS=1 to always prompt instead. On a fresh machine, run gh auth login first (and ensure that account has read access to the repo).

Required Cloudflare API token permissions

Create at dash.cloudflare.com → My Profile → API Tokens → Create Custom Token:

| Permission | Level | |-------------------------|-------| | Cloudflare Tunnel | Edit | | DNS | Edit | | Workers Scripts | Edit | | Workers KV Storage | Edit | | Account Settings | Read |

Set Account resources to your account and Zone resources to your domain.

After install

| URL | Purpose | |-----|---------| | https://tov-sysN.yourdomain.com | Web terminal for this device | | https://tov.yourdomain.com | Fleet registry (all devices) |

Included stack

Backend · Node.js · Express · Socket.IO · node-pty · better-sqlite3
Frontend · React · xterm.js · Tailwind CSS
Auth · bcrypt · express-session · CSRF tokens · RBAC (admin/viewer)
Security · Helmet · CSP · HSTS · host-guard · rate limiting · account lockout
Infra · Cloudflare Tunnel · systemd

License

MIT