Hugging Face's logo

Spaces:
Vvbbnnn
/
shell
Paused

App Files Community
shell
File size: 4,644 Bytes
5fd7a59
996891a
 
 
 
5fd7a59
 
 
 
996891a
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
---
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)
```