• About
• Architecture
• Screenshots
• Getting Started
  • Prerequisites
  • Quick Start (Docker)
  • Expanded Setup Instructions
  • Public Deployment (Cloudflare Tunnel)
• Key System
• Project Structure
• Available Scripts
• Related Documentation
• Contributing
• Security

Install dependencies first:

npm install

Production Commands (The Great Scuttle):

• Start All: npm run scuttle:prod-start (Builds frontend, then starts API + Frontend on 0.0.0.0)
• Stop All: npm run scuttle:prod-stop
• Reset DB: npm run scuttle:reset (DANGER: Deletes prod reef)

Development Commands (The Coral Nursery):

• Start All: npm run scuttle:dev-start (API + Frontend w/ HMR on localhost)
• Stop All: npm run scuttle:dev-stop
• Reset DB: npm run scuttle:reset-dev (Scuttles dev reef)

Utility Scripts:

• Start API Only: npm run start:api
• Frontend Dev Only: npm run dev
• Build Bundle: npm run build
• Preview Build: npm run preview
• Lint TypeScript: npm run lint
• Run Tests: npm test

Option A: Production (Pull from GHCR) ⚓

Use this for a stable, sovereign deployment. It pulls the latest pre-built images from GitHub Container Registry.

docker compose up -d

Option B: Development & Testing (Build Locally) 🛠️

Use this if you are modifying the source code and want to test changes immediately.

docker compose -f docker-compose.dev.yml up -d --build

Environment Variables Reference:

Monitoring & Maintenance:

# View logs in real-time
docker compose logs -f

# Stop the stack
docker compose down

# Restart the stack
docker compose restart

# View database file location
ls -lah ./data/db.sqlite

# Backup your database
cp ./data/db.sqlite ./data/db.sqlite.backup

[!IMPORTANT] Data Sovereignty & Persistence: All pinchmarks and agent identities are stored in local bind mounts on your host machine for maximum visibility and ease of backup.

• Production: ./data/db.sqlite
• Development: ./data-dev/db.sqlite

These directories can be directly backed up or migrated. If they don't exist, Docker will create them (root-owned) when the container starts. Recommend creating them beforehand with desired permissions: mkdir -p data && chown $USER:$USER data

Ready to deploy publicly? Your app is already configured for CF Tunnel. Here's exactly what to set.

# macOS
brew install cloudflared

# Linux (Debian/Ubuntu)
curl https://pkg.cloudflare.com/cloudflare-release-key.gpg | sudo gpg --yes --dearmor --output /usr/share/keyrings/cloudflare-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/cloudflare-archive-keyring.gpg] https://pkg.cloudflare.com/linux $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/cloudflare-main.list
sudo apt-get update && sudo apt-get install cloudflared

# Or download binary
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o cloudflared
chmod +x ./cloudflared

cloudflared tunnel login
# This opens a browser to authenticate with your Cloudflare account

cloudflared tunnel create claw-chives
# Returns: Tunnel credentials saved in ~/.cloudflared/...json

Create ~/.cloudflared/config.yml:

tunnel: claw-chives
credentials-file: ~/.cloudflared/<your-id>.json

ingress:
  - hostname: claw-chives.your-domain.com
    service: http://localhost:4646
  - service: http_status:404

Replace:

• claw-chives.your-domain.com — your desired domain
• <your-id>.json — the credentials file from step 3 (find it with ls ~/.cloudflared/)

Add these to your .env or Docker environment:

# Trust the CF Tunnel proxy headers (reads real client IP)
TRUST_PROXY=true

# Lock CORS to your CF domain only
CORS_ORIGIN=https://claw-chives.your-domain.com

# Enable HTTPS redirect (optional — CF handles HTTPS, but good for defense-in-depth)
ENFORCE_HTTPS=true

# Database encryption (strongly recommended)
DB_ENCRYPTION_KEY=$(openssl rand -base64 32)

For Docker: Add these to docker-compose.yml environment section:

environment:
  - TRUST_PROXY=true
  - CORS_ORIGIN=https://claw-chives.your-domain.com
  - ENFORCE_HTTPS=true
  - DB_ENCRYPTION_KEY=<your-key-from-openssl-command>

# Development: Run tunnel in foreground (see logs)
cloudflared tunnel run claw-chives

# Production: Run tunnel as systemd service
sudo cloudflared service install
sudo systemctl start cloudflared
sudo systemctl status cloudflared

In Cloudflare DNS settings for your domain:

# Test the tunnel
curl https://claw-chives.your-domain.com/api/health

# Should return:
# { "success": true, "service": "ClawChives API", "version": "2.0.0", ... }

✅ HTTPS — CF provides free TLS certificates ✅ Real Client IP — Audit logs show actual IPs (not CF gateway) ✅ Rate Limiting — Preserved (per-agent limits still work) ✅ Database Encryption — AES-256 at rest ✅ CORS Protection — Only your domain can access API ✅ Zero Port Forwarding — CF Tunnel handles all networking

# Check tunnel status
cloudflared tunnel list

# View tunnel logs
cloudflared tunnel run claw-chives --loglevel debug

# Test API accessibility
curl -v https://claw-chives.your-domain.com/api/health

# Check CORS headers
curl -i -H "Origin: https://claw-chives.your-domain.com" \
  https://claw-chives.your-domain.com/api/health

[!TIP] Not ready for public? Skip this section and keep using Docker Compose locally. You can add CF Tunnel anytime — just set the env vars above when you're ready.