shoreguard 0.32.0

Open source control plane for NVIDIA OpenShell

ShoreGuard

Open-source control plane for NVIDIA OpenShell. Manage AI agent sandboxes, inference routing, and security policies — from a web UI, REST API, or Terraform.

---

Architecture

ShoreGuard sits between operators and OpenShell's secure runtime. Agents run inside hardened sandboxes with routed inference — they never see real API keys or provider endpoints.

graph LR
    subgraph "Operators — all use ShoreGuard REST API"
        UI["ShoreGuard Web UI"]
        TF["Terraform Provider"]
        PC["Paperclip"]
        OC["OpenClaw"]
    end

    subgraph "Observability"
        Grafana["Grafana"]
    end

    subgraph "ShoreGuard — Management Plane"
        SG["ShoreGuard API"]
        DB[("PostgreSQL")]
        Metrics["/metrics"]
    end

    subgraph "Gateway: dev"
        OS1["OpenShell Controller"]
        subgraph "Sandbox"
            Agent1["Agent"]
        end
        Proxy1["inference.local/v1"]
    end

    subgraph "Gateway: staging"
        OS2["OpenShell Controller"]
        subgraph "Sandbox "
            Agent2["Agent"]
        end
        Proxy2["inference.local/v1"]
    end

    subgraph "LLM Providers"
        LLM["Anthropic / NVIDIA / OpenAI"]
    end

    UI --> SG
    TF --> SG
    PC -->|"adapter plugin"| SG
    OC -->|"slash commands"| SG
    PC -.->|"controls"| Agent1
    OC -.->|"controls"| Agent1
    Grafana --> Metrics
    SG --> DB
    SG --> Metrics
    SG -- "gRPC + mTLS" --> OS1
    SG -- "gRPC + mTLS" --> OS2
    OS1 --> Agent1
    OS2 --> Agent2
    Agent1 -. "inference.local" .-> Proxy1
    Agent2 -. "inference.local" .-> Proxy2
    Proxy1 -- "real API key" --> LLM
    Proxy2 -- "real API key" --> LLM

    style SG fill:#1a7f37,color:#fff,stroke:#1a7f37
    style Agent1 fill:#c8e6c9,stroke:#388e3c,color:#1b5e20
    style Agent2 fill:#c8e6c9,stroke:#388e3c,color:#1b5e20
    style Proxy1 fill:#ffe0b2,stroke:#e65100,color:#bf360c
    style Proxy2 fill:#ffe0b2,stroke:#e65100,color:#bf360c
    style Grafana fill:#bbdefb,stroke:#1565c0,color:#0d47a1

Key insight: The agent inside the sandbox only knows inference.local/v1. OpenShell's L7 proxy injects the real credentials and routes to the actual provider. API keys are managed by ShoreGuard, never exposed to agent code. All operators — whether human (Web UI, Terraform) or agent platforms (Paperclip, OpenClaw) — use the same ShoreGuard REST API. One ShoreGuard instance manages multiple gateways (dev, staging, production).

---

Why ShoreGuard?

NVIDIA OpenShell provides hardened sandboxes for AI agents — but ships with only a CLI. NemoClaw adds orchestration, but is single-gateway and CLI-driven.

ShoreGuard adds the missing management layer:

Capability	OpenShell CLI	NemoClaw	ShoreGuard
Sandbox creation	CLI	CLI	Web UI + API + Terraform
Multi-gateway	—	—	Multiple gateways, one dashboard
Visual policy editor	—	—	Drag-and-drop with revision history
Approval flow	—	—	Real-time notifications
Inference routing	CLI	Blueprint profiles	API-driven, per-gateway
Audit trail	—	—	Persistent, filterable, exportable
RBAC	—	—	Admin / Operator / Viewer
Agent frameworks	—	OpenClaw only	Paperclip, OpenClaw, custom
Webhooks	—	—	Slack, Discord, Email, HMAC-signed

---

Quick Start

Local development

pip install shoreguard
shoreguard --local --no-auth

Open http://localhost:8888. The --local flag enables Docker-based gateway management, --no-auth skips login.

Docker Compose (production)

git clone https://github.com/FloHofstetter/shoreguard.git
cd shoreguard/deploy
cp .env.example .env    # edit: set SHOREGUARD_SECRET_KEY, passwords
docker compose up -d    # core: ShoreGuard + OpenShell + Caddy (HTTPS)

The stack automatically generates mTLS certificates, registers an OpenShell gateway, and provides HTTPS via Caddy with self-signed certificates.

Optional profiles

# Add Paperclip agent orchestration
docker compose --profile paperclip up -d

# Add OpenClaw agent gateway (sandboxed)
docker compose --profile openclaw up -d

See the deployment guide for production hardening, custom domains, and Let's Encrypt.

Verifying release integrity

Docker images on GHCR and wheels on PyPI are signed via sigstore keyless (GitHub OIDC → Fulcio → Rekor). Verify before running:

cosign verify ghcr.io/flohofstetter/shoreguard:0.30.3 \
  --certificate-identity-regexp 'https://github.com/FloHofstetter/shoreguard/.*' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com'

