### Install and Run Development Server

Source: https://github.com/bigbodycobain/shadowbroker/blob/main/frontend/README.md

Installs project dependencies and starts the development server. Access the application at http://localhost:3000.

```bash
npm install
npm run dev        # http://localhost:3000
```

--------------------------------

### Install and Use Podman Compose

Source: https://github.com/bigbodycobain/shadowbroker/blob/main/README.md

For Podman users, install the `podman-compose` package and use it to pull images and start the services. Ensure you clone the repository and `cd` into the directory before running commands.

```bash
# Linux / macOS / WSL
python3 -m pip install --user podman-compose
podman-compose pull
podman-compose up -d
```

```powershell
# Windows PowerShell
py -m pip install --user podman-compose
podman-compose pull
podman-compose up -d
```

--------------------------------

### Setup Backend Virtual Environment (Bash)

Source: https://github.com/bigbodycobain/shadowbroker/blob/main/README.md

A shell script to set up the backend virtual environment and install development dependencies.

```bash
# macOS/Linux
# ./backend/scripts/setup-venv.sh
```

--------------------------------

### Setup Backend Virtual Environment (PowerShell)

Source: https://github.com/bigbodycobain/shadowbroker/blob/main/README.md

A PowerShell script to set up the backend virtual environment and install development dependencies.

```powershell
# Windows PowerShell
# .\backend\scripts\setup-venv.ps1
```

--------------------------------

### Install Frontend Dependencies

Source: https://github.com/bigbodycobain/shadowbroker/blob/main/README.md

Navigate to the frontend directory and install the necessary Node.js dependencies using npm ci.

```bash
cd ../frontend
npm ci
```

--------------------------------

### Install ShadowBroker Helm Chart

Source: https://github.com/bigbodycobain/shadowbroker/blob/main/helm/chart/README.md

Install the ShadowBroker Helm chart locally from a chart directory.

```bash
helm install shadowbroker ./chart --create-namespace
```

--------------------------------

### Install ShadowBroker from Repository

Source: https://github.com/bigbodycobain/shadowbroker/blob/main/helm/chart/README.md

Install the ShadowBroker Helm chart using the added Helm repository, specifying a namespace and a values file.

```bash
helm install shadowbroker bjw-s-labs/app-template \
  --namespace shadowbroker \
  -f values.yaml
```

--------------------------------

### Install Tauri CLI

Source: https://github.com/bigbodycobain/shadowbroker/blob/main/desktop-shell/tauri-skeleton/README.md

Installs the Tauri CLI globally. Ensure you have Rust and Cargo installed first.

```bash
cargo install tauri-cli@^2
```

--------------------------------

### Clone Repository and Start Docker Compose

Source: https://github.com/bigbodycobain/shadowbroker/blob/main/README.md

Clone the Shadowbroker repository, navigate into the directory, pull the Docker images, and start the services in detached mode.

```bash
git clone https://github.com/bigbodycobain/Shadowbroker.git
cd Shadowbroker
docker compose pull
docker compose up -d
```

--------------------------------

### Clone Repository and Install Backend Dependencies

Source: https://github.com/bigbodycobain/shadowbroker/blob/main/README.md

Clone the Shadowbroker repository and set up the Python backend environment. This includes creating a virtual environment, activating it, and installing the project dependencies.

```bash
# Clone the repository
git clone https://github.com/BigBodyCobain/Shadowbroker.git
cd Shadowbroker

# Backend setup
cd backend
python -m venv venv
venv\Scripts\activate        # Windows
# source venv/bin/activate   # macOS/Linux
pip install .
```

--------------------------------

### Install Pre-commit Hooks

Source: https://github.com/bigbodycobain/shadowbroker/blob/main/README.md

Install pre-commit hooks from the repository root to ensure code quality and consistency before committing changes.

```bash
pre-commit install
```

--------------------------------

### Build Desktop Application

Source: https://github.com/bigbodycobain/shadowbroker/blob/main/desktop-shell/tauri-skeleton/RELEASE.md

Use these commands to initiate the desktop build process. The `--clean` flag can be used to remove previous build artifacts before starting.

```bash
# POSIX shell
./build.sh
```

```powershell
# Windows PowerShell
./build.ps1
```

```bash
# Cross-platform npm wrapper
npm --prefix desktop-shell run build:desktop
```

--------------------------------

### Start Development Shell

Source: https://github.com/bigbodycobain/shadowbroker/blob/main/desktop-shell/tauri-skeleton/README.md

Launches the development shell for the Tauri application. Requires the frontend dev server to be running on port 3000.

```bash
./dev.sh
```

--------------------------------

### Run Docker Compose with Podman

Source: https://github.com/bigbodycobain/shadowbroker/blob/main/README.md

Instructions for users of Podman on different operating systems to pull images and start services using the podman compose wrapper.

```bash
./compose.sh --engine podman pull
./compose.sh --engine podman up -d
```

--------------------------------

### Run Development Server

Source: https://github.com/bigbodycobain/shadowbroker/blob/main/README.md

Start the frontend and backend development servers concurrently from the frontend directory using npm run dev. This will launch the Next.js frontend and FastAPI backend.

```bash
# From the frontend directory — starts both frontend & backend concurrently
npm run dev
```

--------------------------------

### Docker Compose Configuration for ShadowBroker

