Skip to content

Streamline Privacy Guard onboarding #27

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
johnnygreco merged 1 commit into from
Jul 29, 2026
Merged

Streamline Privacy Guard onboarding #27

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
102 changes: 39 additions & 63 deletions projects/privacy-guard/docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,115 +44,91 @@ the provider receives the request.
## Quickstart

This quickstart uses the built-in `RegexEngine` example to replace an email
address and customer ID. It requires:
address and customer ID. Before you start, install:

- Python 3.11 or newer
- `uv` 0.11 or newer
- OpenShell and `openshell-gateway` `v0.0.90`, the version recorded in the
[middleware manifest](https://github.com/NVIDIA/OpenShell-Research/blob/main/projects/privacy-guard/.openshell-middleware-manifest.json)
- a Docker or Podman backend supported by OpenShell
- Claude Code subscription access for the final provider request; the OpenShell
base sandbox supplies the Claude Code binary
- [OpenShell](https://github.com/NVIDIA/OpenShell) `v0.0.90` or a later
compatible version

Confirm the installed command versions:
Privacy Guard is tested with the version recorded in the
[middleware manifest](https://github.com/NVIDIA/OpenShell-Research/blob/main/projects/privacy-guard/.openshell-middleware-manifest.json).
A later version must support the same supervisor middleware contract.

```bash
uv --version
openshell --version
openshell-gateway --version
```
Run the following commands from a checkout of OpenShell Research.

Run the commands from a checkout of OpenShell Research.
### 1. Stop the local gateway

### 1. Prepare the example
First, check the local gateway:

```bash
cd projects/privacy-guard/examples/regex-engine
uv sync --locked
uv run privacy-guard engines
openshell status
```

The engine list should contain:
If the gateway is running, stop it before you change its configuration. Use the
command for your system:

```text
regex detect,replace
```

The example files are:
```bash
# macOS with Homebrew
brew services stop openshell

| File | Purpose |
| --- | --- |
| `patterns.yaml` | Email and customer-ID rules |
| `privacy-guard-config.yaml` | Standalone Privacy Guard policy configuration |
| `policy.yaml` | Complete OpenShell sandbox policy with the same configuration |
# Linux with a Debian or RPM package
systemctl --user stop openshell-gateway
```

### 2. Start Privacy Guard

From the example directory:

```bash
uv run privacy-guard serve --listen 0.0.0.0:50051
cd projects/privacy-guard/examples/regex-engine
uv run --locked privacy-guard serve --listen 0.0.0.0:50051
```

Keep the process running. The development server uses plaintext gRPC and
receives request bodies. Restrict port 50051 to the host and trusted sandbox
network.

### 3. Register Privacy Guard with the gateway
### 3. Configure and start the gateway

Choose a non-loopback host IPv4 address that both the gateway and sandbox
supervisor can reach:
supervisor can reach.

```bash
# macOS
ipconfig getifaddr en0

# Linux
hostname -I
```

Create a local gateway configuration:
Open another terminal and return to the example directory. Replace
`YOUR_HOST_IPV4` with the address you selected. Then update the default gateway
configuration:

```bash
export PRIVACY_GUARD_HOST_IP=YOUR_HOST_IPV4

cd projects/privacy-guard/examples/regex-engine
uv run privacy-guard configure-gateway \
--host-ip "$PRIVACY_GUARD_HOST_IP" \
--name privacy-guard-regex \
--config gateway.local.toml
--host-ip YOUR_HOST_IPV4 \
--name privacy-guard-regex
```

Do not use `127.0.0.1`: loopback inside the sandbox supervisor does not refer to
the host.

Restart the local gateway with `gateway.local.toml`. For a Homebrew
installation:
The command above updates the default OpenShell gateway configuration. Next,
use the command for your system to start the gateway in the background:

```bash
brew services stop openshell
export OPENSHELL_LOCAL_TLS_DIR="$HOME/.local/state/openshell/homebrew/tls"
openshell-gateway --config "$PWD/gateway.local.toml"
```

For a Debian or RPM installation:
# macOS with Homebrew
brew services start openshell

```bash
systemctl --user stop openshell-gateway
export OPENSHELL_LOCAL_TLS_DIR="$HOME/.local/state/openshell/tls"
openshell-gateway --config "$PWD/gateway.local.toml"
# Linux with a Debian or RPM package
systemctl --user start openshell-gateway
```

Keep the foreground gateway running.

### 4. Create a sandbox

In another terminal, return to the example directory and verify the gateway:
Open another terminal, return to the example directory, and check the gateway:

```bash
openshell gateway select openshell
cd projects/privacy-guard/examples/regex-engine
openshell status
```

This walkthrough starts Claude Code in the sandbox. To use a different harness,
replace everything after `--` with its command.

Create the example sandbox:

```bash
Expand Down
68 changes: 25 additions & 43 deletions projects/privacy-guard/docs/operations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,24 +67,32 @@ Restrict its listen port to trusted host and sandbox networks.

## Register the service with OpenShell

Choose a non-loopback IPv4 address reachable by both the local gateway and
sandbox supervisors:
First, check the local gateway:

```bash
# macOS
ipconfig getifaddr en0

# Linux
hostname -I
openshell status
```

Add or update a gateway registration:
If the gateway is running, stop it before you change its configuration. Use the
command for your system:

```bash
export PRIVACY_GUARD_HOST_IP=YOUR_HOST_IPV4
# macOS with Homebrew
brew services stop openshell

# Linux with a Debian or RPM package
systemctl --user stop openshell-gateway
```

Choose a non-loopback IPv4 address reachable by both the local gateway and
sandbox supervisors.

Replace `YOUR_HOST_IPV4` with the address you selected. Then add or update the
gateway registration:

```bash
uv run privacy-guard configure-gateway \
--host-ip "$PRIVACY_GUARD_HOST_IP" \
--host-ip YOUR_HOST_IPV4 \
--name privacy-guard \
--port 50051
```
Expand Down Expand Up @@ -115,45 +123,23 @@ network_middlewares:
OpenShell does not dynamically reload middleware registrations. Restart the
gateway after changing its configuration.

## Run a local foreground gateway

Stop the package-managed service before starting another gateway on the same
port.
## Start the local gateway

### macOS with Homebrew

```bash
brew services stop openshell
export OPENSHELL_LOCAL_TLS_DIR="$HOME/.local/state/openshell/homebrew/tls"
openshell-gateway --config "$HOME/.config/openshell/gateway.toml"
```

Restore it after testing:
Use the command for your system to start the gateway in the background:

```bash
# macOS with Homebrew
brew services start openshell
```

### Linux with a Debian or RPM package

```bash
systemctl --user stop openshell-gateway
export OPENSHELL_LOCAL_TLS_DIR="$HOME/.local/state/openshell/tls"
openshell-gateway --config "$HOME/.config/openshell/gateway.toml"
```

Restore it after testing:

```bash
# Linux with a Debian or RPM package
systemctl --user start openshell-gateway
```

For a custom gateway path, replace the `--config` argument accordingly.
The gateway reads the default configuration that `configure-gateway` updated.

## Verify connectivity

```bash
openshell gateway select openshell
openshell status
```

Expand Down Expand Up @@ -250,8 +236,6 @@ port must be between 1 and 65535.
| Symptom | Check |
| --- | --- |
| Sandbox creation reports unavailable middleware | Confirm Privacy Guard is running, the registration name matches the policy, the host IP is reachable from the sandbox network, and the port is allowed |
| Gateway port is already in use | Stop the package-managed gateway before starting a foreground instance |
| Foreground gateway cannot find certificates | Set `OPENSHELL_LOCAL_TLS_DIR` to the package-specific path shown above |
| Policy config is rejected | Run `privacy-guard configuration-schema` with the same registry factory used by the server |
| Relative Regex catalog is not found | Start Privacy Guard from the directory against which the catalog path is defined |
| Request is denied with `privacy_guard_limit_exceeded` | Inspect Privacy Guard logs, reduce input/output/detections, simplify stages, or increase the processing timeout with OpenShell headroom |
Expand All @@ -261,17 +245,15 @@ port must be between 1 and 65535.

## Shutdown and cleanup

Stop foreground Privacy Guard and gateway processes with `Ctrl-C`. Delete test
sandboxes explicitly:
Stop Privacy Guard with `Ctrl-C`. Delete test sandboxes explicitly:

```bash
openshell sandbox delete SANDBOX_NAME
```

Restore the package-managed gateway and verify connectivity:
The gateway continues to run in the background. Verify its connection:

```bash
openshell gateway select openshell
openshell status
```

Expand Down
Loading