### Install and start ShoreGuard

Source: https://flohofstetter.github.io/shoreguard

Install the ShoreGuard package via pip and launch the service to access the setup wizard.

```bash
pip install shoreguard
shoreguard
```

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

### Install ShoreGuard from PyPI with pip

Source: https://flohofstetter.github.io/shoreguard/getting-started/installation

Installs ShoreGuard from PyPI. This is the fastest way to get started.

```bash
pip install shoreguard
```

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

### Install NVIDIA OpenShell Namespace and Chart

Source: https://flohofstetter.github.io/shoreguard/deploy/production-k8s

Create the openshell namespace with privileged pod security and install the NVIDIA OpenShell chart.

```bash
kubectl create ns openshell
kubectl label ns openshell pod-security.kubernetes.io/enforce=privileged

# Install NVIDIA's chart per their docs, e.g.:
# helm install gw-prod nvidia/openshell --namespace openshell \
#   --set <nvidia-specific-values>
```

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

### Install and run ShoreGuard locally with --single-user

Source: https://flohofstetter.github.io/shoreguard/getting-started/dgx-spark

Installs ShoreGuard and starts it in local single-user mode, prompting once for the admin password (account: admin@localhost). After startup, open http://localhost:8888 to log in as admin. Plain --local --no-auth also works while everything stays on loopback.

```bash
pip install shoreguard
shoreguard --local --single-user
# prompts once for your admin password (account: admin@localhost)

```

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

### Install and start ShoreGuard

Source: https://flohofstetter.github.io/shoreguard/getting-started/quickstart

Installs the ShoreGuard package and starts the service. By default, the service runs on port 8888.

```bash
pip install shoreguard && shoreguard
```

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

### Quick start: Set SHOREGUARD_OIDC_PROVIDERS_JSON and run shoreguard

Source: https://flohofstetter.github.io/shoreguard/admin/oidc

Configure a single OIDC provider (Google) by exporting the SHOREGUARD_OIDC_PROVIDERS_JSON environment variable with a JSON array, then start ShoreGuard. The login page will show a 'Sign in with Google' button.

```bash
export SHOREGUARD_OIDC_PROVIDERS_JSON='[
  {
    "name": "google",
    "display_name": "Google",
    "issuer": "https://accounts.google.com",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
  }
]'
shoreguard
```

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

### Clone and install dependencies for sandbox walkthrough

Source: https://flohofstetter.github.io/shoreguard/development/contributing

Clones the repository and installs development dependencies. This is the first step in the walkthrough from a fresh clone to creating your first sandbox.

```bash
git clone https://github.com/FloHofstetter/shoreguard.git
cd shoreguard
uv sync --group dev

```

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

### Install ShoreGuard from PyPI with uv

Source: https://flohofstetter.github.io/shoreguard/getting-started/installation

Installs ShoreGuard from PyPI using uv, an alternative to pip.

```bash
uv pip install shoreguard
```

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

### Initialize environment configuration

Source: https://flohofstetter.github.io/shoreguard/admin/deployment

Creates the .env file from the provided example.

```bash
cp .env.example .env
```

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

### Start the ShoreGuard server

Source: https://flohofstetter.github.io/shoreguard/reference/cli

Starts the ShoreGuard control-plane server using the specified options.

```bash
shoreguard [OPTIONS]
```

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

### Install ShoreGuard

Source: https://flohofstetter.github.io/shoreguard/guides/nemoclaw-migration

Commands to install ShoreGuard for local, Docker Compose, or Kubernetes environments.

```bash
# Local / homelab / single VM
pip install shoreguard
shoreguard --local --no-auth

# Docker Compose (single VM with HTTPS)
cd deploy/
docker compose up -d

# Kubernetes (production)
helm install shoreguard charts/shoreguard -f values.production.yaml
```

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

### Start ShoreGuard in development mode

Source: https://flohofstetter.github.io/shoreguard/admin/deployment

Starts the server with auto-reload enabled for development.

```bash
shoreguard
```

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

### GET /readyz

Source: https://flohofstetter.github.io/shoreguard/reference/api