Source: https://context7.com/bigbodycobain/shadowbroker/llms.txt

Example docker-compose.yml for deploying ShadowBroker services. Configure environment variables for secrets and API URLs.

```yaml
# docker-compose.yml (abridged)
services:
  backend:
    image: ghcr.io/bigbodycobain/shadowbroker-backend:latest
    ports: ["8000:8000"]
    environment:
      - SECRET_KEY=your-secret-key-here
      - ADMIN_KEY=your-admin-key-here
      - OPENCLAW_HMAC_SECRET=your-hmac-secret
      - MESH_MQTT_ENABLED=false
    volumes:
      - ./data:/app/data

  frontend:
    image: ghcr.io/bigbodycobain/shadowbroker-frontend:latest
    ports: ["3000:3000"]
    environment:
      - NEXT_PUBLIC_API_URL=http://localhost:8000
```

--------------------------------

### Get Summary

Source: https://github.com/bigbodycobain/shadowbroker/blob/main/openclaw-skills/shadowbroker/SKILL.md

Use `get_summary()` to retrieve a lightweight, counts-only summary of available data. This is recommended before pulling any data to discover what exists.

```python
await sb.send_command("get_summary")
```

--------------------------------

### Configure Backend URL for Remote Deployments

Source: https://github.com/bigbodycobain/shadowbroker/blob/main/README.md

Set the BACKEND_URL environment variable to point to your backend server when deploying publicly or on a LAN. Examples are provided for Linux/macOS, Podman, and Windows PowerShell.

```bash
# Linux / macOS
BACKEND_URL=http://myserver.com:9096 docker compose up -d

# Podman (via compose.sh wrapper)
BACKEND_URL=http://192.168.1.50:9096 ./compose.sh up -d

# Windows (PowerShell)
$env:BACKEND_URL="http://myserver.com:9096"; docker compose up -d

# Or add to a .env file next to docker-compose.yml:
# BACKEND_URL=http://myserver.com:9096
```

--------------------------------

### Docker Deployment and Health Check

Source: https://context7.com/bigbodycobain/shadowbroker/llms.txt

Commands to start ShadowBroker services using Docker Compose and verify backend health. The health check endpoint provides version information.

```bash
# Start services
docker compose up -d
```

```bash
# Verify backend health
curl http://localhost:8000/api/health
```

```bash
# Check version
curl http://localhost:8000/api/health | jq .version
```

--------------------------------

### Clone and Navigate Shadowbroker Repository

Source: https://github.com/bigbodycobain/shadowbroker/blob/main/README.md

Use these commands to clone the repository and navigate into the project directory. This is the first step for setting up the project locally.

```bash
git clone https://github.com/BigBodyCobain/Shadowbroker.git
cd Shadowbroker
```

--------------------------------

### Create .env file with API Keys

Source: https://github.com/bigbodycobain/shadowbroker/blob/main/README.md

Create a .env file in the backend directory and add your required API keys for services like AISstream and OpenSky.

```bash
echo "AIS_API_KEY=your_aisstream_key" >> .env
echo "OPENSKY_CLIENT_ID=your_opensky_client_id" >> .env
echo "OPENSKY_CLIENT_SECRET=your_opensky_secret" >> .env
```

--------------------------------

### Initialize ShadowBroker Client

Source: https://github.com/bigbodycobain/shadowbroker/blob/main/openclaw-skills/shadowbroker/SKILL.md

Import the client and instantiate it. The client automatically detects local or remote mode.

```python
from sb_query import ShadowBrokerClient
sb = ShadowBrokerClient()  # auto-detects local or remote mode
```

--------------------------------

### GET /api/settings/wormhole — Wormhole Settings

Source: https://context7.com/bigbodycobain/shadowbroker/llms.txt

Retrieve current Wormhole / privacy settings. Authenticated admins receive the full configuration, while unauthenticated callers get only public fields.

```APIDOC
## GET /api/settings/wormhole — Wormhole Settings

### Description
Read current Wormhole / privacy settings. Returns full config to authenticated admin; public fields only (`enabled`, `transport`, `anonymous_mode`) to unauthenticated callers.

### Method
GET

### Endpoint
/api/settings/wormhole

### Response
#### Success Response (200)
- **enabled** (boolean) - Indicates if Wormhole is enabled.
- **transport** (string) - The transport protocol used.
- **anonymous_mode** (boolean) - Indicates if anonymous mode is active.
(Full configuration returned to authenticated admin users).
```

--------------------------------

### Build Desktop Application (npm wrapper)

Source: https://github.com/bigbodycobain/shadowbroker/blob/main/desktop-shell/tauri-skeleton/README.md

Builds the desktop application using an npm wrapper script from the repository root. This script handles the full packaging pipeline.

```bash
npm --prefix desktop-shell run build:desktop
```

--------------------------------

### GET /api/geocode/reverse

Source: https://context7.com/bigbodycobain/shadowbroker/llms.txt

Performs reverse geocoding to convert coordinates into a human-readable location name.

