Dashboard Overview
The main dashboard gives you a live view of your AI gateway — traffic volume, cache performance, active models, and system health — all in one place.
Recent Activity
last 50 requestshttps://your-domain/dashboard/ — replace with your configured Caddy domain.All-time cumulative count — includes archived logs. Never decreases even as old logs rotate out of Redis.
Percentage of requests served from the 4-phase semantic cache. Higher is better — reduces cost and latency.
Requests stopped by guardrail policies — PII detection, jailbreak attempts, off-topic queries, etc.
SSO & Identity Setup
Connect Smartflow to your identity provider so users authenticate with their corporate credentials. Supports Entra ID (Azure AD), LDAP/Active Directory, and trusted proxy headers.
Microsoft Entra ID (Azure AD)
Navigate to SSO Configuration
From the dashboard top nav, click Users → SSO Config, or go directly to /dashboard/sso_config.html. You'll see a status banner showing whether SSO is currently configured.
Select your identity provider tab
Choose Entra ID / Azure AD for Microsoft environments, LDAP for on-premise Active Directory, or Proxy Headers if your load balancer/IdP injects a user identity header (e.g. X-User-Email, X-Auth-User).
For Entra ID: enter Tenant ID, Client ID, and Client Secret
In Azure Portal → App registrations → your app → Overview: copy the Application (client) ID and Directory (tenant) ID. Under Certificates & secrets, create a new Client Secret and paste it here. The secret is stored encrypted — it is not shown after save.
For LDAP: provide server URL and bind credentials
Enter your LDAP URL (e.g. ldap://dc01.corp.com:389 or ldaps://dc01.corp.com:636), the Base DN for user search (e.g. DC=corp,DC=com), and a read-only service account Bind DN and password. Smartflow uses this account only to validate user lookups.
Click "Test Connection" before saving
The test attempts a lightweight bind or token validation to confirm credentials are correct. A green success banner means the IdP is reachable and credentials are valid. Fix any errors before enabling.
Save & Enable SSO
Click Save & Enable SSO. The status banner at the top of the page turns green. From this point, every API request that arrives with a valid SSO token or identity header will have the authenticated user's identity (user_id, email, groups) attached to their trace log entry — enabling per-user auditing and policy targeting.
Adding & Managing Users
Create virtual API keys and user accounts, assign roles, and control which users can access the Smartflow proxy and management dashboard.
Users & API Keys
| User / Key | Role | Status | Last Seen |
|---|---|---|---|
| alice@corp.com sk-sf-a1b2c3… |
admin | active | 2m ago |
| bob@corp.com sk-sf-d4e5f6… |
user | active | 1hr ago |
| ci-pipeline sk-sf-g7h8i9… |
service | active | 5min ago |
| dave@corp.com sk-sf-j1k2l3… |
user | suspended | 3d ago |
Add New User
Open Admin Users
Navigate to /dashboard/admin_users.html or click Admin → Users from the top nav. You must be logged in as an admin role to access this page.
Click "+ Add User" and fill in the form
Enter the user's email or identifier. Choose a role: admin (full dashboard access), user (proxy access only), service (for CI/CD or applications — no dashboard login), or readonly (can view traces and stats but not change settings).
Set a rate limit
The rate limit controls how many requests per minute this user's API key can send through the proxy. Default is 60/min. For service accounts running batch jobs, set this higher (e.g. 500). For end users on shared plans, keep it lower.
Copy the generated API key immediately
After clicking Create & Generate Key, the virtual key (format: sk-sf-xxxxxx…) is shown once. Copy it now and share it securely with the user. You cannot retrieve it again — only regenerate it.
Users send this key as their OpenAI API key
Users replace OPENAI_API_KEY in their application with the Smartflow virtual key, and replace the API base URL with your Smartflow proxy URL. No other code changes are needed — Smartflow is a drop-in.
/dashboard/key_vault.html. This page lets you issue keys in bulk, set expiry dates, and tag keys to specific policy groups.Creating & Managing Policies
Policies (guardrails) define rules for what the AI proxy will allow, flag, or block. You can create topic restrictions, PII detection rules, jailbreak filters, and output moderation policies.
New Policy
Open Policy Manager
Navigate to /dashboard/policy_perfect_manager.html. The left panel shows all existing policies with their current enabled/disabled toggle. Green toggle = active, grey = disabled.
Click "+ New Policy" and choose an action
Actions determine what happens when the policy triggers: block — reject the request with an explanation; flag — allow but log for review; allow+log — pass through silently; allow+redact — pass but strip matched patterns from the response.
Write your policy rule
In the Policy Editor, define what triggers the policy. You can use keyword lists, regex patterns, semantic similarity topics (e.g. "questions about competitors"), or combine multiple conditions with AND/OR logic. For PII detection, pre-built patterns like SSN, CREDIT_CARD, PASSPORT are available as one-click presets.
Set who it applies to
Policies can target all users, a specific role (e.g. user but not admin), a named group (synced from your SSO groups), or specific API keys. Leave as "All users" for organisation-wide policies.
Save and use the toggle to enable/disable
Click Save Policy. The policy is immediately active if the toggle is on. You can quickly disable any policy without deleting it using the toggle — useful for testing or temporarily suspending a rule.
Testing Compliance
The Compliance Test tool lets you send a sample prompt through the policy engine without making a real AI call — see exactly which policies fire, what action would be taken, and why.
Compliance Test Sandbox
123-45-6789Action: block · Confidence: 98% · Rule:
REGEX: \b\d{3}-\d{2}-\d{4}\b
Passing example
Open the Compliance Test page
Go to /dashboard/intelligent_compliance.html or /dashboard/compliance.html. The Intelligent Compliance page offers a richer test environment with policy reasoning; the basic Compliance page is faster for quick checks.
Type or paste a test prompt
Enter the exact text a user would send. For testing PII policies, include realistic fake data (made-up SSNs like 123-45-6789, fake card numbers, etc.). For topic restriction testing, try prompts that are clearly off-topic.
Select the simulated user role
If your policies apply differently by role (e.g. admins bypass topic restrictions), select the role to simulate. This ensures you're testing the exact policy stack that a real user in that role would experience.
Click "Run Compliance Check" and read the result
A green ALLOWED result means no policies triggered and the request would proceed. A red BLOCKED result shows exactly which policy triggered, what pattern matched, the confidence score, and the action taken.
Tune if you get unexpected results
If a prompt you expect to pass is blocked, click the policy name in the result to jump directly to that policy's editor. Adjust the sensitivity threshold, exclusion list, or rule conditions, then retest. Iterate until the policy behaves correctly.
POST /api/compliance/test to run hundreds of test prompts programmatically as part of a CI pipeline — ensuring policy regressions are caught before deployment.Monitoring the Cache
Smartflow's 4-phase semantic cache stores AI responses and serves identical or semantically similar queries instantly — reducing cost and latency. The Cache Stats page shows you exactly what's hitting and missing.
Cache Layers
Actions
Open Cache Stats
Navigate to /dashboard/cache_stats.html. Stats refresh automatically every 30 seconds. The four headline cards show your overall hit rate, total entries, cumulative token savings, and average latency reduction per hit.
Understand the 4 cache layers
L1 Exact: Byte-identical query → instant hit. L2 Semantic: BERT embedding KNN finds similar-meaning queries above your similarity threshold. L3 Compression: Semantically compressed version of a past response. L4 Predictive: Pre-cached answers for anticipated follow-up questions.
Adjust the similarity threshold
The default is 0.88. Higher values (closer to 1.0) = more conservative matching, fewer false hits. Lower values = more aggressive matching, higher hit rate but risk of serving slightly off-target cached answers. For factual/technical queries, keep at 0.88–0.92. For creative tasks, lower to 0.80.
Flush the cache when needed
Use Flush All Cache after a major knowledge base update so stale answers aren't served. Flush by Model is useful when you upgrade to a new model version — clear only that model's cached responses. Flush by User clears a specific user's cached context if they report stale answers.
/dashboard/mcp_manager.html → Cache tab. This caches MCP tool results independently of AI responses.Trace Logs & Troubleshooting
Every request that passes through the Smartflow proxy generates a trace log entry. This is your primary tool for debugging issues, auditing user activity, and investigating policy decisions.
| Time | User | Model | Status | Tokens | Latency | Policy |
|---|---|---|---|---|---|---|
| 14:32:01 | alice@corp | gpt-4o | BLOCKED | — | 12ms | PII_DETECTION |
| 14:31:44 | bob@corp | claude-3-5-sonnet | CACHED | 342 | 8ms | — |
| 14:31:22 | carol@corp | gpt-4o | LIVE | 1,204 | 2,140ms | — |
| 14:30:58 | dave@corp | gpt-4o-mini | FLAGGED | 88 | 310ms | TOPIC_RESTRICTION |
Open the Traces page
Navigate to /dashboard/traces.html. Requests appear in reverse chronological order. Each row shows the time, authenticated user, model, outcome status, token count, latency, and any triggered policy name.
Understand the status indicators
CACHED Served from cache — no AI call made, very fast.
LIVE Sent to AI provider — normal request.
BLOCKED Rejected by policy — never reached the AI.
FLAGGED Allowed through but logged for review.
ERROR Proxy error or upstream provider error.
Click any row to see the full detail panel
The detail panel shows the exact user identity (including SSO source), the request ID (use this for support tickets), which policy triggered and at what confidence, the processing stage where the request was stopped, and full latency breakdown across each stage.
Key things to look for when troubleshooting
User reports "request blocked": Filter by their email, find the blocked request, check which policy triggered and the matched content.
High latency complaints: Filter for LIVE requests, sort by latency descending — look for outliers over 5s. Check whether they're hitting a slow model or a routing misconfiguration.
Cache not working: Filter for requests from the affected user — if all show LIVE with no CACHED results, check the similarity threshold and ensure the cache is enabled for their policy group.
Wrong user identity shown: The SSO source is shown in the detail. If it shows "unknown" or missing, SSO is not configured or the client isn't sending the identity header.
Use search and filters to narrow results
The search bar accepts a user email, model name, request ID, or partial text. The status dropdown filters to a specific outcome. The time range selector defaults to last 24 hours — extend to "All time" to search historical logs (sourced from both Redis and MongoDB archive).
Common Issues & Fixes
Request blocked unexpectedly
- Find the trace in Traces page
- Note the policy name that triggered
- Go to Policy Manager → find that policy
- Check the confidence threshold — lower it if too aggressive
- Add the specific phrase to the policy's allowlist
- Retest with Compliance Tester
Cache not hitting despite identical questions
- Open Cache Stats → check Similarity Threshold
- Lower threshold from 0.88 to 0.82 and test
- Check if the user's policy group has cache disabled
- Verify Redis is healthy (green on Cache Stats page)
- Check REDIS_URL env var is set correctly in the proxy container
User shows as "unknown" in traces
- Open SSO Config → check if SSO is enabled (green banner)
- Confirm client is sending the
Authorization: Bearer <token>header - For proxy header mode: confirm header name matches config exactly
- Check proxy container logs for
"SSO validation"errors - Re-test SSO connection from SSO Config page
Dashboard shows 0 for Total Requests
- Hard-refresh the browser (Ctrl/Cmd + Shift + R)
- Open browser console → check for failed
/api/vas/logscall - Confirm
REDIS_URLandMONGODB_URLenv vars are set - SSH to server → check
docker logs smartflow-api-server - Verify
vas:total_all_timekey exists in Redis