Engine

The detection engine is a Python service. It scans prompts and responses for PII and prompt-injection signals, and returns results to the gateway for policy enforcement.

Run it alongside the gateway. The gateway still works without it (secrets detection and gateway policy controls stay active), but PII and injection scanning require the engine.

Requirements

Python 3.10+

Install

git clone https://github.com/promptshieldhq/promptshield-engine
cd promptshield-engine

uv sync

Run

uv run uvicorn main:app --port 4321

The engine listens on :4321 by default.

Plain on-prem deployment (no Docker)

Use a process manager (systemd, supervisord, or your platform equivalent) and a local env file.

Create an env file (example /etc/promptshield-engine.env):

PROMPTSHIELD_ENGINE_HOST=0.0.0.0
PROMPTSHIELD_ENGINE_PORT=4321
PROMPTSHIELD_API_KEY=replace-with-strong-random-value
PROMPTSHIELD_ALLOW_UNAUTH=false
PROMPTSHIELD_LOG_LEVEL=INFO

Start with uvicorn (same command your service manager should run):

uv run uvicorn main:app --host 0.0.0.0 --port 4321

Point the gateway and dashboard to this engine URL:

# promptshield-gateway/.env
PROMPTSHIELD_ENGINE_URL=http://<engine-host>:4321
PROMPTSHIELD_ENGINE_API_KEY=<same-as-PROMPTSHIELD_API_KEY>

# promptshield/apps/server/.env
ENGINE_URL=http://<engine-host>:4321
ENGINE_API_KEY=<same-as-PROMPTSHIELD_API_KEY>

Run with Docker Compose (dev only)

The engine repository currently ships a development Compose file only: docker-compose.dev.yml.

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

There is no production Compose file in that repository.

Authentication

By default, the engine requires PROMPTSHIELD_API_KEY.

Recommended: set a key in the engine and set the same value as PROMPTSHIELD_ENGINE_API_KEY in the gateway.
Local/dev-only: set PROMPTSHIELD_ALLOW_UNAUTH=true on the engine to disable auth.

Connect to the gateway

Add to the gateway .env and restart:

PROMPTSHIELD_ENGINE_URL=http://localhost:4321
PROMPTSHIELD_ENGINE_API_KEY=your-engine-key

The gateway will now scan every request before forwarding to the LLM and every response on the way back.

Verify

curl -s http://localhost:4321/health

What it detects

PII: email, phone, SSN, credit card, IBAN, passport, medical license (30+ types)
Prompt injection: heuristic patterns for instruction override, jailbreak, and prompt exfiltration attempts

See Policy for action configuration.

Engine

On this page