```APIDOC
## GET /api/geocode/reverse — Reverse Geocoding

### Description
Convert coordinates to a human-readable location name.

### Method
GET

### Endpoint
/api/geocode/reverse

### Parameters
#### Query Parameters
- **lat** (number) - Required - The latitude.
- **lng** (number) - Required - The longitude.

### Response
#### Success Response (200)
- **display_name** (string) - The human-readable name of the location.
- **lat** (number) - Latitude of the location.
- **lng** (number) - Longitude of the location.

### Request Example
```bash
curl "http://localhost:8000/api/geocode/reverse?lat=36.78&lng=36.95"
```
```

--------------------------------

### GET /api/sar/near

Source: https://context7.com/bigbodycobain/shadowbroker/llms.txt

Finds SAR anomalies within a specified radius of a given coordinate, sorted by distance.

```APIDOC
## GET /api/sar/near — SAR Anomalies Near a Coordinate

### Description
Returns anomalies within `radius_km` of a point, sorted by distance. Each result includes `distance_km`.

### Method
GET

### Endpoint
/api/sar/near

### Parameters
#### Query Parameters
- **lat** (number) - Required - The latitude of the center point.
- **lng** (number) - Required - The longitude of the center point.
- **radius_km** (number) - Required - The radius in kilometers to search within.
- **kind** (string) - Optional - Filters anomalies by type (e.g., "flood_extent").

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the request was successful.
- **count** (integer) - The number of anomalies found within the radius.
- **anomalies** (array) - A list of SAR anomalies within the specified radius.
  - **distance_km** (number) - The distance of the anomaly from the center point in kilometers.
  - Other anomaly fields as described in `/api/sar/anomalies`.

### Request Example
```bash
curl "http://localhost:8000/api/sar/near?lat=50.45&lng=30.52&radius_km=50&kind=flood_extent"
```

### Response Example
```json
{"ok": true, "count": 3, "anomalies": [{"distance_km": 12.4, ...}, ...]}}
```

### Python SDK Example
```python
near = await sb.sar_anomalies_near(lat=50.45, lng=30.52, radius_km=50)
for a in near["anomalies"]:
    print(f"{a['kind']} — {a['distance_km']}km away — hash:{a['evidence_hash'][:16]}")
```
```

--------------------------------

### AIS-Catcher Ingest

Source: https://context7.com/bigbodycobain/shadowbroker/llms.txt

Accepts decoded AIS messages from a local AIS-catcher installation via an HTTP JSON feed.

```APIDOC
## POST /api/ais/feed — AIS-Catcher Ingest

### Description
Accept decoded AIS messages from a local AIS-catcher installation (HTTP JSON feed format).

### Method
POST

### Endpoint
/api/ais/feed

### Parameters
#### Request Body
- **msgs** (array) - Required - An array of AIS message objects.
  - **mmsi** (integer) - Required - The MMSI of the vessel.
  - **lat** (number) - Required - The latitude of the vessel.
  - **lng** (number) - Required - The longitude of the vessel.
  - **speed** (number) - Required - The speed of the vessel.
  - **course** (number) - Required - The course of the vessel.
  - **heading** (number) - Required - The heading of the vessel.
  - **status** (integer) - Required - The navigational status of the vessel.

### Request Example
```bash
curl -X POST http://localhost:8000/api/ais/feed \
  -H "Content-Type: application/json" \
  -d 
    {
      "msgs": [
        {"mmsi": 636016400, "lat": 36.6, "lng": 5.4, "speed": 12.3,
         "course": 270, "heading": 268, "status": 0}
      ]
    }
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the status of the ingestion, e.g., "ok".
- **ingested** (integer) - The number of AIS messages ingested.

#### Response Example
```json
{
  "status": "ok",
  "ingested": 1
}
```
```

--------------------------------

### GET /api/geocode/search

Source: https://context7.com/bigbodycobain/shadowbroker/llms.txt

Performs forward geocoding to convert a place name into coordinates using Nominatim, with an option for a local cache.

```APIDOC
## GET /api/geocode/search — Forward Geocoding

### Description
Convert a place name to coordinates via Nominatim (with optional local-only cache).

### Method
GET

### Endpoint
/api/geocode/search

### Parameters
#### Query Parameters
- **q** (string) - Required - The place name to geocode.
- **limit** (integer) - Optional - The maximum number of results to return.

### Response
#### Success Response (200)
- **results** (array) - A list of geocoding results.
  - **lat** (number) - Latitude of the result.
  - **lon** (number) - Longitude of the result.
  - **display_name** (string) - The display name of the location.
- **query** (string) - The original query string.
- **count** (integer) - The total number of results found.

### Request Example
```bash
curl "http://localhost:8000/api/geocode/search?q=Griffith+Observatory+Los+Angeles&limit=3"
```

### Response Example
```json
{"results": [{"lat": 34.1184, "lon": -118.3004, "display_name": "..."}],
 "query": "Griffith Observatory...", "count": 1}
```

### Python SDK Example
```python
results = await sb.geocode("Hmeimim Air Base, Syria")
if results:
    lat, lon = results[0]["lat"], results[0]["lon"]
    await sb.place_pin(lat=lat, lng=lon, label="Hmeimim AB", category="military")
```
```

--------------------------------

### sig() — Message Signatures

Source: https://context7.com/bigbodycobain/shadowbroker/llms.txt

Ensures all outbound OpenClaw messages start with the appropriate branded signature, categorized by message type.

```APIDOC
## Message Signatures — `sig()` — Branded Prefixes

### Description
All outbound OpenClaw messages must start with the appropriate branded signature.

