π οΈ Troubleshooting & FAQ β
Solutions to common configuration, network, and operational questions when setting up and running ShellGuard across desktop and mobile.
π 1. Mobile & Gateway Connectivity β
β Mobile App reports "Connection Refused" or cannot reach server β
- Symptom: When entering the gateway URL in ShellGuard Mobile, the screen reports
Failed to connect to gatewayor hangs indefinitely. - Root Cause: The mobile device cannot route to the configured address, or port
6464is blocked. - Resolution:
- Do not use
localhoston mobile: On an Android device or emulator,localhostpoints to the phone itself. Use your server's local subnet IP (e.g.http://192.168.1.100:6464) or your Tailscale hostname. - Verify Host Firewall: Ensure your host machine permits incoming TCP connections on port 6464:bash
# Ubuntu / Debian UFW sudo ufw allow 6464/tcp - Verify Docker Port Binding: Ensure
docker-compose.ymlbinds to0.0.0.0:6464(default in compose:- "6464:6464"). - Verify Health Endpoint from Device: Open Chrome on your phone and navigate to
http://<server-ip>:6464/api/health. You should receive a valid JSON status response.
- Do not use
β οΈ Unencrypted HTTP (http://) and Android Cleartext Traffic β
- Question: Does ShellGuard Mobile support connecting to homelab servers over unencrypted
http://? - Answer: Yes. Modern Android (API 28+) disables cleartext HTTP by default, but ShellGuard Mobile explicitly configures
<base-config cleartextTrafficPermitted="true" />and registersConnectionSpec.CLEARTEXTin its network engine. You can safely connect over local LAN subnets (192.168.x.x,10.x.x.x) or Tailscale WireGuard meshes (*.ts.net). - Visual Indicator: The mobile app displays an amber warning pill (
β οΈ Unencrypted HTTP) to ensure transport awareness. Even over plain HTTP, all vault item secrets remain sealed with client-side Layer 1 AES-GCM-256.
π 2. TLS Certificates, Invites & WebCrypto Origins β
π Browser warning: "Your connection is not private" (NET::ERR_CERT_AUTHORITY_INVALID) β
- Symptom: When visiting
https://<server-ip>:6565, Chrome or Firefox displays a full-page red security warning. - Root Cause: ShellGuard uses a self-signed EC P-256 certificate for local LAN transport encryption. Because it is not signed by a commercial public Certificate Authority (CA), browsers warn by default.
- Resolution:
- Trust on First Use (TOFU): Click Advanced β Proceed to [host] (unsafe). ShellGuard persists the certificate on disk (
DATA_DIR/certs/cert.pem), so you only need to accept this once per device. - Install Root Certificate: Log into SuperLobster at
/superlobsterβ Transport & Mobile Pairing β click Download Certificate (.pem). Install this.pemfile into your OS or browser's "Trusted Root Certification Authorities" store to permanently silence warnings across all local devices.
- Trust on First Use (TOFU): Click Advanced β Proceed to [host] (unsafe). ShellGuard persists the certificate on disk (
π« "This invite link is invalid or has already been used" β
- Symptom: Opening
/?invite=inv_...displays a red error banner and permanently locks the Hatch Identity button withINVITE LINK EXPIRED OR USED. - Root Cause: ShellGuard enforces atomic single-use invite burning:
- Once an identity is registered with an invite, the token is permanently deleted from SQLite (
api_tokens). - If the invite's Time-to-Live (TTL: 1h, 6h, 24h, 7d) has passed, the token is expired.
- Once an identity is registered with an invite, the token is permanently deleted from SQLite (
- Resolution: Request a fresh invite link or QR code from the instance operator via the SuperLobster Transport & Mobile Pairing tab.
π Why didn't certificate regeneration prompt me to accept the warning again? β
- Symptom: After clicking Regenerate Certificate in SuperLobster, refreshing the page loaded immediately without asking to re-accept the self-signed cert.
- Root Cause: Browsers cache active TLS socket connections via HTTP Keep-Alive. While the server immediately updates its in-memory context via
server.setSecureContext({ key, cert })and closes idle sockets, active browser tabs may hold lingering HTTP/2 or Keep-Alive tunnels. - Resolution: Open an Incognito window, perform a hard refresh (
Ctrl + Shift + RorCmd + Shift + R), or verify the new fingerprint in your browser's security inspector (Padlock icon β Connection is secure β Certificate viewer).
β οΈ Web Browser displays "WebCrypto requires secure origin" β
- Symptom: Features like in-browser SSH key generation or WebCrypto operations display a warning when accessing ShellGuard Web from another computer over
http://192.168.x.x:6565. - Root Cause: The W3C WebCrypto API (
crypto.subtle) is restricted by modern browsers strictly to Secure Contexts (https://orhttp://localhost). - Resolution:
- Run ShellGuard with
TLS_ENABLED=trueand access viahttps://<server-ip>:6565. See the First-Class HTTPS & TLS Guide. - Alternatively, place ShellGuard behind a reverse proxy terminating TLS (Caddy, Traefik, Cloudflare Tunnels). See the Reverse Proxy & TLS Guide.
- Run ShellGuard with
ποΈ 3. Identity, ClawKeys & Disaster Recovery β
β I lost my 67-character hu- master key. Can an admin reset it? β
- Answer: No. It is mathematically impossible.
- Why: ShellGuard is built on zero-knowledge cryptographic isolation. The server only holds
SHA-256(hu-)for login verification and never possesses the decryption key. Secrets are encrypted client-side using HKDF-derived keys. - Recovery Path: If you lose your
hu-key and yourshellguard_identity_<username>.jsonrecovery kit, your vault data cannot be recovered by anyone. Always store your recovery file on an offline USB drive or print an Emergency Sheet.
β "Invalid Key Format" Error during Login β
- Symptom: Submitting the key displays an invalid format error.
- Resolution:
- Ensure the key begins with the
hu-prefix (67 characters total). - Verify there are no leading or trailing whitespace characters.
- If you downloaded your
shellguard_identity_<username>.jsonfile, open it in a text editor and copy the exact value from the"token"field.
- Ensure the key begins with the
π 4. Mobile Sync & Offline Operation β
β³ Mobile App changes do not appear immediately on Web β
- Symptom: Items created on Android don't reflect on the web dashboard.
- Resolution:
- Check device connectivity: Pull down on the Vault Dashboard in ShellGuard Mobile to trigger an immediate manual synchronization.
- Verify sync status in Settings > Sync: The screen displays the timestamp of the last successful delta synchronization.
- Ensure ShellGuard Mobile has permission to run in the background (Android Settings > Apps > ShellGuard > Battery > Unrestricted).
π What happens if I edit the same item on Mobile and Web simultaneously? β
- Answer: ShellGuard uses Mutex-Serialized Delta Sync with Last-Write-Wins (LWW) conflict resolution based on server monotonic sequence timestamps. If both clients edit the same record offline, the most recent timestamp takes precedence. Previous password revisions are preserved in the item's password history drawer.
π³ 5. Docker & Server Operations β
β Docker container exits immediately on startup (Exit Code 1) β
- Symptom:
docker compose up -dstarts the container, but it immediately shuts down. - Diagnosis: Run
docker compose logs shellguardto inspect the startup trace. - Common Causes:
- Missing or Malformed
DB_ENCRYPTION_KEY: Must be a valid 32-byte Base64 string:bashopenssl rand -base64 32 - File Permissions on
./dataVolume: If the directory on the host was created with root ownership, the Node process cannot create the SQLite database:bashsudo chown -R 1000:1000 ./data
- Missing or Malformed
π How do I verify the server is healthy? β
- Run a curl check against the health endpoint:bashExpected output:
curl -k -s https://localhost:6565/api/health | jq .json{ "success": true, "service": "ShellGuard API", "version": "0.0.3.0", "mode": "sqlite", "uptime": 45.2, "counts": { "vaultPearls": 1, "secureNotes": 0, "sshKeys": 0, "attachments": 0, "agentKeys": 0 } }
π Still Need Help? β
- π¬ GitHub Discussions: github.com/clawstackstudios/shellguard/discussions
- π Issue Tracker: github.com/clawstackstudios/shellguard/issues
- π Lexicon & Terminology: ClawStack Lexicon (Glossary)