Readiness probe endpoint that checks database and service initialisation.

```APIDOC
## GET /readyz

### Description
Readiness probe — checks database and service initialisation.

### Method
GET

### Endpoint
/readyz

### Response
#### Success Response (200)
- No response body documented.

#### Response Example
No response example documented.

```

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

### Start the Docker stack

Source: https://flohofstetter.github.io/shoreguard/admin/deployment

Launches the ShoreGuard and PostgreSQL containers in detached mode.

```bash
docker compose up -d
```

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

### POST /api/gateway/{name}/start

Source: https://flohofstetter.github.io/shoreguard/reference/api

Starts a gateway. Only available in local mode.

```APIDOC
## POST /api/gateway/{name}/start

### Description
Start gateway (local mode only).

### Method
POST

### Endpoint
/api/gateway/{name}/start

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the gateway.

### Response
#### Success Response (200)
- No response body documented.

#### Response Example
No response example documented.

```

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

### GET /api/gateways/{gw}/sandboxes/{name}/hooks

Source: https://flohofstetter.github.io/shoreguard/reference/api

Lists boot hooks associated with a sandbox.

```APIDOC
## GET /api/gateways/{gw}/sandboxes/{name}/hooks

### Description
List boot hooks for a sandbox (viewer).

### Method
GET

### Endpoint
/api/gateways/{gw}/sandboxes/{name}/hooks

### Parameters
#### Path Parameters
- **gw** (string) - Required - The gateway identifier
- **name** (string) - Required - The sandbox name

### Response
#### Success Response (200)
- **hooks** (array) - List of hooks

#### Response Example
{
  "hooks": []
}
```

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

### POST /api/auth/setup

Source: https://flohofstetter.github.io/shoreguard/reference/api

Creates the initial admin account on first run.

```APIDOC
## POST /api/auth/setup

### Description
Creates the initial admin account (first run only).

### Method
POST

### Endpoint
/api/auth/setup

### Parameters
#### Request Body
- **email** (string) - Required - Admin email
- **password** (string) - Required - Admin password

### Response
#### Success Response (200)
- **user** (object) - Created admin user

#### Response Example
{
  "user": {}
}

```

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

### Current policy with allow-legacy rule

Source: https://flohofstetter.github.io/shoreguard/guides/gitops-merge

Current policy with one network rule named allow-legacy. Used as the starting point for the diff example.

```yaml
policy:
  network_policies:
    allow-legacy:
      name: allow-legacy
      endpoints:
        - {host: legacy.example.com, port: 443}
```

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

### Install and run ShoreGuard from source

Source: https://flohofstetter.github.io/shoreguard/getting-started/installation

Clones the ShoreGuard repository and runs it from source using uv.

```bash
git clone https://github.com/FloHofstetter/shoreguard.git
cd shoreguard
uv sync
uv run shoreguard
```

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

### REST API request with Bearer token

Source: https://flohofstetter.github.io/shoreguard/admin/service-principals

Example of a GET request to the ShoreGuard API using the service principal key in the Authorization header.

```http
GET /api/gateways
Authorization: Bearer sg_live_abc123...

```

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

### get

Source: https://flohofstetter.github.io/shoreguard/reference/python/client

Get the current active policy for a sandbox.

```APIDOC
## get

### Description
Get the current active policy for a sandbox.

### Method
async

### Endpoint
get(sandbox_name: str) -> dict[str, Any]

### Parameters
#### Path Parameters
- **sandbox_name** (str) - Required - Sandbox name.

### Returns
- **dict[str, Any]** - Active policy status with revision details.
```

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

### Install ShoreGuard with production values

Source: https://flohofstetter.github.io/shoreguard/deploy/production-k8s

Install ShoreGuard with the production preset, overriding environment-specific values. Replace shoreguard.example.com with your actual domain. The production preset enables persistence (2 Gi PVC), nginx Ingress with cert-manager TLS and force-SSL-redirect, NetworkPolicy egress for DNS and LLM providers, JSON logging, and forwarded header trust (forwardedAllowIps: "*").