### Method
`sig(signature_key)`

### Parameters
- **signature_key** (string) - Required - The key representing the message type (e.g., 'intel', 'warning').

### Usage
Prefix outbound messages with the returned signature string.

### Example
```python
from sb_signatures import sig

message = f"{sig('intel')}\nCVN-78 Gerald Ford has departed Norfolk Naval Station.\nAIS track shows NE heading at 18 knots. 2 DDGs + 1 SSN in escort.\nEstimated Mediterranean arrival: 2026-04-22."
```

### Available Signatures (Selected)
- 'brief' → 🌍📡 SHADOWBROKER BRIEF:
- 'warning' → 🌍⚠️ SHADOWBROKER WARNING:
- 'intel' → 🌍🛰️ SHADOWBROKER INTEL:
- 'threat' → 🌍🔴 SHADOWBROKER THREAT:
- 'sigint' → 🌍📻 SHADOWBROKER SIGINT:
- 'maritime' → 🌍🚢 SHADOWBROKER MARITIME:
- 'flight' → 🌍🛫 SHADOWBROKER FLIGHT:
- 'sar' → 🌍📡 SHADOWBROKER SAR:
- 'seismic' → 🌍🌋 SHADOWBROKER SEISMIC:
- 'correlation' → 🌍⚡ SHADOWBROKER CORRELATION:
- 'near_you' → 🌍📍 SHADOWBROKER NEAR YOU:
- 'pinning' → 🌍📌 SHADOWBROKER PINNING:
```

--------------------------------

### Build Desktop Application (POSIX)

Source: https://github.com/bigbodycobain/shadowbroker/blob/main/desktop-shell/tauri-skeleton/README.md

Builds the desktop application using a POSIX shell script. This script handles the full packaging pipeline.

```bash
./build.sh
```

--------------------------------

### Get Ship Trail by MMSI

Source: https://context7.com/bigbodycobain/shadowbroker/llms.txt

Fetches the AIS position trail for a vessel identified by its Maritime Mobile Service Identity (MMSI).

```bash
curl http://localhost:8000/api/trail/ship/636016400
# {"id": 636016400, "trail": [{"lat": 36.6, "lng": 5.4, "ts": 1744466000}, ...]}}
```

--------------------------------

### Get AOI Coverage and Next Pass Estimate

Source: https://github.com/bigbodycobain/shadowbroker/blob/main/openclaw-skills/shadowbroker/SKILL.md

Retrieves coverage information and the next estimated pass time for a specified AOI.

```python
coverage = await sb.sar_coverage_for_aoi(aoi_id="kyiv_metro")
```

--------------------------------

### Initialize ShadowBrokerClient in Python

Source: https://context7.com/bigbodycobain/shadowbroker/llms.txt

Instantiate the ShadowBrokerClient for local or remote connections. For remote connections, ensure the SHADOWBROKER_URL and SHADOWBROKER_HMAC_SECRET environment variables are set.

```python
from sb_query import ShadowBrokerClient

# Local mode — auto-connects to localhost:8000 (no config needed)
sb = ShadowBrokerClient()

# Remote mode — set env vars first:
# SHADOWBROKER_URL=https://your-host:8000
# SHADOWBROKER_HMAC_SECRET=your-hmac-secret
sb = ShadowBrokerClient()  # same call, reads env automatically

# Check authentication tier
status = await sb.channel_status()
# {"tier": "hmac_direct", "reason": "HMAC key configured"}
```

--------------------------------

### Desktop Shell Build Scripts

Source: https://github.com/bigbodycobain/shadowbroker/blob/main/desktop-shell/README.md

Use these entrypoints to build the desktop application. The `--clean` flag removes previous exports and artifacts before rebuilding.

```bash
./desktop-shell/tauri-skeleton/build.sh
```

```powershell
./desktop-shell/tauri-skeleton/build.ps1
```

```bash
npm --prefix desktop-shell run build:desktop
```

--------------------------------

### GET /api/sar/anomalies

Source: https://context7.com/bigbodycobain/shadowbroker/llms.txt

Retrieves pre-processed SAR anomalies, such as flood extents and surface deformation, from various sources. Mode B must be enabled.

```APIDOC
## GET /api/sar/anomalies — SAR Ground-Change Anomalies (Mode B)

### Description
Returns pre-processed SAR anomalies from NASA OPERA, Copernicus EGMS/GFM/EMS, and UNOSAT — flood extents, surface deformation, damage assessments. Mode B must be enabled.

### Method
GET

### Endpoint
/api/sar/anomalies

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of anomalies to return.
- **kind** (string) - Optional - Filters anomalies by type (e.g., "flood_extent").
- **aoi_id** (string) - Optional - Filters anomalies by Area of Interest ID.

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the request was successful.
- **count** (integer) - The total number of anomalies returned.
- **products_enabled** (boolean) - Whether SAR products (Mode B) are enabled.
- **anomalies** (array) - A list of SAR anomalies.
  - **id** (string) - Unique identifier for the anomaly.
  - **lat** (number) - Latitude of the anomaly.
  - **lng** (number) - Longitude of the anomaly.
  - **kind** (string) - The type of anomaly (e.g., "surface_deformation", "flood_extent").
  - **evidence_hash** (string) - Hash of the evidence for the anomaly.
  - **magnitude_mm** (number) - Magnitude of deformation in millimeters (if applicable).
  - **aoi_id** (string) - The ID of the Area of Interest this anomaly belongs to.