PyPI wheels ship with PEP 740 attestations — modern pip/uv verify them automatically. See the installation guide for explicit verification.

---

Features

Sandbox Management

• Sandbox wizard — step-by-step creation with community images, GPU support, and policy presets
• Visual policy editor — network rules, filesystem paths, process settings with revision history and diff viewer
• Approval flow — agents request endpoint access, operators approve or deny in real-time, with binary SHA-256 + process ancestry + L7 request samples for full context
• Multi-stage approvals — per-sandbox quorum with escalation deadlines
• Policy pinning — freeze the active policy version during incidents or change freezes; all writes return HTTP 423
• Boot hooks — pre/post-create validation gates and warm-up tasks attached to each sandbox
• Templates — pre-configured sandboxes for data science, web development, and secure coding

Policy & Verification

• Policy Prover — Z3 formal verification with built-in templates (can_exfiltrate, unrestricted_egress, binary_bypass, write_despite_readonly) that return a SAT witness when a property fails
• GitOps policy sync — declarative YAML policies via shoreguard policy export|diff|apply, optimistic-locked via policy_hash etag, CI apply counts as one quorum vote under an active workflow
• Bypass Detection — OCSF events classified as policy bypass attempts, with MITRE ATT&CK mapping

Infrastructure & Supply Chain

• Multi-gateway — manage dev, staging, and production OpenShell clusters from one dashboard
• Gateway discovery — auto-register gateways from _openshell._tcp.<domain> DNS SRV records
• RBAC — Admin, Operator, Viewer roles with gateway-scoped overrides
• Audit log — persistent, filterable, exportable trail of all state changes
• Health monitoring — automatic gateway probing with status indicators
• SBOM / Supply-Chain Viewer — per-sandbox CycloneDX ingestion with component search, severity filter, and offline CVE browsing

Integrations

• REST API — full CRUD for gateways, sandboxes, policies, providers, and inference (see the API reference)
• Terraform provider — declarative infrastructure as code (gateways, groups, approval workflows, policy pins, boot hooks); policy content lives in the GitOps flow, not Terraform state
• Webhooks — Slack, Discord, Email, and generic webhooks with HMAC-SHA256 signing, including quorum events (approval.vote_cast / quorum_met / escalated) and drift detection (policy.drift_detected)
• Prometheus metrics — /metrics endpoint for Grafana and standard monitoring

Screenshots

Sandbox Overview	Policy Editor

Network Policies	Gateway Detail

Providers	Audit Log

---

Ecosystem

Project	Description
Terraform Provider	Manage gateways, sandboxes, providers, and policies as code
Paperclip Plugin + Adapter	Run Paperclip agents in isolated OpenShell sandboxes
OpenClaw Plugin	/shoreguard slash commands for OpenClaw agents
OpenClaw Sandbox Image	Hardened OpenClaw image for OpenShell deployment
Docker Compose Stack	One-command setup: ShoreGuard + OpenShell + Caddy + optional integrations

---

Roadmap

Shipped:

• Multi-gateway management with health monitoring + DNS SRV auto-discovery
• Multi-region federation (in-k8s via tests/fixtures/charts/openshell-cluster, host-to-host via scripts/m8_demo.py)
• RBAC with gateway-scoped overrides
• Sandbox wizard with community images, presets, and pre/post-create boot hooks
• Visual policy editor with revision history
• Real-time approval flow with binary SHA-256, process ancestry, and L7 request samples
• Multi-stage approval workflows (quorum + escalation)
• Policy pinning (HTTP 423 on all writes while active)
• Z3 policy prover with four built-in verification templates
• GitOps policy sync (YAML export/apply + shoreguard policy CLI + optional drift detection)
• Bypass Detection dashboard with MITRE ATT&CK mapping
• SBOM / Supply-Chain Viewer (CycloneDX ingestion, offline CVE browse)
• Terraform provider (v0.30.0 mirroring server version)
• Helm chart (charts/shoreguard) with production preset + NetworkPolicy + PDB + helm test
• Persistent audit log with export
• Webhooks (Slack, Discord, Email) with HMAC signing and quorum/drift events
• Prometheus metrics
• Paperclip adapter (@shoreguard/paperclip-plugin + @shoreguard/paperclip-adapter)
• Docker Compose stack with Caddy auto-TLS
• Inference routing via OpenShell L7 proxy
• OpenClaw sandbox image with NemoClaw-style hardening

In progress:

• Hardened sandbox deployment via gRPC API (blocked by OpenShell API limitations)
• Routed inference for Paperclip adapter (replace credential injection with inference.local)

Planned:

• DigitalOcean Marketplace integration

---

Development

git clone https://github.com/FloHofstetter/shoreguard.git
cd shoreguard
uv sync --group dev
uv run pre-commit install --hook-type pre-commit --hook-type pre-push
uv run shoreguard --local --no-auth

Run checks with just:

just check    # lint + format + typecheck + tests
just dev      # start dev server
just test     # run unit tests

See the contributing guide for details.

Documentation

Full docs: flohofstetter.github.io/shoreguard

License

Apache 2.0