```bash
helm install sg ./charts/shoreguard \
  --namespace shoreguard \
  -f charts/shoreguard/values.production.yaml \
  --set existingSecret=sg-secrets \
  --set ingress.host=shoreguard.example.com \
  --set 'ingress.tls[0].hosts[0]=shoreguard.example.com' \
  --set 'ingress.tls[0].secretName=shoreguard-tls' \
  --set networkPolicy.egress.inClusterGateways.enabled=true \
  --set 'networkPolicy.egress.inClusterGateways.namespaceSelector.matchLabels.kubernetes\.io/metadata\.name=openshell'
```

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

### Deploy ShoreGuard with systemd

Source: https://flohofstetter.github.io/shoreguard/operations/homelab

Commands to create a system user, set up a virtual environment, install the package, and enable the systemd service.

```bash
sudo useradd --system --home-dir /var/lib/shoreguard --shell /usr/sbin/nologin shoreguard
sudo python3 -m venv /opt/shoreguard
sudo /opt/shoreguard/bin/pip install shoreguard
sudo cp deploy/systemd/shoreguard.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now shoreguard
```

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

### Create a boot hook via the API

Source: https://flohofstetter.github.io/shoreguard/guides/boot-hooks

Creates a post-create boot hook for the sandbox 'agent-a' on the 'dev' gateway. The hook runs 'apt update && apt install -y htop' with a 60-second timeout and is enabled. The request must include the Content-Type header and a JSON body with the hook configuration fields.

```http
POST /api/gateways/dev/sandboxes/agent-a/hooks
Content-Type: application/json

{
  "phase": "post_create",
  "command": "apt update && apt install -y htop",
  "timeout_seconds": 60,
  "enabled": true
}
```

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

### Verify upgrade with readyz and version endpoints

Source: https://flohofstetter.github.io/shoreguard/admin/deployment

Verify the upgrade with the readiness and version probes. The /version endpoint reports the version, git SHA, and build time of the running binary.

```bash
curl -s http://localhost:8888/readyz | python3 -m json.tool
curl -s http://localhost:8888/version

```

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

### GET /export YAML document

Source: https://flohofstetter.github.io/shoreguard/guides/gitops

Deterministic YAML document produced by GET /export. Re-exporting this YAML yields the same bytes because ordering is stable and keys are sorted, keeping Git diffs clean.

```yaml
metadata:
  gateway: dev
  sandbox: agent-a
  version: 42
  policy_hash: 8f3a…
  exported_at: 2026-04-13T12:00:00Z
policy:
  network:
    rules: [...]
  filesystem:
    paths: [...]
  process: {...}

```

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

### POST /api/gateways/{gw}/sandboxes/{name}/hooks/{id}/run

Source: https://flohofstetter.github.io/shoreguard/reference/api

Manually triggers a boot hook. Operator or higher permission required.

```APIDOC
## POST /api/gateways/{gw}/sandboxes/{name}/hooks/{id}/run

### Description
Manually trigger a boot hook (operator+).

### Method
POST

### Endpoint
/api/gateways/{gw}/sandboxes/{name}/hooks/{id}/run

### Parameters
#### Path Parameters
- **gw** (string) - Required - The gateway identifier
- **name** (string) - Required - The sandbox name
- **id** (string) - Required - The hook ID

### Response
#### Success Response (200)
- **status** (string) - Run status

#### Response Example
{
  "status": "triggered"
}
```

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

### Start ShoreGuard server in local mode

Source: https://flohofstetter.github.io/shoreguard/development/contributing

Starts the ShoreGuard server on http://localhost:8888 by default. The --local flag enables Docker-based gateway management, and --no-auth skips login.

```bash
uv run shoreguard --local --no-auth

```

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

### GET /api/auth/users

Source: https://flohofstetter.github.io/shoreguard/reference/api

Retrieves a list of all users.

```APIDOC
## GET /api/auth/users

### Description
Lists all users.

### Method
GET

### Endpoint
/api/auth/users

### Response
#### Success Response (200)
- **users** (array) - List of users

#### Response Example
{
  "users": []
}

```

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