### Request Example
```bash
# All anomalies (latest cached)
curl "http://localhost:8000/api/sar/anomalies?limit=50"

# Filter by kind
curl "http://localhost:8000/api/sar/anomalies?kind=flood_extent&limit=20"

# Filter by AOI
curl "http://localhost:8000/api/sar/anomalies?aoi_id=port_of_odesa&limit=50"
```

### Response Example
```json
{"ok": true, "count": 12, "products_enabled": true,
 "anomalies": [{"id": "opera-disp-...", "lat": 46.5, "lng": 30.7,
                "kind": "surface_deformation", "evidence_hash": "sha256:...",
                "magnitude_mm": -12.3, "aoi_id": "port_of_odesa", ...}]}
```
```

--------------------------------

### Build Desktop Application (PowerShell)

Source: https://github.com/bigbodycobain/shadowbroker/blob/main/desktop-shell/tauri-skeleton/README.md

Builds the desktop application using a Windows PowerShell script. This script handles the full packaging pipeline.

```powershell
./build.ps1
```

--------------------------------

### GET /api/sar/status

Source: https://context7.com/bigbodycobain/shadowbroker/llms.txt

Retrieves the status of SAR (Search and Rescue) features, including feature-gate status and onboarding links for enabling Mode B.

```APIDOC
## GET /api/sar/status — SAR Mode Status + Onboarding Links

### Description
Returns SAR feature-gate status. When Mode B is disabled, includes a step-by-step `help` block with free signup URLs so the user can enable it in-app without hunting externally.

### Method
GET

### Endpoint
/api/sar/status

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the request was successful.
- **catalog** (object) - Status of the catalog feature.
  - **mode** (string) - The current mode (e.g., "A").
  - **enabled** (boolean) - Whether the feature is enabled.
  - **needs_account** (boolean) - Whether an account is required.
  - **description** (string) - Description of the feature.
- **products** (object) - Status of the products feature (Mode B).
  - **mode** (string) - The current mode (e.g., "B").
  - **enabled** (boolean) - Whether the feature is enabled.
  - **help** (object) - Information on how to enable the feature if disabled.
    - **steps** (array) - An array of steps to enable the feature.
      - **step** (integer) - The step number.
      - **label** (string) - Description of the step.
      - **url** (string) - URL for the step.
- **openclaw_enabled** (boolean) - Whether OpenCLAW is enabled.

### Request Example
```bash
curl http://localhost:8000/api/sar/status
```

### Response Example
```json
{
  "ok": true,
  "catalog": {"mode": "A", "enabled": true, "needs_account": false,
              "description": "Free Sentinel-1 scene catalog from ASF Search."},
  "products": {"mode": "B", "enabled": false, "help": {"steps": [...]}},
  "openclaw_enabled": true
}
```
```

--------------------------------

### Set Meshtastic Layer

Source: https://context7.com/bigbodycobain/shadowbroker/llms.txt

Toggles the Meshtastic layer integration within the SIGINT layer. This command automatically starts or stops the Meshtastic MQTT bridge.

```APIDOC
## POST /api/commands/set_layer

### Description
Toggles the Meshtastic layer integration within the SIGINT layer. This command automatically starts or stops the Meshtastic MQTT bridge.

### Method
POST

### Endpoint
/api/commands/set_layer

### Request Body
- **sigint_meshtastic** (boolean) - Set to `true` to enable the Meshtastic layer, `false` to disable.

### Request Example
{
  "sigint_meshtastic": true
}
```

--------------------------------

### Get Latest Sentinel-2 Satellite Scenes

Source: https://github.com/bigbodycobain/shadowbroker/blob/main/openclaw-skills/shadowbroker/SKILL.md

Retrieves the latest Sentinel-2 satellite scenes for a given geographic coordinate. Useful for visual intelligence of a location.

```python
await sb.get_satellite_images(lat=35.68, lng=51.38, count=3)
```

--------------------------------

### ShadowBroker Client Initialization

Source: https://github.com/bigbodycobain/shadowbroker/blob/main/openclaw-skills/shadowbroker/SKILL.md

Initialize the ShadowBroker client. It automatically detects local mode or uses environment variables for remote mode.

```APIDOC
## Initialize Client

### Description
Instantiate the `ShadowBrokerClient` to connect to the ShadowBroker platform.

### Method
```python
from sb_query import ShadowBrokerClient
sb = ShadowBrokerClient()
```

### Configuration
- **Local Mode**: No configuration needed if running on the same machine as ShadowBroker.
- **Remote Mode**: Set the following environment variables:
  - `SHADOWBROKER_URL`: The URL of your ShadowBroker host (e.g., `https://your-shadowbroker-host:8000`).
  - `SHADOWBROKER_HMAC_SECRET`: The HMAC secret obtained from ShadowBroker's 'Connect OpenClaw' modal.
