---
title: Shellular Web UI
emoji: 🖥️
colorFrom: blue
colorTo: indigo
sdk: docker
pinned: false
---

# Shellular Web UI

A self-hosted web interface that runs **[Shellular](https://shellular.dev)** 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](https://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.dev` to 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)
```