Skip to main content

TSZ Quick Start Guide

This guide helps you deploy TSZ locally and call the primary /detect endpoint in under 10 minutes.

TSZ is designed to run as a containerized microservice in your environment (Docker, Kubernetes, on‑prem, cloud). The steps below focus on a local Docker‑based setup.

For Kubernetes deployments, use the Helm chart in deployment/helm/thyris-sz and follow the deployment guide.

If applications already send LLM traffic through Envoy Gateway, use the Bring Your Gateway quick path instead. BYG attaches Safe Zone at the gateway and does not require each application to call /detect or adopt an SDK.

1. Prerequisites​

  • Docker and Docker Compose installed
  • Git installed
  • Optional: Go 1.23+ if you want to run from source instead of Docker
  • Optional: Helm 3 and access to a Kubernetes cluster if you want to use the Helm chart

2. Clone the Repository​

git clone https://source.example/thyris/repository
cd safe-zone

3. Configure Environment (Optional)​

A default configuration is already provided in deployment/docker/docker-compose.yml and .env.example. The PostgreSQL bootstrap schema lives in scripts/database/init.sql.

Key environment variables:

SERVER_PORT=8080
DB_DSN=postgres://postgres:postgres@localhost:5432/thyris?sslmode=disable&TimeZone=the region/Example City
REDIS_URL=redis://:thyrisredis@localhost:6379/0

# Security middleware
SECURITY_HEADERS_ENABLED=true
CORS_ENABLED=true
MAX_REQUEST_SIZE_BYTES=10485760
HANDLER_TIMEOUT_DETECT_SECONDS=30
HANDLER_TIMEOUT_CHAT_SECONDS=300

# AuthN/AuthZ (set true in production)
AUTH_ENABLED=false
AUTH_REQUIRE_BEARER_TOKEN=true
AUTH_TOKEN_PERMISSIONS=token_detect=detect:read,token_admin=*
AUTH_PUBLIC_PATHS=/healthz,/ready

# AI Provider Configuration
# Options: CHAT_COMPLETIONS_COMPATIBLE (default) or MANAGED_MODEL
AI_PROVIDER=CHAT_COMPLETIONS_COMPATIBLE

# chat-completions provider-Compatible Provider (chat-completions provider, cloud provider chat-completions provider, local model runtime, etc.)
AI_MODEL_URL=http://localhost:11434/v1
AI_API_KEY=local model runtime
AI_MODEL=llama3.1:8b

# CLOUD_PROVIDER managed model service Provider (only used when AI_PROVIDER=MANAGED_MODEL)
# AWS_BEDROCK_REGION=us-east-1
# AWS_BEDROCK_MODEL_ID=model provider.managed model-3-sonnet-20240229-v1:0
# AWS_BEDROCK_ENDPOINT_OVERRIDE=  # Optional: for VPC endpoints

# Confidence thresholds
CONFIDENCE_ALLOW_THRESHOLD=0.30
CONFIDENCE_BLOCK_THRESHOLD=0.85

# Optional admin API key for /admin endpoints
ADMIN_API_KEY=change-me-in-production

For a local test run, the defaults are usually sufficient. For production, you should:

  • Change all secrets/passwords
  • Configure TLS / API gateway in front of TSZ
  • Tune thresholds according to your risk appetite

4. Start TSZ Using Docker Compose​

From the repository root:

docker compose -f deployment/docker/docker-compose.yml up --build -d

This will start:

  • TSZ API server on http://localhost:8080
  • PostgreSQL (for patterns, allowlist/blocklist, validators)
  • Redis (for AI confidence caching and fast lookups)

For Kubernetes instead of Docker Compose:

helm upgrade --install thyris-sz deployment/helm/thyris-sz \
  --namespace thyris-sz \
  --create-namespace \
  --set image.repository=ghcr.io/thyrisai/thyris-sz \
  --set image.tag=0.1.0

See the deployment guide for production-style values, external PostgreSQL and Redis configuration, ingress, and secret handling.

You can check container status with:

docker ps

5. Verify the Deployment​

5.1 Health Check​

curl http://localhost:8080/healthz

Expected response:

UP

5.2 Readiness Check​

curl http://localhost:8080/ready

Expected response:

READY

If you see Database not ready or Redis not ready, wait a few seconds and retry.

6. First Detection Call (cURL)​

Call the /detect endpoint with a simple text:

curl -X POST http://localhost:8080/detect \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer token_detect" \
  -d '{
    "text": "Contact me at user@example.com regarding order #99281.",
    "rid": "RID-QUICKSTART-001",
    "expected_format": "FREE_TEXT",
    "guardrails": []
  }'

If AUTH_ENABLED=false, you can remove the Authorization header.

Example response (simplified):

{
  "redacted_text": "Contact me at [EMAIL] regarding order #99281.",
  "detections": [
    {
      "type": "EMAIL",
      "value": "user@example.com",
      "placeholder": "[EMAIL]",
      "start": 14,
      "end": 30,
      "confidence_score": "0.87"
    }
  ],
  "breakdown": {
    "EMAIL": 1
  },
  "blocked": false,
  "contains_pii": true,
  "overall_confidence": "0.87"
}

7. Explore with Postman​

The repository includes a ready‑to‑use Postman collection:

7.1 Import the Collection​

  1. Open Postman.
  2. Click Import.
  3. Download and select TSZ_Postman_Collection.json.
  4. A collection named "TSZ – Thyris Safe Zone API (Enterprise – FULL)" will appear.

