title: Shellular Web UI
emoji: 🖥️
colorFrom: blue
colorTo: indigo
sdk: docker
pinned: false
Shellular Web UI
A self-hosted web interface that runs Shellular inside a Hugging Face Space and shows the pairing QR code in your browser — no terminal access needed.
What it does
- Password-protected login page hosted on your HF Space URL
- Starts Shellular automatically after login and renders a scannable QR code
- All traffic between your phone and the host is end-to-end encrypted (libsodium)
- One-time setup panel guides you through saving permanent secrets so restarts are instant
Architecture
Your Phone ──scan QR──▶ Shellular App
│
wss://api.shellular.dev (relay, E2E encrypted)
│
HF Space
(Node.js + Shellular CLI)
Quick Start
Step 1 — Fork the Space
Click Duplicate this Space on the top-right of this Space page.
Step 2 — Add SECRET_KEY
Go to your forked Space → Settings → Variables and secrets → New secret
| Name | Value |
|---|---|
SECRET_KEY |
Any strong password — this is the login password for the web UI |
The Space will restart automatically.
Step 3 — Login
Open your Space URL (https://your-username-vps.hf.space), enter your SECRET_KEY and click Login.
Shellular starts automatically. Within a few seconds the QR code appears.
Step 4 — Scan the QR code
Install the Shellular app on your phone → shellular.dev
Open the app and scan the QR code on the dashboard. Your phone is now connected.
Step 5 — Save the permanent secrets (important!)
After the QR code appears, a ⚡ One-time Setup panel appears showing three values with Copy buttons.
Add all three as secrets in your Space settings:
Space → Settings → Variables and secrets → New secret
| Secret name | Where to get it |
|---|---|
SHELLULAR_HOST_ID |
Copy from the One-time Setup panel |
SHELLULAR_MACHINE_ID |
Copy from the One-time Setup panel |
SHELLULAR_KEY |
Copy from the One-time Setup panel |
After adding all three, restart the Space. The setup panel disappears permanently.
Why are these needed? Shellular calls
api.shellular.devto register on every cold start. That API is rate-limited — if the Space restarts too often, registration fails and the QR never appears. Saving these three values means Shellular reuses the same registered identity on every restart with no API call at all.
All Secrets Reference
| Name | Required | Description |
|---|---|---|
SECRET_KEY |
✅ Always | Login password for the web UI. Choose anything strong. |
SHELLULAR_HOST_ID |
⭐ Strongly recommended | The relay server's ID for this host. Shown in the One-time Setup panel. |
SHELLULAR_MACHINE_ID |
⭐ Strongly recommended | Hashed machine identifier tied to the registration. Shown in the One-time Setup panel. |
SHELLULAR_KEY |
⭐ Strongly recommended | 32-byte base64 E2E encryption key. Shown in the One-time Setup panel. |
Troubleshooting
QR code doesn't appear / "Shellular stopped"
The Shellular registration API was rate-limited.
Fix: Save the three SHELLULAR_* secrets from the One-time Setup panel (Step 5). Once saved, Shellular skips registration on every restart — no rate limit, instant QR.
If you have not yet seen the One-time Setup panel (e.g. the first registration also failed), wait a few minutes and click ▶ Restart on the dashboard to try again.
"Invalid key" on login
SECRET_KEY is not set or was typed incorrectly. Check Settings → Variables and secrets.
One-time Setup panel not appearing
The panel only appears after the QR code is successfully rendered for the first time AND the SHELLULAR_* secrets are not yet saved. If the QR rendered but the panel did not appear, refresh the page and log in again.
Project Structure
├── app.js # Express server — auth, SSE, shellular lifecycle
├── package.json
├── Dockerfile # Node 20-slim, pinned machine-id for stable registration
└── public/
├── index.html # Login page + dashboard (QR, One-time Setup, Output log)
├── style.css # Dark theme
├── app.js # Frontend JS
└── qrcode.min.js # Bundled QR renderer (no CDN dependency)