> ## Documentation Index
> Fetch the complete documentation index at: https://docs.promptguard.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Testing & Environments

> One reference for running and testing PromptGuard across all four environments — local engine, the Shadow AI agent locally, staging, and production/dogfood.

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.

<CardGroup cols={2}>
  <Card title="Local engine" icon="laptop-code">
    The API + database on your machine. Fastest loop for detector, policy, and API work.
  </Card>

  <Card title="Shadow AI locally" icon="user-shield">
    The desktop agent pointed at your local engine — test detection on real AI traffic with zero cloud dependency.
  </Card>

  <Card title="Staging" icon="flask">
    A production-shaped deploy on every push to `main`. Where E2E runs before anything ships.
  </Card>

  <Card title="Production / dogfood" icon="rocket">
    Customer-facing, monitored. You dogfood it the way a user would.
  </Card>
</CardGroup>

<Note>
  **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.
</Note>

## 1. Local engine

The PromptGuard API (`:8080`) + Supabase, in Docker. See [`CONTRIBUTING.md`](https://github.com/acebot712/promptguard/blob/main/CONTRIBUTING.md) for full setup.

<Steps>
  <Step title="Start it">
    ```bash theme={"system"}
    make local        # API on :8080 + Supabase, one command
    make health       # confirm services are up
    ```
  </Step>

  <Step title="Seed demo data (optional)">
    ```bash theme={"system"}
    make demo:on      # a demo user, project, API key, and 500 events
    make demo:off     # remove events (keeps the user)
    ```
  </Step>

  <Step title="Run the tests">
    ```bash theme={"system"}
    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
    ```
  </Step>

  <Step title="Stop">
    ```bash theme={"system"}
    make stop         # stop services, keep your data
    ```

    <Warning>
      `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.
    </Warning>
  </Step>
</Steps>

## 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`).

<Steps>
  <Step title="Point the agent at your local engine">
    With `make local` running in the other repo, mint a local key and log in:

    ```bash theme={"system"}
    pgshadow login --local --api-key <demo-key>   # --local = http://localhost:8080/api/v1
    ```

    (Get `<demo-key>` from `make demo:on`'s output.)
  </Step>

  <Step title="One-command demo (recommended)">
    ```bash theme={"system"}
    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.
  </Step>

  <Step title="Or drive the pieces yourself">
    ```bash theme={"system"}
    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
    ```
  </Step>
</Steps>

<Note>
  `--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](/shadow-ai/test-drive).
</Note>

## 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.

<Steps>
  <Step title="Trigger">
    Merge a PR to `main`. The staging pipeline runs on its own.
  </Step>

  <Step title="Check health & logs">
    ```bash theme={"system"}
    make health:staging
    make logs:staging [LIMIT=200]
    make logs:staging:tail          # stream live
    ```
  </Step>

  <Step title="Run E2E against staging">
    ```bash theme={"system"}
    make test:e2e:staging           # Playwright suite vs the deployed staging app
    ```
  </Step>
</Steps>

## 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.

| Component | URL                           |
| --------- | ----------------------------- |
| API       | `https://api.promptguard.co`  |
| Dashboard | `https://app.promptguard.co`  |
| Docs      | `https://docs.promptguard.co` |

<Steps>
  <Step title="Ship a release">
    ```bash theme={"system"}
    git tag v3.9.4 && git push origin v3.9.4
    ```
  </Step>

  <Step title="Verify">
    ```bash theme={"system"}
    make health           # production health (default env)
    make test:e2e:production
    ```
  </Step>

  <Step title="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](/shadow-ai/test-drive). For the production hardening checklist, see [Best Practices](/production/best-practices).
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Local: services won't start / port in use" icon="triangle-exclamation">
    `make stop` then `make local`. If Supabase is wedged, `make db:reset` (destructive) gives a clean DB. Check `make health`.
  </Accordion>

  <Accordion title="Shadow AI: nothing gets flagged" icon="magnifying-glass">
    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`.
  </Accordion>

  <Accordion title="Staging/prod deploy fails at the migration step" icon="database">
    "Remote migration versions not found in local migrations directory" means the DB history drifted from the repo. See the [Fix Migration Drift runbook](https://github.com/acebot712/promptguard/blob/main/docs/04_engineering/runbooks/FIX_MIGRATION_DRIFT.md).
  </Accordion>

  <Accordion title="Which environment am I hitting?" icon="signs-post">
    Local: `localhost:8080`. Production: `api.promptguard.co`. The Shadow agent's target is whatever `pgshadow login` saved — check `pgshadow status`.
  </Accordion>
</AccordionGroup>

<Card title="Deploying to production for real?" icon="list-check" href="/production/best-practices">
  The production best-practices checklist covers API-key management, policy config, monitoring, and reliability.
</Card>