### Headless first-admin creation via env var or CLI

Source: https://flohofstetter.github.io/shoreguard/getting-started/installation

Creates the first admin account without the browser wizard. The first command seeds admin@localhost on first start only while no users exist; the second creates any user explicitly.

```bash
# Seeds admin@localhost on first start, only while no users exist
SHOREGUARD_ADMIN_PASSWORD='choose-a-strong-one' shoreguard

# …or create any user explicitly
shoreguard create-user you@example.com --role admin
```

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

### GET /api/policies/presets

Source: https://flohofstetter.github.io/shoreguard/reference/api

Lists available policy presets.

```APIDOC
## GET /api/policies/presets

### Description
List available policy presets.

### Method
GET

### Endpoint
/api/policies/presets

### Response
#### Success Response (200)
- **presets** (array) - List of policy presets

#### Response Example
{
  "presets": []
}

```

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

### get_pending

Source: https://flohofstetter.github.io/shoreguard/reference/python/client

Get only pending (unapproved) draft chunks.

```APIDOC
## ApprovalManager.get_pending

### Description
Get only pending (unapproved) draft chunks.

### Method
async

### Parameters
#### Path Parameters
- **sandbox_name** (str) - Required - Sandbox name.

### Returns
- **list[dict[str, Any]]** - List of pending chunk dicts.

```

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

### Clone and set up ShoreGuard with uv and pre-commit

Source: https://flohofstetter.github.io/shoreguard/development/contributing

Clones the ShoreGuard repository, installs runtime and development dependencies in an isolated uv-managed virtual environment, and registers the pre-commit hooks for both commit and push.

```bash
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

```

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

### get_draft

Source: https://flohofstetter.github.io/shoreguard/reference/python/client

Get draft policy recommendations for a sandbox.

```APIDOC
## ApprovalManager.get_draft

### Description
Get draft policy recommendations for a sandbox.

### Method
async

### Parameters
#### Path Parameters
- **sandbox_name** (str) - Required - Sandbox name.

#### Query Parameters
- **status_filter** (str) - Optional - Optional status to filter chunks by. Default: `''`

### Returns
- **dict[str, Any]** - Draft policy with chunks, summary, and version.

```

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

### __aenter__

Source: https://flohofstetter.github.io/shoreguard/reference/python/client

Async context manager entry point returning the client instance.

```APIDOC
## __aenter__

### Description
Support usage as an async context manager.

### Method
async

### Signature
```
__aenter__() -> ShoreGuardClient
```

### Returns
- **ShoreGuardClient** - This client instance.
```

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

### GET /api/auth/service-principals

Source: https://flohofstetter.github.io/shoreguard/reference/api

Retrieves a list of all service principals.

```APIDOC
## GET /api/auth/service-principals

### Description
Lists all service principals.

### Method
GET

### Endpoint
/api/auth/service-principals

### Response
#### Success Response (200)
- **service_principals** (array) - List of service principals

#### Response Example
{
  "service_principals": []
}

```

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

### Start development Docker stack

Source: https://flohofstetter.github.io/shoreguard/admin/deployment

Runs the development configuration using SQLite without PostgreSQL.

```bash
docker compose -f docker-compose.dev.yml up --build
```

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

### GET /api/webhooks

Source: https://flohofstetter.github.io/shoreguard/guides/webhooks

Lists all webhooks configured in the system.

```APIDOC
## GET /api/webhooks

### Description
List all webhooks configured in the system.

### Method
GET

### Endpoint
/api/webhooks

### Response
#### Success Response (200)
- **webhooks** (array) - List of webhook objects.

#### Response Example
{
  "webhooks": []
}
```

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

### GET /api/audit/export

Source: https://flohofstetter.github.io/shoreguard/reference/api

Exports the audit log as CSV or JSON.

```APIDOC
## GET /api/audit/export

### Description
Export audit log as CSV or JSON.

### Method
GET

### Endpoint
/api/audit/export

### Parameters
#### Query Parameters
- **format** (string) - Optional - Export format: csv or json

### Response
#### Success Response (200)
- **body** (string) - Exported audit log

#### Response Example
"audit log data"

```

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

