// SELF-HOST GUIDE

Run ShadowCypher on Your Infrastructure

Three paths to full sovereignty: Docker Compose for a single machine, Kubernetes for scale, or bare metal if you want maximum control. No cloud dependency required.

// PREREQUISITES

Requirement	Version	Notes
Docker	24+	Docker Desktop or Docker Engine
Docker Compose	v2+	Bundled with Docker Desktop
RAM	4 GB min	8 GB recommended if running Ollama AI
Disk	10 GB	More if downloading AI models
OS	Linux / macOS / Windows WSL2	ARM64 supported (Apple Silicon, Pi 5)

// OPTION 1 — DOCKER COMPOSE RECOMMENDED

The fastest path. Runs the Guardian agent, a local web UI, and optionally Ollama for AI — all in isolated containers.

Clone the repository

git clone https://github.com/jakes1345/ShadowCypher.git
cd ShadowCypher

Configure environment

cp config.example.json config.json
# Edit config.json — set your API key from shadowcypher.site/account
nano config.json

The only required field is api_key. Everything else has sensible defaults.

Start the stack

docker compose up -d

This starts the Guardian agent in the background. It will begin scanning your network within 30 seconds and reporting to your dashboard.

Verify it's running

docker compose logs -f shadowcypher-ui

You should see Guardian agent active — scanning network within a minute. Your devices will appear at shadowcypher.site → Guardian.

// WITH LOCAL AI (OLLAMA) OPTIONAL

Add AI capabilities without sending any data to the cloud. Requires a GPU or Apple Silicon for reasonable speed.

# docker-compose.override.yml — add this file to enable Ollama
services:
  ollama:
    image: ollama/ollama:latest
    container_name: shadowcypher_ollama
    volumes:
      - ollama_data:/root/.ollama
    ports:
      - "11434:11434"
    deploy:
      resources:
        reservations:
          devices:
            - capabilities: [gpu]   # remove if no GPU

  shadowcypher-ui:
    environment:
      - OLLAMA_HOST=http://ollama:11434

volumes:
  ollama_data:

# Pull and start
docker compose -f docker-compose.yml -f docker-compose.override.yml up -d

# Pull the default Shadow AI model (1.75 GB)
docker exec shadowcypher_ollama ollama pull hf.co/NousResearch/Hermes-3-Llama-3.2-3B-GGUF:Q4_K_M

// OPTION 2 — KUBERNETES ADVANCED

For running ShadowCypher across a cluster or on a homelab with k3s/k8s.

# namespace
kubectl create namespace shadowcypher

# secret — your API key from shadowcypher.site
kubectl create secret generic shadowcypher-config \
  --from-literal=api_key=sc_live_YOUR_KEY_HERE \
  -n shadowcypher

# deploy guardian agent
kubectl apply -f https://shadowcypher.site/k8s/guardian.yaml -n shadowcypher

# check status
kubectl get pods -n shadowcypher

The Kubernetes manifest runs the Guardian agent as a DaemonSet so it monitors every node in your cluster. It reports device discovery and security incidents back to your dashboard in real time.

// OPTION 3 — BARE METAL

No Docker. Just Python 3.11+ on Linux or macOS.

# Install
git clone https://github.com/jakes1345/ShadowCypher.git
cd ShadowCypher
pip3 install -r requirements.txt

# Configure
cp config.example.json config.json
nano config.json   # add your api_key

# Run Guardian agent
python3 shadowcypher/scripts/guardian.py run

# Or as a systemd service (Linux)
sudo cp shadowcypher.service /etc/systemd/system/
sudo systemctl enable --now shadowcypher

// ENVIRONMENT VARIABLES

Variable	Default	Description
`SC_API_KEY`	—	Your shadowcypher.site API key (required)
`SC_API_BASE`	`https://shadowcypher-api.shadowcypher.workers.dev`	Override for self-hosted backend
`SC_SCAN_INTERVAL`	`600`	Seconds between network scans
`OLLAMA_HOST`	`http://127.0.0.1:11434`	Ollama endpoint for local AI
`SC_LOG_LEVEL`	`INFO`	DEBUG \| INFO \| WARNING \| ERROR

// SELF-HOST THE BACKEND (OPTIONAL)

The backend API is a Cloudflare Worker. You can fork it and deploy your own instance in under 5 minutes.

Self-hosting the backend requires your own Supabase project, Stripe account, and optionally Resend for email. See API Docs for the full database schema.

// UPDATES

// GETTING HELP

Open an issue on GitHub or email hello@shadowcypher.site. Check the status page if the cloud API seems down.