```

--------------------------------

### Batch Place Pins with ShadowBroker

Source: https://context7.com/bigbodycobain/shadowbroker/llms.txt

Efficiently create up to 100 pins in a single request. This is useful for ingesting multiple related intelligence events.

```python
# Batch-place geolocated SIGINT events
await sb.place_pins_batch([
    {
        "lat": 55.75, "lng": 37.62,
        "label": "RF anomaly Moscow",
        "category": "sigint",
        "confidence": 0.7,
        "ttl_hours": 24,
    },
    {
        "lat": 59.95, "lng": 30.32,
        "label": "RF anomaly St Petersburg",
        "category": "sigint",
        "confidence": 0.65,
        "ttl_hours": 24,
    },
])
# {"ok": true, "created": 2, "pins": [...]}
```

```bash
curl -X POST http://localhost:8000/api/ai/pins/batch \
  -H "Content-Type: application/json" \
  -d '{
    "pins": [
      {"lat": 55.75, "lng": 37.62, "label": "Site A", "category": "sigint"},
      {"lat": 48.85, "lng": 2.35,  "label": "Site B", "category": "news"}
    ],
    "layer_id": "mission-alpha"
  }'
```

--------------------------------

### CI/GitHub Actions Workflow

Source: https://github.com/bigbodycobain/shadowbroker/blob/main/desktop-shell/tauri-skeleton/RELEASE.md

The CI workflow for desktop releases is defined in this file. It handles building artifacts across different platforms and uploading them to GitHub releases.

```text
.github/workflows/desktop-release.yml
```

--------------------------------

### Get Oracle Intelligence Summary

Source: https://context7.com/bigbodycobain/shadowbroker/llms.txt

Obtains a concise regional intelligence summary by aggregating news items for a specified coordinate. Requires latitude and longitude as query parameters.

```bash
curl "http://localhost:8000/api/oracle/region-intel?lat=55.75&lng=37.62"
# {"region": "Moscow, Russia", "summary": "...", "threat_indicators": [...], ...}
```

--------------------------------

### Check ShadowBroker Backend Logs

Source: https://github.com/bigbodycobain/shadowbroker/blob/main/README.md

Monitor the logs of the ShadowBroker backend service in real-time using 'docker compose logs -f'.

```bash
docker compose logs -f backend
```

--------------------------------

### Get Flight Trail by ICAO24

Source: https://context7.com/bigbodycobain/shadowbroker/llms.txt

Retrieves the cached position trail for a specific flight using its ICAO24 hex code. Ensure the flight data is available in the cache.

```bash
curl http://localhost:8000/api/trail/flight/AE07D2
# {"id": "AE07D2", "trail": [{"lat": 36.5, "lng": 36.1, "alt": 28000, "ts": 1744466400}, ...]}}
```

--------------------------------

### Fast-Tier Live Data API

Source: https://context7.com/bigbodycobain/shadowbroker/llms.txt

Stream fast-refresh data including flights, ships, CCTV, UAVs, and more. Use `initial=true` for a startup-capped payload.

```bash
# Full dashboard update
curl http://localhost:8000/api/live-data/fast

# First-paint (capped counts)
curl "http://localhost:8000/api/live-data/fast?initial=true"

# Response keys: commercial_flights, military_flights, private_flights,
# private_jets, tracked_flights, ships, cctv, uavs, liveuamap,
# gps_jamming, satellites, satellite_source, satellite_analysis,
# sigint, sigint_totals, cctv_total, trains, freshness
```

--------------------------------

### GET /api/live-data/slow — Slow-Tier Live Data

Source: https://context7.com/bigbodycobain/shadowbroker/llms.txt

Returns the enrichment tier of live data, updated less frequently, including news, stocks, weather, earthquakes, and more.

```APIDOC
## GET /api/live-data/slow — Slow-Tier Live Data

### Description
Returns the enrichment tier updated less frequently: news, stocks, oil, weather, traffic, earthquakes, frontlines, GDELT, airports, KiwiSDR stations, SatNOGS observations, TinyGS satellites, space weather, internet outages, FIRMS fires, datacenters, military bases, power plants, and VIIRS change nodes.

### Method
GET

### Endpoint
/api/live-data/slow

### Response
#### Success Response (200)
- **news** (array) - News articles.
- **earthquakes** (array) - Earthquake data.
- **firms_fires** (array) - FIRMS fire data.
- **gdelt** (array) - GDELT project data.
- **datacenters** (array) - Datacenter locations.
- **military_bases** (array) - Military base locations.
- **power_plants** (array) - Power plant locations.
- **space_weather** (array) - Space weather data.
- **internet_outages** (array) - Internet outage reports.
- **satnogs_observations** (array) - SatNOGS satellite observations.
- **tinygs_satellites** (array) - TinyGS satellite data.
- **wastewater** (array) - Wastewater data.
- **uap_sightings** (array) - Unidentified Aerial Phenomena sightings.
- **volcanoes** (array) - Volcano data.
- **air_quality** (array) - Air quality data.

### Request Example
```bash
curl http://localhost:8000/api/live-data/slow
```

### Response Example
```json
{
  "news": [...],
  "earthquakes": [...],
  "firms_fires": [...],
  "gdelt": [...],
  "datacenters": [...],
  "military_bases": [...],
  "power_plants": [...],
  "space_weather": [...],
  "internet_outages": [...],
  "satnogs_observations": [...],
  "tinygs_satellites": [...],
  "wastewater": [...],
  "uap_sightings": [...],
  "volcanoes": [...],
  "air_quality": [...]
}
```
```

--------------------------------

### Configure Backend Port in .env

Source: https://github.com/bigbodycobain/shadowbroker/blob/main/README.md

If the backend port is already in use, create or edit the .env file to specify a different port for the backend API.

```bash
BACKEND_PORT=8001
```

--------------------------------

### Get Satellite Images

Source: https://github.com/bigbodycobain/shadowbroker/blob/main/openclaw-skills/shadowbroker/SKILL.md

Fetches the latest Sentinel-2 satellite scenes for a specified geographic location. Useful for visual intelligence and when users request satellite images of a place.

```APIDOC
## Get Satellite Images

