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:

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. New to it? Follow the Solo Dev guide — zero to a sandbox on one box, no certificates.

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

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

Contributing

PRs welcome. See CONTRIBUTING.md for the development environment, local gates, and PR conventions. Bugs and feature requests go through GitHub Issues.

Security

Vulnerabilities should be reported privately. See SECURITY.md for the responsible-disclosure path.

License

Apache 2.0. See also NOTICE.txt.