Skip to main content
PromptGuard runs in four environments. This page is the single map: what each is for, how to run it, and how to test in it. Everything below is a real, current command.

Local engine

The API + database on your machine. Fastest loop for detector, policy, and API work.

Shadow AI locally

The desktop agent pointed at your local engine — test detection on real AI traffic with zero cloud dependency.

Staging

A production-shaped deploy on every push to main. Where E2E runs before anything ships.

Production / dogfood

Customer-facing, monitored. You dogfood it the way a user would.
Promotion path: code flows local → main (auto-staging) → tag vX.Y.Z (production). Every change is validated in staging before a version tag ships it to production. Test as far left as possible; only what passes staging E2E reaches prod.

​
1. Local engine

The PromptGuard API (:8080) + Supabase, in Docker. See CONTRIBUTING.md for full setup.
1

Start it

make local        # API on :8080 + Supabase, one command
make health       # confirm services are up
2

Seed demo data (optional)

make demo:on      # a demo user, project, API key, and 500 events
make demo:off     # remove events (keeps the user)
3

Run the tests

make test:unit          # fast; no Supabase needed
make test:integration   # needs Supabase running
make test               # both
make test:detectors PROMPT="my aws key is AKIA..."   # try a specific detector
make test:e2e:local     # Playwright against localhost
4

Stop

make stop         # stop services, keep your data
make stop:clean and make db:reset delete all local data (Docker volumes + Supabase). They prompt for confirmation — use only when you want a clean slate.

​
2. Shadow AI agent, locally

Test the desktop agent against your local engine — no cloud, no impact on your real traffic. Run from the promptguard-shadow-desktop repo (build the CLI first: cargo build -p pgshadow-cli).
1

Point the agent at your local engine

With make local running in the other repo, mint a local key and log in:
pgshadow login --local --api-key <demo-key>   # --local = http://localhost:8080/api/v1
(Get <demo-key> from make demo:on’s output.)
2

One-command demo (recommended)

pgshadow demo     # proxy-only + isolated test browser + live detection feed
This brings up the proxy without touching your system network, opens a throwaway browser at claude.ai, and streams each decision (allow / redact / block) as you type. Paste my aws key is AKIAIOSFODNN7EXAMPLE and watch it get caught.
3

Or drive the pieces yourself

pgshadow start --proxy-only    # proxy + PAC, no system changes
pgshadow test-browser          # isolated browser wired to the PAC
pgshadow status                # coverage + proxy liveness
pgshadow stop                  # tear down
--proxy-only never modifies your system proxy — only the test-browser window is routed. For the full system-wide experience (the real product), see the Test It Yourself guide.

​
3. Staging

Staging deploys automatically on every push to main (.github/workflows/staging.yml): unit + integration tests → Cloud Run deploy → Newman smoke tests. It’s the gate every production release must pass.
1

Trigger

Merge a PR to main. The staging pipeline runs on its own.
2

Check health & logs

make health:staging
make logs:staging [LIMIT=200]
make logs:staging:tail          # stream live
3

Run E2E against staging

make test:e2e:staging           # Playwright suite vs the deployed staging app

​
4. Production / dogfood

Production deploys when you push a vX.Y.Z tag (.github/workflows/production.yml): version validation → a staging-freshness gate → pre-deploy tests → Cloud Run → post-deploy smoke + health → GitHub Release.
ComponentURL
APIhttps://api.promptguard.co
Dashboardhttps://app.promptguard.co
Docshttps://docs.promptguard.co
1

Ship a release

git tag v3.9.4 && git push origin v3.9.4
2

Verify

make health           # production health (default env)
make test:e2e:production
3

Dogfood the Shadow AI product

Install the signed build and use it like a customer would — the full walkthrough is the Test It Yourself guide. For the production hardening checklist, see Best Practices.

​
Troubleshooting

make stop then make local. If Supabase is wedged, make db:reset (destructive) gives a clean DB. Check make health.
The proxy fails open when it can’t reach the engine — traffic passes un-scanned. Confirm the engine is up (curl localhost:8080/health) and that you ran pgshadow login --local with a fresh key from make demo:on.
“Remote migration versions not found in local migrations directory” means the DB history drifted from the repo. See the Fix Migration Drift runbook.
Local: localhost:8080. Production: api.promptguard.co. The Shadow agent’s target is whatever pgshadow login saved — check pgshadow status.

Deploying to production for real?

The production best-practices checklist covers API-key management, policy config, monitoring, and reliability.