### Description
Retrieves the latest Sentinel-2 satellite scenes for a given latitude and longitude.

### Method
`get_satellite_images`

### Parameters
- **lat** (float) - Required - The latitude of the location.
- **lng** (float) - Required - The longitude of the location.
- **count** (int) - Optional - The number of scenes to retrieve.

### Response
#### Success Response (200)
- **scenes** (list) - A list of satellite scene objects, each containing `scene_id`, `datetime`, `cloud_cover`, `thumbnail_url`, and `fullres_url`.

### Request Example
```python
scenes = await sb.get_satellite_images(lat=35.68, lng=51.38, count=3)
```

### Response Example
```json
{
  "scenes": [
    {
      "scene_id": "S2A_MSIL1C_20231027T103031_N0509_R078_T32TNL_20231027T103031",
      "datetime": "2023-10-27T10:30:31Z",
      "cloud_cover": 0.15,
      "thumbnail_url": "https://example.com/thumbnails/scene1.jpg",
      "fullres_url": "https://example.com/fullres/scene1.tif"
    }
  ]
}
```
```

--------------------------------

### Shadowbroker Project Structure

Source: https://github.com/bigbodycobain/shadowbroker/blob/main/README.md

Overview of the directory and file structure for the Shadowbroker project, highlighting key modules and their purposes.

```tree
Shadowbroker/
├── backend/
│   ├── main.py                     # FastAPI app, middleware, API routes (~4,000 lines)
│   ├── cctv.db                     # SQLite CCTV camera database (auto-generated)
│   ├── config/
│   │   └── news_feeds.json         # User-customizable RSS feed list
│   ├── services/
│   │   ├── data_fetcher.py         # Core scheduler — orchestrates all data sources
│   │   ├── ais_stream.py           # AIS WebSocket client (25K+ vessels)
│   │   ├── carrier_tracker.py      # OSINT carrier position estimator (GDELT news scraping)
│   │   ├── cctv_pipeline.py        # 13-source CCTV camera ingestion pipeline
│   │   ├── geopolitics.py          # GDELT + Ukraine frontline + air alerts
│   │   ├── region_dossier.py       # Right-click country/city intelligence
│   │   ├── radio_intercept.py      # Police scanner feeds + OpenMHZ
│   │   ├── kiwisdr_fetcher.py      # KiwiSDR receiver scraper
│   │   ├── sentinel_search.py      # Sentinel-2 STAC imagery search
│   │   ├── shodan_connector.py     # Shodan device search connector
│   │   ├── sigint_bridge.py        # APRS-IS TCP bridge
│   │   ├── network_utils.py        # HTTP client with curl fallback
│   │   ├── api_settings.py         # API key management
│   │   ├── news_feed_config.py     # RSS feed config manager
│   │   ├── fetchers/
│   │   │   ├── flights.py          # OpenSky, adsb.lol, GPS jamming, holding patterns
│   │   │   ├── geo.py              # AIS vessels, carriers, GDELT, fishing activity
│   │   │   ├── satellites.py       # CelesTrak TLE + SGP4 propagation
│   │   │   ├── earth_observation.py # Quakes, fires, volcanoes, air quality, weather
│   │   │   ├── infrastructure.py   # Data centers, power plants, military bases
│   │   │   ├── trains.py           # Amtrak + DigiTraffic European rail
│   │   │   ├── sigint.py           # SatNOGS, TinyGS, APRS, Meshtastic
│   │   │   ├── meshtastic_map.py   # Meshtastic MQTT + map node aggregation
│   │   │   ├── military.py         # Military aircraft classification
│   │   │   ├── news.py             # RSS intelligence feed aggregation
│   │   │   ├── financial.py        # Global markets data
│   │   │   └── ukraine_alerts.py   # Ukraine air raid alerts
│   │   └── mesh/                   # InfoNet / Wormhole protocol stack
│   │       ├── mesh_protocol.py    # Core mesh protocol + routing
│   │       ├── mesh_crypto.py      # Ed25519, X25519, AESGCM primitives
│   │       ├── mesh_hashchain.py   # Hash chain commitment system (~1,400 lines)
│   │       ├── mesh_router.py      # Multi-transport router (APRS, Meshtastic, WS)
│   │       ├── mesh_wormhole_persona.py  # Gate persona identity management
│   │       ├── mesh_wormhole_dead_drop.py # Dead Drop token-based DM mailbox
│   │       ├── mesh_wormhole_ratchet.py   # Double-ratchet DM scaffolding
│   │       ├── mesh_wormhole_gate_keys.py # Gate key management + rotation
│   │       ├── mesh_wormhole_seal.py      # Message sealing + unsealing
│   │       ├── mesh_merkle.py      # Merkle tree proofs for data commitment
│   │       ├── mesh_reputation.py  # Node reputation scoring
│   │       ├── mesh_oracle.py      # Oracle consensus protocol
│   │       └── mesh_secure_storage.py # Secure credential storage
├── frontend/
│   ├── src/
│   │   ├── app/
│   │   │   └── page.tsx            # Main dashboard — state, polling, layout
│   │   └── components/
│   │       ├── MaplibreViewer.tsx   # Core map — all GeoJSON layers
│   │       ├── MeshChat.tsx        # InfoNet / Mesh / Dead Drop chat panel
│   │       ├── MeshTerminal.tsx    # Draggable CLI terminal
│   │       ├── NewsFeed.tsx        # SIGINT feed + entity detail panels
│   │       ├── WorldviewLeftPanel.tsx   # Data layer toggles (35+ layers)
│   │       ├── WorldviewRightPanel.tsx  # Search + filter sidebar
│   │       ├── AdvancedFilterModal.tsx  # Airport/country/owner filtering
│   │       ├── MapLegend.tsx       # Dynamic legend with all icons
│   │       ├── MarketsPanel.tsx    # Global financial markets ticker
│   │       ├── RadioInterceptPanel.tsx # Scanner-style radio panel
│   │       ├── FindLocateBar.tsx   # Search/locate bar
│   │       ├── ChangelogModal.tsx  # Version changelog popup (auto-shows on upgrade)
│   │       ├── SettingsPanel.tsx   # API Keys + News Feed + Shodan config
│   │       ├── ScaleBar.tsx        # Map scale indicator
│   │       └── ErrorBoundary.tsx   # Crash recovery wrapper
│   └── package.json
```

--------------------------------

### Check Backend Environment Variables (Bash)

Source: https://github.com/bigbodycobain/shadowbroker/blob/main/README.md

A shell script to check the backend environment variables and warn about missing API keys.

```bash
# macOS/Linux
# ./backend/scripts/check-env.sh
```

--------------------------------

### Get Full Intelligence Report

Source: https://github.com/bigbodycobain/shadowbroker/blob/main/openclaw-skills/shadowbroker/SKILL.md

Use `get_report()` to retrieve a full structured intelligence report. This method is part of the full telemetry dump options and should be used sparingly.

```python
await sb.get_report()
```

--------------------------------

### Updater Key Files for Local Builds

Source: https://github.com/bigbodycobain/shadowbroker/blob/main/desktop-shell/tauri-skeleton/RELEASE_INPUTS.md

These files are required for local builds to use the Tauri updater. Keep them safe and ignored by version control.

```text
release-secrets/shadowbroker-updater.key
release-secrets/shadowbroker-updater.key.pass
```

--------------------------------

### Set API URL for Build (Linux/macOS)

Source: https://github.com/bigbodycobain/shadowbroker/blob/main/frontend/README.md

Configures the build-time API URL environment variable for Linux or macOS systems. Rebuilding is required after changing this variable.

```bash
NEXT_PUBLIC_API_URL=http://myserver:8000 npm run build
```

--------------------------------

### Get Mesh Network Status

Source: https://context7.com/bigbodycobain/shadowbroker/llms.txt

Retrieves the current status of the Wormhole / InfoNet / RNS mesh network, including connectivity, peer count, transport tier, and privacy settings.

```bash
curl http://localhost:8000/api/mesh/status
# {
#   "enabled": true, "transport": "direct", "anonymous_mode": false,
#   "peers_active": 3, "peers_configured": 5, "infonet_chain_height": 842,