### get_version

Source: https://flohofstetter.github.io/shoreguard/reference/python/client

Get a specific policy revision by version number.

```APIDOC
## get_version

### Description
Get a specific policy revision by version number.

### Method
async

### Endpoint
get_version(sandbox_name: str, version: int) -> dict[str, Any]

### Parameters
#### Path Parameters
- **sandbox_name** (str) - Required - Sandbox name.
- **version** (int) - Required - Policy version number to retrieve.

### Returns
- **dict[str, Any]** - Policy status with revision details.
```

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

### Enable budget metering

Source: https://flohofstetter.github.io/shoreguard/guides/budgets

Set the environment variable to enable usage metering for sandboxes.

```text
SHOREGUARD_BUDGET_METERING_ENABLED=true
```

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

### GET /api/gateways/{gw}/providers

Source: https://flohofstetter.github.io/shoreguard/reference/api

Lists all providers associated with a gateway.

```APIDOC
## GET /api/gateways/{gw}/providers

### Description
Lists providers for a gateway.

### Method
GET

### Endpoint
/api/gateways/{gw}/providers

### Parameters
#### Path Parameters
- **gw** (string) - Required - Gateway identifier

### Response
#### Success Response (200)
- **providers** (array) - List of providers

```

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

### get_history

Source: https://flohofstetter.github.io/shoreguard/reference/python/client

Get decision history for a sandbox's draft policy.

```APIDOC
## ApprovalManager.get_history

### Description
Get decision history for a sandbox's draft policy.

### Method
async

### Parameters
#### Path Parameters
- **sandbox_name** (str) - Required - Sandbox name.

### Returns
- **list[dict[str, Any]]** - List of history entry dicts.

```

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

### GET /api/gateways/{gw}/sandboxes

Source: https://flohofstetter.github.io/shoreguard/reference/api

Lists all sandboxes associated with a gateway.

```APIDOC
## GET /api/gateways/{gw}/sandboxes

### Description
List sandboxes for a gateway.

### Method
GET

### Endpoint
/api/gateways/{gw}/sandboxes

### Parameters
#### Path Parameters
- **gw** (string) - Required - The gateway identifier

### Response
#### Success Response (200)
- **sandboxes** (array) - List of sandboxes

#### Response Example
{
  "sandboxes": []
}
```

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

### POST /api/gateways/{gw}/sandboxes/{name}/hooks

Source: https://flohofstetter.github.io/shoreguard/reference/api

Creates a new boot hook for a sandbox. Admin permission required.

```APIDOC
## POST /api/gateways/{gw}/sandboxes/{name}/hooks

### Description
Create a boot hook (admin).

### Method
POST

### Endpoint
/api/gateways/{gw}/sandboxes/{name}/hooks

### Parameters
#### Path Parameters
- **gw** (string) - Required - The gateway identifier
- **name** (string) - Required - The sandbox name

#### Request Body
- **type** (string) - Required - Hook type (pre-create or post-create)
- **command** (string) - Required - Command to run
- **env** (object) - Optional - Environment variables

### Request Example
{
  "type": "pre-create",
  "command": "echo hello",
  "env": {}
}

### Response
#### Success Response (200)
- **hook** (object) - Created hook

#### Response Example
{
  "hook": {
    "id": "hook_123",
    "type": "pre-create",
    "command": "echo hello"
  }
}
```

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

### Configure PostgreSQL connection with SHOREGUARD_DATABASE_URL

Source: https://flohofstetter.github.io/shoreguard/reference/configuration

Use this for multi-replica or production deployments. The database and tables are created automatically on first start, and migrations are applied on every startup via Alembic.

```bash
export SHOREGUARD_DATABASE_URL="postgresql+psycopg://user:pass@db-host:5432/shoreguard"
shoreguard --no-reload

```

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

### GET /api/gateways/{gw}/health

Source: https://flohofstetter.github.io/shoreguard/reference/api

Retrieves the health status of a gateway.