7.2 Try the Detect Scenarios​

Recommended first requests:

  • Detect – Clean Input (Minimal)
  • Detect – Single EMAIL (Full Fields)
  • Detect – AI Guardrail (Toxic Language) + PII

Then explore:

  • Patterns – create custom regex patterns
  • Allowlist / Blocklist – manage trusted/forbidden values
  • Validators – define AI guardrails like TOXIC_LANGUAGE
  • Templates – import pre‑packaged guardrail sets
  • System – check health, readiness and reload cache

Set these Postman collection variables before running protected endpoints:

  • base_url (example: http://localhost:8080)
  • tsz_bearer_token (example: token_admin when auth is enabled)

8. Basic LLM Integration Example​

Below is a minimal Python example showing how to integrate TSZ in front of an LLM provider (e.g. chat-completions provider):

import requests
import chat-completions provider

TSZ_URL = "http://localhost:8080/detect"
OPENAI_MODEL = "gpt-4"

user_input = "My credit card is 4111 1111 1111 1111, can you save it?"

# 1) Send user input to TSZ
security_check = requests.post(TSZ_URL, json={
    "text": user_input,
    "rid": "RID-PY-001",
    "expected_format": "FREE_TEXT",
    "guardrails": ["TOXIC_LANGUAGE"]
})

result = security_check.json()

if result.get("blocked"):
    raise Exception(result.get("message", "Unsafe content detected by TSZ"))

safe_text = result.get("redacted_text", user_input)

# 2) Call the LLM with redacted input
response = chat-completions provider.ChatCompletion.create(
    model=OPENAI_MODEL,
    messages=[{"role": "user", "content": safe_text}]
)

print(response.choices[0].message["content"])

9. Using the Go Client (tszclient-go)​

If you are building Go services, you can integrate TSZ via the Go client instead of calling the HTTP APIs manually.

9.1 Install & Configure​

Inside this repository:

import tszclient "source.example/thyris/safe-zone/pkg/tszclient-go"

client, err := tszclient.New(tszclient.Config{
    BaseURL: "http://localhost:8080", // TSZ gateway URL
})
if err != nil {
    // handle error
}

9.2 Example – Call /detect from Go​

ctx := context.Background()

resp, err := client.Detect(ctx, tszclient.DetectRequest{
    Text:       "Contact me at user@example.com",
    RID:        "RID-GO-QUICKSTART-001",
    Guardrails: []string{"TOXIC_LANGUAGE"},
})
if err != nil {
    log.Fatalf("detect failed: %v", err)
}

if resp.Blocked {
    log.Printf("request blocked by TSZ: %s", resp.Message)
} else {
    log.Printf("redacted text: %s", resp.RedactedText)
}

For more details, see:

  • Go client
  • examples/go-detect and examples/go-llm-gateway

10. Using the Python Client (tszclient_py / tszclient-py)​

If you are building Python services, you can use the lightweight Python client instead of calling the HTTP APIs manually.

10.1 Install​

Install directly from this source repository repository (from the main branch):

pip install "tszclient-py @ git+https://source.example/thyris/repository@main"

10.2 Example – Call /detect and the LLM gateway from Python​

A runnable example is provided at examples/python-sdk-demo/main.py. In summary, the usage pattern looks like this:

from tszclient_py import TSZClient, TSZConfig, ChatCompletionRequest

client = TSZClient(TSZConfig(
    base_url="http://localhost:8080",
    api_key="token_admin",  # optional; needed when AUTH_ENABLED=true
))

# /detect example
resp = client.detect_text(
    "Contact me at user@example.com",
    rid="RID-QUICKSTART-PY-001",
    guardrails=["TOXIC_LANGUAGE"],
)
print("Redacted:", resp.redacted_text)

# LLM gateway example
chat_req = ChatCompletionRequest(
    model="llama3.1:8b",
    messages=[{"role": "user", "content": "Hello via TSZ gateway (Python)"}],
)
llm_resp = client.chat_completions(chat_req)
print(llm_resp["choices"][0]["message"]["content"])

For a full working demo (including headers, RIDs and guardrails), see:

  • examples/python-sdk-demo/main.py

If auth is enabled in TSZ, set TSZ_AUTH_TOKEN before running the demo:

export TSZ_AUTH_TOKEN=token_admin
python -m examples.python-sdk-demo.main

11. Using the CLI Tool (tsz)​

You can use the tsz command-line tool to interact with the API without writing code.

11.1 Build/Install​

cd pkg/tsz-cli
go build -o tsz
# On Windows: tsz.exe

11.2 Run a Scan​

./tsz scan --text "My email is user@example.com"

Output:

{
  "redacted_text": "My email is [EMAIL]",
  "detections": [...]
}

For more commands (managing patterns, lists, templates), see the TSZ CLI guide.

12. Next Steps​

From here, you can:

  • Read the full API reference for all endpoints.
  • Review Architecture & Security for architecture, data flows and security considerations.
  • Customize patterns, validators and templates to match your organization’s policies.

If you run into issues during Quick Start:

  • Verify Docker containers are running (docker ps).
  • Check TSZ logs (docker-compose logs tsz or application logs).
  • Confirm DB and Redis are reachable and healthy.

For commercial support or architecture reviews, contact open-source@thyris.ai.