5-Minute Quickstart β
Get your sovereign ShellGuard reef up and running in minutes using Docker Compose or Node.js.
π³ Option A: Docker Compose (Recommended) β
ShellGuard compiles into a single multi-stage container (node:20-alpine) running the Vite-built React UI and Express 5 API on port :6464.
Step 1: Configure & Generate Keys β
Create a directory for your deployment:
bashmkdir -p shellguard && cd shellguardGenerate the master database encryption key and SuperLobster admin token:
bash# Generate 256-bit DB Encryption Key (Layer 2 metadata & Layer 3 SQLCipher) openssl rand -base64 32 # Generate SuperLobster Admin Token openssl rand -hex 24Create
docker-compose.yml:yamlservices: shellguard: image: ghcr.io/clawstackstudios/shellguard:latest container_name: shellguard restart: unless-stopped ports: - "6464:6464" volumes: - ./data:/app/data environment: - NODE_ENV=production - PORT=6464 - DATA_DIR=/app/data - DB_ENCRYPTION_KEY=your_generated_base64_key_here - ADMIN_TOKEN=your_generated_admin_token_here healthcheck: test: ["CMD", "wget", "-qO-", "http://localhost:6464/api/health"] interval: 15s timeout: 10s retries: 5 start_period: 15s
Step 2: Start & Verify the Container β
Launch the unified container stack in detached mode:
bashdocker compose up -d --waitVerify that the server is healthy and the database is initialized:
bashcurl -k https://localhost:6565/api/health # {"success":true,"service":"ShellGuard API","version":"0.0.3.0","mode":"sqlite","uptime":14.2,"counts":{"vaultPearls":0,"secureNotes":0,"sshKeys":0,"attachments":0,"agentKeys":0}}
Step 3: Launch Vault & Genesis User #1 Hatching β
- Open https://localhost:6565 (or your LAN IP
https://192.168.1.x:6565) in your web browser. - Accept Self-Signed Certificate: On your first visit, your browser will present a security notice. Click Advanced β Proceed to localhost (unsafe). ShellGuard's persistent self-signed certificate pins trust (TOFU) across restarts without recurring warnings.
- Hatch Genesis Identity: Click Hatch Vault to generate your sovereign 67-character
hu-master ClawKey.NOTE
Genesis User #1 Immunity: Even if your server is configured with
DISABLE_SIGNUPS=true, the first user to hatch on a fresh database is unconditionally permitted to register. Once User #1 exists, the gateway automatically locks down to invite-only mode. - Download and securely store your identity recovery JSON kit. There are no central passwords, reset emails, or account recovery links.
- Enter your vault dashboard (The Grotto) to begin storing secrets and issuing agent delegation keys.
TIP
Connecting from ShellGuard Mobile: Open SuperLobster at https://localhost:6565/superlobster, navigate to Transport & Mobile Pairing, and scan the on-screen QR code with ShellGuard Mobile or ShellGuard-TOTP to establish instant, auto-healing trust. Ensure your host firewall allows inbound TCP traffic on port 6565.
π» Option B: Local Node.js Development β
If you are developing features or contributing to ShellGuard:
1. Prerequisites β
- Node.js: v20+ (Node v22.23.0 recommended)
- C/C++ Build Toolchain: Required for
better-sqlite3-multiple-ciphersnative bindings (build-essential,python3,make,g++).
2. Install Dependencies β
npm install
cp .env.example .env3. Start Development Servers β
npm run scuttle:dev-start- Frontend (Vite + HMR): http://localhost:6464
- Backend (Express API): http://localhost:6565 (proxied via Vite
/api)
π Useful Scuttle Commands β
# Gracefully stop running dev servers
npm run scuttle:dev-stop
# Wipe development database (data-dev/)
npm run scuttle:dev-reset
# Validate a database backup before restore
npm run scuttle:restore -- --file data/backups/db-....sqlite --key <KEY>