```APIDOC
## GET /api/gateways/{gw}/health

### Description
Gateway health status.

### Method
GET

### Endpoint
/api/gateways/{gw}/health

### Parameters
#### Path Parameters
- **gw** (string) - Required - The gateway identifier.

### Response
#### Success Response (200)
- No response body documented.

#### Response Example
No response example documented.

```

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

### GET /api/gateway/{name}/config

Source: https://flohofstetter.github.io/shoreguard/reference/api

Retrieves the configuration for a specific gateway.

```APIDOC
## GET /api/gateway/{name}/config

### Description
Gateway configuration.

### Method
GET

### Endpoint
/api/gateway/{name}/config

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the gateway.

### Response
#### Success Response (200)
- No response body documented.

#### Response Example
No response example documented.

```

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

### Headless Admin Account Creation

Source: https://flohofstetter.github.io/shoreguard/admin/deployment

Methods for creating an initial admin account without a browser, suitable for automated deployments or CI environments.

```bash
# Option 1: environment variable (useful in Docker / CI)
SHOREGUARD_ADMIN_PASSWORD=secret shoreguard --no-reload

# Option 2: CLI command
shoreguard create-user admin@example.com --role admin
```

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

### GET /api/webhooks/{id}

Source: https://flohofstetter.github.io/shoreguard/guides/webhooks

Retrieves a single webhook by its unique identifier.

```APIDOC
## GET /api/webhooks/{id}

### Description
Get a single webhook by its unique identifier.

### Method
GET

### Endpoint
/api/webhooks/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the webhook.

### Response
#### Success Response (200)
- **webhook** (object) - The webhook object.

#### Response Example
{
  "webhook": {}
}
```

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

### Get one webhook

Source: https://flohofstetter.github.io/shoreguard/guides/webhooks

Retrieve details for a specific webhook by its ID.

```http
GET /api/webhooks/{id}
```

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

### Enable local mode via environment variable

Source: https://flohofstetter.github.io/shoreguard/admin/local-mode

Set SHOREGUARD_LOCAL_MODE=1 and run shoreguard to enable local mode.

```bash
export SHOREGUARD_LOCAL_MODE=1
shoreguard

```

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

### Run full check suite with just

Source: https://flohofstetter.github.io/shoreguard/development/contributing

Runs the full check suite before pushing to ensure CI will pass. This covers linting, formatting, type checking, and unit tests.

```bash
just check

```

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

### Initialize PolicyManager

Source: https://flohofstetter.github.io/shoreguard/reference/python/client

Initializes the PolicyManager with an OpenShell gRPC stub and an optional timeout.

```python
PolicyManager(
    stub: OpenShellStub, *, timeout: float = 30.0
)
```

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

### Start ShoreGuard in single-user mode

Source: https://flohofstetter.github.io/shoreguard/getting-started/solo-dev

Starts ShoreGuard in single-user mode, which creates one admin account (admin@localhost) with a password. The password is set interactively or via the SHOREGUARD_ADMIN_PASSWORD environment variable; changing that variable and restarting rotates the password. Use this when the UI is reachable from a LAN or tailnet.

```bash
shoreguard --local --single-user
# prompts for the admin password on a terminal; non-interactively:
SHOREGUARD_ADMIN_PASSWORD='choose-a-strong-one' shoreguard --local --single-user

```

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

### Initialize ProviderManager

Source: https://flohofstetter.github.io/shoreguard/reference/python/client

Instantiates the manager with an OpenShell gRPC stub and an optional timeout.

```python
ProviderManager(
    stub: OpenShellStub, *, timeout: float = 30.0
)
```

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

### GET /api/policies/presets/{name}

Source: https://flohofstetter.github.io/shoreguard/reference/api

Retrieves details of a specific policy preset by name.

```APIDOC
## GET /api/policies/presets/{name}

### Description
Get details of a specific policy preset.

### Method
GET

### Endpoint
/api/policies/presets/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - Preset name

### Response
#### Success Response (200)
- **preset** (object) - Preset details

#### Response Example
{
  "preset": {}
}

```