```

--------------------------------

### Place Batch Pins

Source: https://github.com/bigbodycobain/shadowbroker/blob/main/openclaw-skills/shadowbroker/SKILL.md

Use `place_pins_batch()` to add up to 100 pins to the 'AI Intel' layer in a single request. Provide a list of pin objects, each with at least latitude, longitude, and label.

```python
# Batch pins (up to 100 at once)
await sb.place_pins_batch([
    {"lat": 34.05, "lng": -118.24, "label": "Site A", "category": "research"},
    {"lat": 34.10, "lng": -118.30, "label": "Site B", "category": "research"},
])
```

--------------------------------

### Get SAR Anomalies Near a Coordinate

Source: https://context7.com/bigbodycobain/shadowbroker/llms.txt

Find SAR anomalies within a specified radius of a given latitude and longitude. Results are sorted by distance and include the distance in kilometers.

```bash
curl "http://localhost:8000/api/sar/near?lat=50.45&lng=30.52&radius_km=50&kind=flood_extent"
```

```text
# {"ok": true, "count": 3, "anomalies": [{"distance_km": 12.4, ...}, ...]})

```

```python
near = await sb.sar_anomalies_near(lat=50.45, lng=30.52, radius_km=50)
for a in near["anomalies"]:
    print(f"{a['kind']} — {a['distance_km']}km away — hash:{a['evidence_hash'][:16]}")
```

--------------------------------

### Run AIS-catcher Docker Image

Source: https://github.com/bigbodycobain/shadowbroker/blob/main/README.md

Run the AIS-catcher Docker image to decode local AIS ship data and POST it to the ShadowBroker API. Ensure the USB device is correctly mapped.

```bash
docker run -d --device /dev/bus/usb \
  ghcr.io/jvde-github/ais-catcher -H http://host.docker.internal:4000/api/ais/feed interval 10
```