feat: v3.1 — quota checking, dark UI redesign, registration fixes, daily CI

- Add HEALTHCHECK to Dockerfile, --timeout-keep-alive 75 to uvicorn
- Redesign admin UI: dark theme, DM Sans + JetBrains Mono, grok2api-style
filter tags (All/Active/Inactive/Exhausted), Test/Delete action buttons
- Add Tavily /usage quota checking during healthcheck, per-key quota endpoint
- Add expires_at field to access tokens with automatic expiry enforcement
- Fix registration: add navigation waits after Auth0 login redirect,
navigate to /api-keys page, save screenshot on failure
- Change CI to daily schedule (5 accounts), upload failure screenshots
- Create hf_space/ directory for minimal HF Space deployment
- Update deploy-hf.yml to use hf_space/ directory

Made-with: Cursor

Dockerfile

@@ -0,0 +1,25 @@
+FROM python:3.11-slim
+
+RUN apt-get update && apt-get install -y --no-install-recommends curl libpq-dev && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+RUN pip install \
+    fastapi>=0.104.0 \
+    uvicorn>=0.24.0 \
+    pydantic>=2.0 \
+    requests>=2.31.0 \
+    psycopg2-binary>=2.9.0
+
+COPY manager/ /app/manager/
+COPY entrypoint.sh /app/
+
+RUN mkdir -p /tmp/data && chmod -R 777 /tmp
+RUN chmod +x /app/entrypoint.sh
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=60s --retries=3 \
+    CMD curl -f http://localhost:7860/health || exit 1
+
+EXPOSE 7860
+
+CMD ["/app/entrypoint.sh"]

README.md

@@ -0,0 +1,84 @@
+---
+title: Tavily Key Manager
+emoji: 🔑
+colorFrom: blue
+colorTo: green
+sdk: docker
+app_port: 7860
+pinned: false
+license: mit
+---
+
+```
+████████╗ █████╗ ██╗   ██╗██╗██╗  ██╗   ██╗
+╚══██╔══╝██╔══██╗██║   ██║██║██║  ╚██╗ ██╔╝
+   ██║   ███████║██║   ██║██║██║   ╚████╔╝
+   ██║   ██╔══██║╚██╗ ██╔╝██║██║    ╚██╔╝
+   ██║   ██║  ██║ ╚████╔╝ ██║███████╗██║
+   ╚═╝   ╚═╝  ╚═╝  ╚═══╝  ╚═╝╚══════╝╚═╝
+```
+
+**Tavily Search Proxy & Key Pool Manager**
+
+A managed Tavily API key pool with automatic round-robin selection, health checking, and access token quota system. Drop-in replacement for `api.tavily.com`.
+
+---
+
+## Quick Start
+
+Set your base URL to this Space's address:
+
+```bash
+export TAVILY_BASE_URL=https://ohmyapi-tavily.hf.space
+export TAVILY_API_KEY=sk-your-access-token
+```
+
+### Search
+
+```bash
+curl -X POST https://ohmyapi-tavily.hf.space/v1/search \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer sk-your-access-token" \
+  -d '{"query": "latest AI news", "max_results": 5}'
+```
+
+### Python
+
+```python
+import requests
+
+resp = requests.post(
+    "https://ohmyapi-tavily.hf.space/v1/search",
+    headers={"Authorization": "Bearer sk-your-access-token"},
+    json={"query": "hello world", "max_results": 3}
+)
+print(resp.json())
+```
+
+---
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| Key Pool | Automatic round-robin key selection with health checking |
+| Access Tokens | Per-user tokens with monthly quota management |
+| Free Mode | Optional open access without token |
+| Admin Dashboard | Manage keys, tokens, and configuration via web UI |
+| Search Proxy | `/v1/search` and `/v1/extract` compatible with Tavily API |
+| MCP Support | Works with Tavily MCP server for AI agents |
+
+---
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `ADMIN_PASSWORD` | Yes | Dashboard login password |
+| `DATABASE_URL` | Yes | PostgreSQL connection string |
+| `ADMIN_TOKEN` | No | Default admin API token (default: `REDACTED_TOKEN`) |
+| `FREE_MODE` | No | Enable open access (default: `false`) |
+
+---
+
+Built with FastAPI + PostgreSQL · Powered by [Tavily](https://tavily.com)

entrypoint.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+mkdir -p /tmp/data
+exec python -m uvicorn manager.app:app --host 0.0.0.0 --port 7860 --timeout-keep-alive 75

manager/__init__.py

@@ -0,0 +1 @@
+"""manager package"""

manager/app.py

@@ -0,0 +1,56 @@
+"""FastAPI application for Tavily token management."""
+import os
+import logging
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse, HTMLResponse
+from fastapi.staticfiles import StaticFiles
+
+from . import db
+from .routes import router, proxy_router
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+STATIC_DIR = os.path.join(os.path.dirname(__file__), "static")
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    db.init_db()
+    yield
+
+
+app = FastAPI(title="Tavily Key Manager", version="3.1.0", lifespan=lifespan)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["GET", "POST", "DELETE", "PATCH", "OPTIONS"],
+    allow_headers=["Authorization", "Content-Type"],
+)
+
+app.include_router(router)
+app.include_router(proxy_router)
+
+
+@app.get("/")
+@app.get("/admin")
+@app.get("/admin/{path:path}")
+def index():
+    index_path = os.path.join(STATIC_DIR, "index.html")
+    if os.path.exists(index_path):
+        return FileResponse(index_path)
+    return HTMLResponse("<h1>Tavily Key Manager</h1><p>Dashboard not found.</p>")
+
+
+@app.get("/health")
+def health():
+    stats = db.get_stats()
+    return {"status": "ok", **stats}
+
+
+if os.path.isdir(STATIC_DIR):
+    app.mount("/static", StaticFiles(directory=STATIC_DIR), name="static")

manager/db.py

@@ -0,0 +1,507 @@
+"""Database operations for API key management.
+
+Supports PostgreSQL (via DATABASE_URL) with SQLite fallback for local dev.
+"""
+import os
+import sqlite3
+import logging
+from contextlib import contextmanager
+from datetime import datetime, timezone
+
+logger = logging.getLogger(__name__)
+
+DATABASE_URL = os.getenv("DATABASE_URL", "")
+DB_PATH = os.getenv("DB_PATH", "/tmp/data/tavily_keys.db")
+
+_use_pg = bool(DATABASE_URL)
+
+if _use_pg:
+    import psycopg2
+    import psycopg2.extras
+
+
+def _ensure_dir():
+    if not _use_pg:
+        os.makedirs(os.path.dirname(DB_PATH), exist_ok=True)
+
+
+@contextmanager
+def get_db():
+    if _use_pg:
+        conn = psycopg2.connect(DATABASE_URL)
+        conn.autocommit = False
+        try:
+            yield conn
+            conn.commit()
+        except Exception:
+            conn.rollback()
+            raise
+        finally:
+            conn.close()
+    else:
+        _ensure_dir()
+        conn = sqlite3.connect(DB_PATH)
+        conn.row_factory = sqlite3.Row
+        conn.execute("PRAGMA journal_mode=WAL")
+        try:
+            yield conn
+            conn.commit()
+        except Exception:
+            conn.rollback()
+            raise
+        finally:
+            conn.close()
+
+
+def _execute(conn, sql, params=None):
+    if _use_pg:
+        cur = conn.cursor(cursor_factory=psycopg2.extras.RealDictCursor)
+    else:
+        cur = conn.cursor()
+    cur.execute(sql, params or ())
+    return cur
+
+
+def _fetchall(conn, sql, params=None):
+    cur = _execute(conn, sql, params)
+    rows = cur.fetchall()
+    return [dict(r) for r in rows]
+
+
+def _fetchone(conn, sql, params=None):
+    cur = _execute(conn, sql, params)
+    row = cur.fetchone()
+    if row is None:
+        return None
+    return dict(row)
+
+
+def _sql(template):
+    """Convert SQL template: replace ? with %s for PostgreSQL."""
+    if _use_pg:
+        return template.replace("?", "%s")
+    return template
+
+
+# ── Initialization ──
+
+def init_db():
+    with get_db() as conn:
+        if _use_pg:
+            _execute(conn, """
+                CREATE TABLE IF NOT EXISTS api_keys (
+                    id SERIAL PRIMARY KEY,
+                    email TEXT NOT NULL,
+                    password TEXT DEFAULT '',
+                    api_key TEXT NOT NULL UNIQUE,
+                    status TEXT DEFAULT 'active',
+                    created_at TEXT NOT NULL,
+                    last_checked TEXT,
+                    quota_remaining INTEGER,
+                    use_count INTEGER DEFAULT 0
+                )
+            """)
+            _execute(conn, """
+                CREATE TABLE IF NOT EXISTS meta (
+                    key TEXT PRIMARY KEY,
+                    value TEXT
+                )
+            """)
+            _execute(conn, """
+                CREATE TABLE IF NOT EXISTS access_tokens (
+                    id SERIAL PRIMARY KEY,
+                    token TEXT NOT NULL UNIQUE,
+                    name TEXT DEFAULT '',
+                    quota_limit INTEGER DEFAULT 1000,
+                    quota_used INTEGER DEFAULT 0,
+                    is_admin BOOLEAN DEFAULT FALSE,
+                    status TEXT DEFAULT 'active',
+                    created_at TEXT NOT NULL,
+                    last_used TEXT,
+                    expires_at TEXT
+                )
+            """)
+            _execute(conn, """
+                CREATE TABLE IF NOT EXISTS config (
+                    key TEXT PRIMARY KEY,
+                    value TEXT NOT NULL
+                )
+            """)
+        else:
+            _execute(conn, """
+                CREATE TABLE IF NOT EXISTS api_keys (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    email TEXT NOT NULL,
+                    password TEXT DEFAULT '',
+                    api_key TEXT NOT NULL UNIQUE,
+                    status TEXT DEFAULT 'active',
+                    created_at TEXT NOT NULL,
+                    last_checked TEXT,
+                    quota_remaining INTEGER,
+                    use_count INTEGER DEFAULT 0
+                )
+            """)
+            _execute(conn, """
+                CREATE TABLE IF NOT EXISTS meta (
+                    key TEXT PRIMARY KEY,
+                    value TEXT
+                )
+            """)
+            _execute(conn, """
+                CREATE TABLE IF NOT EXISTS access_tokens (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    token TEXT NOT NULL UNIQUE,
+                    name TEXT DEFAULT '',
+                    quota_limit INTEGER DEFAULT 1000,
+                    quota_used INTEGER DEFAULT 0,
+                    is_admin INTEGER DEFAULT 0,
+                    status TEXT DEFAULT 'active',
+                    created_at TEXT NOT NULL,
+                    last_used TEXT,
+                    expires_at TEXT
+                )
+            """)
+            _execute(conn, """
+                CREATE TABLE IF NOT EXISTS config (
+                    key TEXT PRIMARY KEY,
+                    value TEXT NOT NULL
+                )
+            """)
+
+    # Migrations
+    for col, default in [("use_count", "0"), ("quota_remaining", "NULL")]:
+        try:
+            with get_db() as conn:
+                if _use_pg:
+                    _execute(conn, f"ALTER TABLE api_keys ADD COLUMN IF NOT EXISTS {col} INTEGER DEFAULT {default}")
+                else:
+                    _execute(conn, f"ALTER TABLE api_keys ADD COLUMN {col} INTEGER DEFAULT {default}")
+        except Exception:
+            pass
+
+    for tbl, col, coltype, default in [("access_tokens", "expires_at", "TEXT", "NULL")]:
+        try:
+            with get_db() as conn:
+                if _use_pg:
+                    _execute(conn, f"ALTER TABLE {tbl} ADD COLUMN IF NOT EXISTS {col} {coltype} DEFAULT {default}")
+                else:
+                    _execute(conn, f"ALTER TABLE {tbl} ADD COLUMN {col} {coltype} DEFAULT {default}")
+        except Exception:
+            pass
+
+    _seed_defaults()
+    db_type = "PostgreSQL" if _use_pg else f"SQLite ({DB_PATH})"
+    logger.info("Database initialized: %s", db_type)
+
+
+def _seed_defaults():
+    """Seed default config values and admin token if not present."""
+    defaults = {
+        "admin_password": os.getenv("ADMIN_PASSWORD", ""),
+        "admin_token": os.getenv("ADMIN_TOKEN", "REDACTED_TOKEN"),
+        "free_mode": os.getenv("FREE_MODE", "false"),
+        "default_quota": os.getenv("DEFAULT_QUOTA", "1000"),
+    }
+    with get_db() as conn:
+        for k, v in defaults.items():
+            existing = _fetchone(conn, _sql("SELECT value FROM config WHERE key = ?"), (k,))
+            if not existing:
+                if _use_pg:
+                    _execute(conn, "INSERT INTO config (key, value) VALUES (%s, %s) ON CONFLICT (key) DO NOTHING", (k, v))
+                else:
+                    _execute(conn, "INSERT OR IGNORE INTO config (key, value) VALUES (?, ?)", (k, v))
+
+    # Ensure admin token exists
+    admin_token = get_config("admin_token")
+    if admin_token:
+        with get_db() as conn:
+            existing = _fetchone(conn, _sql("SELECT id FROM access_tokens WHERE token = ?"), (admin_token,))
+            if not existing:
+                now = datetime.now(timezone.utc).isoformat()
+                if _use_pg:
+                    _execute(conn,
+                        "INSERT INTO access_tokens (token, name, quota_limit, quota_used, is_admin, status, created_at) "
+                        "VALUES (%s, %s, %s, %s, %s, %s, %s) ON CONFLICT (token) DO NOTHING",
+                        (admin_token, "Admin", 0, 0, True, "active", now))
+                else:
+                    _execute(conn,
+                        "INSERT OR IGNORE INTO access_tokens (token, name, quota_limit, quota_used, is_admin, status, created_at) "
+                        "VALUES (?, ?, ?, ?, ?, ?, ?)",
+                        (admin_token, "Admin", 0, 0, 1, "active", now))
+
+
+# ── API Key CRUD ──
+
+def add_key(email: str, password: str, api_key: str, created_at: str = "") -> int:
+    if not created_at:
+        created_at = datetime.now(timezone.utc).isoformat()
+    with get_db() as conn:
+        if _use_pg:
+            cur = _execute(conn,
+                "INSERT INTO api_keys (email, password, api_key, created_at) VALUES (%s, %s, %s, %s) RETURNING id",
+                (email, password, api_key, created_at))
+            return cur.fetchone()["id"]
+        else:
+            cur = _execute(conn,
+                "INSERT INTO api_keys (email, password, api_key, created_at) VALUES (?, ?, ?, ?)",
+                (email, password, api_key, created_at))
+            return cur.lastrowid
+
+
+def add_keys_batch(keys: list[dict]) -> int:
+    added = 0
+    with get_db() as conn:
+        for k in keys:
+            try:
+                created = k.get("created_at", datetime.now(timezone.utc).isoformat())
+                if _use_pg:
+                    _execute(conn,
+                        "INSERT INTO api_keys (email, password, api_key, created_at) "
+                        "VALUES (%s, %s, %s, %s) ON CONFLICT (api_key) DO NOTHING",
+                        (k["email"], k.get("password", ""), k["api_key"], created))
+                else:
+                    _execute(conn,
+                        "INSERT OR IGNORE INTO api_keys (email, password, api_key, created_at) "
+                        "VALUES (?, ?, ?, ?)",
+                        (k["email"], k.get("password", ""), k["api_key"], created))
+                added += 1
+            except Exception:
+                pass
+    return added
+
+
+def list_keys(status: str = "") -> list[dict]:
+    with get_db() as conn:
+        if status:
+            return _fetchall(conn, _sql(
+                "SELECT * FROM api_keys WHERE status = ? ORDER BY id DESC"), (status,))
+        return _fetchall(conn, "SELECT * FROM api_keys ORDER BY id DESC")
+
+
+def get_key(key_id: int) -> dict | None:
+    with get_db() as conn:
+        return _fetchone(conn, _sql("SELECT * FROM api_keys WHERE id = ?"), (key_id,))
+
+
+def delete_key(key_id: int) -> bool:
+    with get_db() as conn:
+        cur = _execute(conn, _sql("DELETE FROM api_keys WHERE id = ?"), (key_id,))
+        return cur.rowcount > 0
+
+
+def delete_keys_batch(key_ids: list[int]) -> int:
+    if not key_ids:
+        return 0
+    with get_db() as conn:
+        if _use_pg:
+            cur = _execute(conn, "DELETE FROM api_keys WHERE id = ANY(%s)", (key_ids,))
+        else:
+            placeholders = ",".join("?" for _ in key_ids)
+            cur = _execute(conn, f"DELETE FROM api_keys WHERE id IN ({placeholders})", tuple(key_ids))
+        return cur.rowcount
+
+
+def delete_keys_by_status(statuses: list[str]) -> int:
+    if not statuses:
+        return 0
+    with get_db() as conn:
+        if _use_pg:
+            placeholders = ",".join("%s" for _ in statuses)
+        else:
+            placeholders = ",".join("?" for _ in statuses)
+        cur = _execute(conn,
+            f"DELETE FROM api_keys WHERE status IN ({placeholders})", tuple(statuses))
+        return cur.rowcount
+
+
+def update_status(key_id: int, status: str, quota_remaining: int | None = None):
+    now = datetime.now(timezone.utc).isoformat()
+    with get_db() as conn:
+        if quota_remaining is not None:
+            _execute(conn, _sql(
+                "UPDATE api_keys SET status = ?, last_checked = ?, quota_remaining = ? WHERE id = ?"
+            ), (status, now, quota_remaining, key_id))
+        else:
+            _execute(conn, _sql(
+                "UPDATE api_keys SET status = ?, last_checked = ? WHERE id = ?"
+            ), (status, now, key_id))
+
+
+def update_status_batch(key_ids: list[int], status: str) -> int:
+    if not key_ids:
+        return 0
+    now = datetime.now(timezone.utc).isoformat()
+    with get_db() as conn:
+        if _use_pg:
+            cur = _execute(conn,
+                "UPDATE api_keys SET status = %s, last_checked = %s WHERE id = ANY(%s)",
+                (status, now, key_ids))
+        else:
+            placeholders = ",".join("?" for _ in key_ids)
+            cur = _execute(conn,
+                f"UPDATE api_keys SET status = ?, last_checked = ? WHERE id IN ({placeholders})",
+                (status, now, *key_ids))
+        return cur.rowcount
+
+
+def get_next_active_key() -> dict | None:
+    """Get the least-recently-checked active key (round-robin) and increment use_count."""
+    with get_db() as conn:
+        row = _fetchone(conn,
+            "SELECT * FROM api_keys WHERE status = 'active' "
+            "ORDER BY last_checked ASC NULLS FIRST LIMIT 1")
+        if row:
+            now = datetime.now(timezone.utc).isoformat()
+            _execute(conn, _sql(
+                "UPDATE api_keys SET last_checked = ?, use_count = COALESCE(use_count, 0) + 1 WHERE id = ?"
+            ), (now, row["id"]))
+            return row
+        return None
+
+
+def get_stats() -> dict:
+    with get_db() as conn:
+        total = _fetchone(conn, "SELECT COUNT(*) as cnt FROM api_keys")["cnt"]
+        active = _fetchone(conn, "SELECT COUNT(*) as cnt FROM api_keys WHERE status='active'")["cnt"]
+        inactive = _fetchone(conn, "SELECT COUNT(*) as cnt FROM api_keys WHERE status='inactive'")["cnt"]
+        exhausted = _fetchone(conn, "SELECT COUNT(*) as cnt FROM api_keys WHERE status='exhausted'")["cnt"]
+        total_usage = _fetchone(conn, "SELECT COALESCE(SUM(use_count), 0) as cnt FROM api_keys")["cnt"]
+        quota_sum = _fetchone(conn,
+            "SELECT COALESCE(SUM(quota_remaining), 0) as cnt FROM api_keys "
+            "WHERE status='active' AND quota_remaining IS NOT NULL")["cnt"]
+        last_reg = _fetchone(conn, "SELECT created_at FROM api_keys ORDER BY id DESC LIMIT 1")
+        last_check = _fetchone(conn, "SELECT value FROM meta WHERE key='last_healthcheck'")
+        return {
+            "total_keys": total,
+            "active_keys": active,
+            "inactive_keys": inactive,
+            "exhausted_keys": exhausted,
+            "total_usage": total_usage,
+            "total_quota_remaining": quota_sum if quota_sum else None,
+            "last_registration": last_reg["created_at"] if last_reg else None,
+            "last_healthcheck": last_check["value"] if last_check else None,
+        }
+
+
+def set_meta(key: str, value: str):
+    with get_db() as conn:
+        if _use_pg:
+            _execute(conn,
+                "INSERT INTO meta (key, value) VALUES (%s, %s) "
+                "ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value",
+                (key, value))
+        else:
+            _execute(conn, "INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)", (key, value))
+
+
+def export_all_keys() -> list[dict]:
+    with get_db() as conn:
+        return _fetchall(conn,
+            "SELECT email, password, api_key, status, created_at, last_checked, "
+            "COALESCE(use_count, 0) as use_count FROM api_keys ORDER BY id")
+
+
+# ── Access Token CRUD ──
+
+def add_access_token(token: str, name: str = "", quota_limit: int = 1000,
+                     is_admin: bool = False, expires_at: str | None = None) -> int:
+    now = datetime.now(timezone.utc).isoformat()
+    with get_db() as conn:
+        if _use_pg:
+            cur = _execute(conn,
+                "INSERT INTO access_tokens (token, name, quota_limit, is_admin, status, created_at, expires_at) "
+                "VALUES (%s, %s, %s, %s, %s, %s, %s) RETURNING id",
+                (token, name, quota_limit, is_admin, "active", now, expires_at))
+            return cur.fetchone()["id"]
+        else:
+            cur = _execute(conn,
+                "INSERT INTO access_tokens (token, name, quota_limit, is_admin, status, created_at, expires_at) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?)",
+                (token, name, quota_limit, 1 if is_admin else 0, "active", now, expires_at))
+            return cur.lastrowid
+
+
+def list_access_tokens() -> list[dict]:
+    with get_db() as conn:
+        rows = _fetchall(conn, "SELECT * FROM access_tokens ORDER BY id")
+        for r in rows:
+            r["is_admin"] = bool(r.get("is_admin"))
+        return rows
+
+
+def get_access_token(token: str) -> dict | None:
+    with get_db() as conn:
+        row = _fetchone(conn, _sql("SELECT * FROM access_tokens WHERE token = ? AND status = 'active'"), (token,))
+        if row:
+            row["is_admin"] = bool(row.get("is_admin"))
+            exp = row.get("expires_at")
+            if exp:
+                try:
+                    if datetime.fromisoformat(exp.replace("Z", "+00:00")) < datetime.now(timezone.utc):
+                        return None
+                except ValueError:
+                    pass
+        return row
+
+
+def delete_access_token(token_id: int) -> bool:
+    with get_db() as conn:
+        cur = _execute(conn, _sql("DELETE FROM access_tokens WHERE id = ?"), (token_id,))
+        return cur.rowcount > 0
+
+
+def update_access_token(token_id: int, **kwargs) -> bool:
+    allowed = {"name", "quota_limit", "status", "expires_at"}
+    updates = {k: v for k, v in kwargs.items() if k in allowed}
+    if not updates:
+        return False
+    with get_db() as conn:
+        if _use_pg:
+            set_clause = ", ".join(f"{k} = %s" for k in updates)
+            _execute(conn, f"UPDATE access_tokens SET {set_clause} WHERE id = %s",
+                     (*updates.values(), token_id))
+        else:
+            set_clause = ", ".join(f"{k} = ?" for k in updates)
+            _execute(conn, f"UPDATE access_tokens SET {set_clause} WHERE id = ?",
+                     (*updates.values(), token_id))
+        return True
+
+
+def increment_token_usage(token: str) -> bool:
+    now = datetime.now(timezone.utc).isoformat()
+    with get_db() as conn:
+        cur = _execute(conn, _sql(
+            "UPDATE access_tokens SET quota_used = quota_used + 1, last_used = ? WHERE token = ?"),
+            (now, token))
+        return cur.rowcount > 0
+
+
+def reset_token_usage(token_id: int) -> bool:
+    with get_db() as conn:
+        cur = _execute(conn, _sql("UPDATE access_tokens SET quota_used = 0 WHERE id = ?"), (token_id,))
+        return cur.rowcount > 0
+
+
+# ── Config ──
+
+def get_config(key: str) -> str | None:
+    with get_db() as conn:
+        row = _fetchone(conn, _sql("SELECT value FROM config WHERE key = ?"), (key,))
+        return row["value"] if row else None
+
+
+def set_config(key: str, value: str):
+    with get_db() as conn:
+        if _use_pg:
+            _execute(conn,
+                "INSERT INTO config (key, value) VALUES (%s, %s) "
+                "ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value",
+                (key, value))
+        else:
+            _execute(conn, "INSERT OR REPLACE INTO config (key, value) VALUES (?, ?)", (key, value))
+
+
+def get_all_config() -> dict:
+    with get_db() as conn:
+        rows = _fetchall(conn, "SELECT key, value FROM config ORDER BY key")
+        return {r["key"]: r["value"] for r in rows}

manager/models.py

@@ -0,0 +1,97 @@
+"""Pydantic models for the token manager API."""
+from pydantic import BaseModel
+
+
+# ── API Key models ──
+
+class ApiKeyCreate(BaseModel):
+    email: str
+    password: str = ""
+    api_key: str
+    created_at: str = ""
+
+
+class ApiKeyImport(BaseModel):
+    keys: list[ApiKeyCreate]
+
+
+class ApiKeyResponse(BaseModel):
+    id: int
+    email: str
+    password: str
+    api_key: str
+    status: str
+    created_at: str
+    last_checked: str | None = None
+    quota_remaining: int | None = None
+    use_count: int | None = 0
+
+
+class ApiKeyListResponse(BaseModel):
+    total: int
+    active: int
+    keys: list[ApiKeyResponse]
+
+
+class StatsResponse(BaseModel):
+    total_keys: int
+    active_keys: int
+    inactive_keys: int
+    exhausted_keys: int
+    total_usage: int = 0
+    total_quota_remaining: int | None = None
+    last_registration: str | None = None
+    last_healthcheck: str | None = None
+
+
+class HealthCheckResult(BaseModel):
+    id: int
+    api_key: str
+    status: str
+    message: str
+    quota_remaining: int | None = None
+
+
+class BatchIds(BaseModel):
+    ids: list[int]
+
+
+class BatchStatus(BaseModel):
+    ids: list[int]
+    status: str
+
+
+# ── Access Token models ──
+
+class AccessTokenCreate(BaseModel):
+    name: str = ""
+    token: str = ""
+    quota_limit: int = 1000
+    is_admin: bool = False
+    expires_at: str | None = None
+
+
+class AccessTokenUpdate(BaseModel):
+    name: str | None = None
+    quota_limit: int | None = None
+    status: str | None = None
+    expires_at: str | None = None
+
+
+class AccessTokenResponse(BaseModel):
+    id: int
+    token: str
+    name: str
+    quota_limit: int
+    quota_used: int
+    is_admin: bool
+    status: str
+    created_at: str
+    last_used: str | None = None
+    expires_at: str | None = None
+
+
+# ── Config models ──
+
+class ConfigUpdate(BaseModel):
+    configs: dict[str, str]

manager/routes.py

@@ -0,0 +1,379 @@
+"""API routes for the token manager."""
+import os
+import secrets
+import string
+from datetime import datetime, timezone
+
+import requests
+from fastapi import APIRouter, Depends, HTTPException, Header, Request
+from fastapi.responses import JSONResponse
+
+from . import db
+from .models import (
+    ApiKeyCreate, ApiKeyImport, ApiKeyResponse, ApiKeyListResponse,
+    StatsResponse, HealthCheckResult, BatchIds, BatchStatus,
+    AccessTokenCreate, AccessTokenUpdate, AccessTokenResponse,
+    ConfigUpdate,
+)
+
+router = APIRouter(prefix="/api")
+proxy_router = APIRouter()
+
+ADMIN_PASSWORD = os.getenv("ADMIN_PASSWORD", "")
+
+
+def verify_auth(authorization: str = Header(None)):
+    """Verify admin auth via password or admin token."""
+    admin_pw = db.get_config("admin_password") or ADMIN_PASSWORD
+    if not admin_pw:
+        raise HTTPException(500, "ADMIN_PASSWORD not configured")
+    if not authorization:
+        raise HTTPException(401, "Authorization required")
+    token = authorization.removeprefix("Bearer ").strip()
+    if secrets.compare_digest(token, admin_pw):
+        return True
+    admin_token_val = db.get_config("admin_token") or ""
+    if admin_token_val and secrets.compare_digest(token, admin_token_val):
+        return True
+    raise HTTPException(403, "Invalid credentials")
+
+
+def _generate_token() -> str:
+    chars = string.ascii_letters + string.digits
+    return "sk-" + ''.join(secrets.choice(chars) for _ in range(24))
+
+
+# ── Key Management ──
+
+@router.post("/keys", response_model=ApiKeyResponse)
+def create_key(body: ApiKeyCreate, _=Depends(verify_auth)):
+    try:
+        key_id = db.add_key(body.email, body.password, body.api_key, body.created_at)
+    except Exception as e:
+        raise HTTPException(409, f"Key already exists: {e}")
+    row = db.get_key(key_id)
+    return row
+
+
+@router.post("/keys/import")
+def import_keys(body: ApiKeyImport, _=Depends(verify_auth)):
+    keys = [k.model_dump() for k in body.keys]
+    added = db.add_keys_batch(keys)
+    return {"imported": added, "total": len(keys)}
+
+
+@router.get("/keys/export")
+def export_keys(_=Depends(verify_auth)):
+    keys = db.export_all_keys()
+    return JSONResponse(content=keys, headers={
+        "Content-Disposition": "attachment; filename=tavily-keys-export.json"
+    })
+
+
+@router.get("/keys", response_model=ApiKeyListResponse)
+def list_keys(status: str = "", _=Depends(verify_auth)):
+    keys = db.list_keys(status)
+    active = sum(1 for k in keys if k["status"] == "active")
+    return {"total": len(keys), "active": active, "keys": keys}
+
+
+@router.delete("/keys/{key_id}")
+def delete_key(key_id: int, _=Depends(verify_auth)):
+    if not db.delete_key(key_id):
+        raise HTTPException(404, "Key not found")
+    return {"deleted": True}
+
+
+@router.get("/keys/next")
+def get_next_key(_=Depends(verify_auth)):
+    key = db.get_next_active_key()
+    if not key:
+        raise HTTPException(404, "No active keys available")
+    return {"api_key": key["api_key"], "email": key["email"]}
+
+
+@router.post("/keys/{key_id}/check", response_model=HealthCheckResult)
+def check_single_key(key_id: int, _=Depends(verify_auth)):
+    row = db.get_key(key_id)
+    if not row:
+        raise HTTPException(404, "Key not found")
+    status, msg, quota = _check_tavily_key(row["api_key"])
+    db.update_status(key_id, status, quota_remaining=quota)
+    return {"id": key_id, "api_key": row["api_key"], "status": status, "message": msg, "quota_remaining": quota}
+
+
+@router.post("/keys/healthcheck")
+def healthcheck_all(_=Depends(verify_auth)):
+    keys = db.list_keys()
+    results = []
+    for row in keys:
+        status, msg, quota = _check_tavily_key(row["api_key"])
+        db.update_status(row["id"], status, quota_remaining=quota)
+        results.append({
+            "id": row["id"],
+            "api_key": row["api_key"],
+            "status": status,
+            "message": msg,
+            "quota_remaining": quota,
+        })
+    db.set_meta("last_healthcheck", datetime.now(timezone.utc).isoformat())
+    active = sum(1 for r in results if r["status"] == "active")
+    return {"checked": len(results), "active": active, "results": results}
+
+
+@router.get("/keys/{key_id}/quota")
+def get_key_quota(key_id: int, _=Depends(verify_auth)):
+    row = db.get_key(key_id)
+    if not row:
+        raise HTTPException(404, "Key not found")
+    quota = _fetch_tavily_quota(row["api_key"])
+    if quota is not None:
+        db.update_status(key_id, row["status"], quota_remaining=quota)
+    return {"id": key_id, "api_key": row["api_key"], "quota_remaining": quota}
+
+
+@router.get("/stats", response_model=StatsResponse)
+def get_stats(_=Depends(verify_auth)):
+    return db.get_stats()
+
+
+# ── Batch Operations ──
+
+@router.post("/keys/batch-delete")
+def batch_delete(body: BatchIds, _=Depends(verify_auth)):
+    deleted = db.delete_keys_batch(body.ids)
+    return {"deleted": deleted}
+
+
+@router.post("/keys/batch-status")
+def batch_status(body: BatchStatus, _=Depends(verify_auth)):
+    if body.status not in ("active", "inactive", "exhausted"):
+        raise HTTPException(400, "Invalid status")
+    updated = db.update_status_batch(body.ids, body.status)
+    return {"updated": updated}
+
+
+@router.post("/keys/batch-check")
+def batch_check(body: BatchIds, _=Depends(verify_auth)):
+    results = []
+    for key_id in body.ids:
+        row = db.get_key(key_id)
+        if not row:
+            continue
+        status, msg, quota = _check_tavily_key(row["api_key"])
+        db.update_status(key_id, status, quota_remaining=quota)
+        results.append({"id": key_id, "api_key": row["api_key"], "status": status, "message": msg, "quota_remaining": quota})
+    db.set_meta("last_healthcheck", datetime.now(timezone.utc).isoformat())
+    active = sum(1 for r in results if r["status"] == "active")
+    return {"checked": len(results), "active": active, "results": results}
+
+
+@router.delete("/keys/inactive")
+def delete_inactive(_=Depends(verify_auth)):
+    deleted = db.delete_keys_by_status(["inactive", "exhausted"])
+    return {"deleted": deleted}
+
+
+# ── Access Token Management ──
+
+@router.get("/tokens")
+def list_tokens(_=Depends(verify_auth)):
+    return db.list_access_tokens()
+
+
+@router.post("/tokens")
+def create_token(body: AccessTokenCreate, _=Depends(verify_auth)):
+    token_str = body.token or _generate_token()
+    default_quota = int(db.get_config("default_quota") or "1000")
+    quota = body.quota_limit if body.quota_limit != 1000 else default_quota
+    try:
+        token_id = db.add_access_token(token_str, body.name, quota, body.is_admin, body.expires_at)
+    except Exception as e:
+        raise HTTPException(409, f"Token already exists: {e}")
+    return {"id": token_id, "token": token_str}
+
+
+@router.patch("/tokens/{token_id}")
+def update_token(token_id: int, body: AccessTokenUpdate, _=Depends(verify_auth)):
+    updates = {k: v for k, v in body.model_dump().items() if v is not None}
+    if not updates:
+        raise HTTPException(400, "No fields to update")
+    db.update_access_token(token_id, **updates)
+    return {"updated": True}
+
+
+@router.delete("/tokens/{token_id}")
+def delete_token(token_id: int, _=Depends(verify_auth)):
+    if not db.delete_access_token(token_id):
+        raise HTTPException(404, "Token not found")
+    return {"deleted": True}
+
+
+@router.post("/tokens/{token_id}/reset")
+def reset_usage(token_id: int, _=Depends(verify_auth)):
+    db.reset_token_usage(token_id)
+    return {"reset": True}
+
+
+# ── Config Management ──
+
+@router.get("/config")
+def get_config(_=Depends(verify_auth)):
+    return db.get_all_config()
+
+
+@router.patch("/config")
+def update_config(body: ConfigUpdate, _=Depends(verify_auth)):
+    for k, v in body.configs.items():
+        db.set_config(k, v)
+    return {"updated": list(body.configs.keys())}
+
+
+# ── Tavily Search Proxy (OpenClaw compatible) ──
+
+def _verify_proxy_auth(request: Request) -> dict | None:
+    """Verify access token for proxy endpoints. Returns token row or None."""
+    free_mode = (db.get_config("free_mode") or "false").lower() == "true"
+    auth_header = request.headers.get("authorization", "")
+    bearer = auth_header.removeprefix("Bearer ").strip() if auth_header else ""
+
+    if free_mode:
+        if bearer:
+            token_row = db.get_access_token(bearer)
+            if token_row:
+                return token_row
+        return {"token": "__free__", "is_admin": False, "quota_limit": 0, "quota_used": 0}
+
+    if not bearer:
+        return None
+
+    token_row = db.get_access_token(bearer)
+    return token_row
+
+
+@proxy_router.post("/v1/search")
+@proxy_router.post("/search")
+async def proxy_tavily_search(request: Request):
+    token_row = _verify_proxy_auth(request)
+    if token_row is None:
+        return JSONResponse(status_code=401, content={"error": "Valid access token required. Set Authorization: Bearer <token>"})
+
+    if not token_row.get("is_admin") and token_row.get("quota_limit", 0) > 0:
+        if token_row.get("quota_used", 0) >= token_row["quota_limit"]:
+            return JSONResponse(status_code=429, content={"error": "Token quota exceeded"})
+
+    key_row = db.get_next_active_key()
+    if not key_row:
+        return JSONResponse(status_code=503, content={"error": "No active API keys in pool"})
+
+    try:
+        body = await request.json()
+    except Exception:
+        return JSONResponse(status_code=400, content={"error": "Invalid JSON body"})
+
+    body["api_key"] = key_row["api_key"]
+
+    try:
+        resp = requests.post("https://api.tavily.com/search", json=body, timeout=30)
+        if resp.status_code == 401:
+            db.update_status(key_row["id"], "inactive")
+        elif resp.status_code == 429:
+            db.update_status(key_row["id"], "exhausted")
+
+        if resp.status_code == 200 and token_row.get("token") != "__free__":
+            db.increment_token_usage(token_row["token"])
+
+        return JSONResponse(
+            status_code=resp.status_code,
+            content=resp.json() if resp.headers.get("content-type", "").startswith("application/json") else {"raw": resp.text},
+        )
+    except requests.Timeout:
+        return JSONResponse(status_code=504, content={"error": "Tavily API timeout"})
+    except Exception as e:
+        return JSONResponse(status_code=502, content={"error": f"Proxy error: {e}"})
+
+
+@proxy_router.post("/v1/extract")
+@proxy_router.post("/extract")
+async def proxy_tavily_extract(request: Request):
+    token_row = _verify_proxy_auth(request)
+    if token_row is None:
+        return JSONResponse(status_code=401, content={"error": "Valid access token required. Set Authorization: Bearer <token>"})
+
+    if not token_row.get("is_admin") and token_row.get("quota_limit", 0) > 0:
+        if token_row.get("quota_used", 0) >= token_row["quota_limit"]:
+            return JSONResponse(status_code=429, content={"error": "Token quota exceeded"})
+
+    key_row = db.get_next_active_key()
+    if not key_row:
+        return JSONResponse(status_code=503, content={"error": "No active API keys in pool"})
+
+    try:
+        body = await request.json()
+    except Exception:
+        return JSONResponse(status_code=400, content={"error": "Invalid JSON body"})
+
+    body["api_key"] = key_row["api_key"]
+
+    try:
+        resp = requests.post("https://api.tavily.com/extract", json=body, timeout=30)
+        if resp.status_code == 401:
+            db.update_status(key_row["id"], "inactive")
+        elif resp.status_code == 429:
+            db.update_status(key_row["id"], "exhausted")
+
+        if resp.status_code == 200 and token_row.get("token") != "__free__":
+            db.increment_token_usage(token_row["token"])
+
+        return JSONResponse(
+            status_code=resp.status_code,
+            content=resp.json() if resp.headers.get("content-type", "").startswith("application/json") else {"raw": resp.text},
+        )
+    except requests.Timeout:
+        return JSONResponse(status_code=504, content={"error": "Tavily API timeout"})
+    except Exception as e:
+        return JSONResponse(status_code=502, content={"error": f"Proxy error: {e}"})
+
+
+def _check_tavily_key(api_key: str) -> tuple[str, str, int | None]:
+    """Check key validity and return (status, message, quota_remaining)."""
+    quota_remaining = None
+    try:
+        resp = requests.post(
+            "https://api.tavily.com/search",
+            json={"api_key": api_key, "query": "test", "max_results": 1},
+            timeout=15,
+        )
+        if resp.status_code == 200:
+            quota_remaining = _fetch_tavily_quota(api_key)
+            return "active", "OK", quota_remaining
+        elif resp.status_code == 401:
+            return "inactive", "Invalid key", None
+        elif resp.status_code == 429:
+            return "exhausted", "Rate limited / quota exceeded", 0
+        else:
+            return "inactive", f"HTTP {resp.status_code}: {resp.text[:100]}", None
+    except requests.Timeout:
+        return "active", "Timeout (assumed active)", quota_remaining
+    except Exception as e:
+        return "unknown", f"Check error: {e}", None
+
+
+def _fetch_tavily_quota(api_key: str) -> int | None:
+    """Fetch remaining quota from Tavily /usage endpoint."""
+    try:
+        resp = requests.get(
+            "https://api.tavily.com/usage",
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=10,
+        )
+        if resp.status_code == 200:
+            data = resp.json()
+            key_data = data.get("key", {})
+            limit = key_data.get("limit")
+            usage = key_data.get("usage", 0)
+            if limit is not None:
+                return max(0, limit - usage)
+    except Exception:
+        pass
+    return None

manager/static/index.html

@@ -0,0 +1,910 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Tavily Key Manager</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link href="https://fonts.googleapis.com/css2?family=DM+Sans:ital,opsz,wght@0,9..40,400;0,9..40,500;0,9..40,600;0,9..40,700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
+    <style>
+        *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+        :root {
+            --bg: #0a0a0b; --bg2: #111113; --surface: #18181b; --surface2: #1e1e22;
+            --border: #27272a; --border2: #3f3f46;
+            --fg: #fafafa; --fg2: #d4d4d8; --fg3: #a1a1aa; --fg4: #71717a; --fg5: #52525b;
+            --accent: #3b82f6; --accent2: #60a5fa; --accent-bg: rgba(59,130,246,.12);
+            --ok: #22c55e; --ok-bg: rgba(34,197,94,.1); --ok-dim: #16a34a;
+            --err: #ef4444; --err-bg: rgba(239,68,68,.1); --err-dim: #dc2626;
+            --warn: #f59e0b; --warn-bg: rgba(245,158,11,.1);
+            --r: 8px; --rl: 12px;
+            --font: 'DM Sans', -apple-system, sans-serif;
+            --mono: 'JetBrains Mono', 'SF Mono', monospace;
+        }
+        html { font-size: 15px; }
+        body { background: var(--bg); color: var(--fg); font-family: var(--font); line-height: 1.6; min-height: 100vh; -webkit-font-smoothing: antialiased; }
+        ::selection { background: var(--accent); color: #fff; }
+        ::-webkit-scrollbar { width: 6px; height: 6px; }
+        ::-webkit-scrollbar-track { background: transparent; }
+        ::-webkit-scrollbar-thumb { background: var(--border2); border-radius: 3px; }
+
+        /* ── Login ── */
+        .login-wrap { display: flex; align-items: center; justify-content: center; min-height: 100vh; padding: 24px; background: radial-gradient(ellipse at 50% 0%, rgba(59,130,246,.06) 0%, transparent 60%); }
+        .login-card { width: 100%; max-width: 380px; animation: rise .5s ease both; }
+        .login-hdr { text-align: center; margin-bottom: 40px; }
+        .login-hdr .logo { width: 56px; height: 56px; background: linear-gradient(135deg, var(--accent), #6366f1); color: #fff; border-radius: 16px; display: inline-flex; align-items: center; justify-content: center; font-size: 24px; font-weight: 700; margin-bottom: 20px; box-shadow: 0 8px 32px rgba(59,130,246,.25); }
+        .login-hdr h1 { font-size: 1.5rem; font-weight: 700; letter-spacing: -.02em; }
+        .login-hdr p { font-size: .875rem; color: var(--fg4); margin-top: 6px; }
+        .login-err { margin-top: 14px; padding: 10px 14px; background: var(--err-bg); border: 1px solid rgba(239,68,68,.2); border-radius: var(--r); color: var(--err); font-size: .8rem; text-align: center; }
+
+        /* ── Inputs ── */
+        .inp { width: 100%; height: 44px; padding: 0 14px; background: var(--surface); border: 1px solid var(--border); border-radius: var(--r); color: var(--fg); font-family: var(--font); font-size: .9rem; outline: none; transition: border-color .15s, box-shadow .15s; }
+        .inp::placeholder { color: var(--fg5); }
+        .inp:focus { border-color: var(--accent); box-shadow: 0 0 0 3px var(--accent-bg); }
+        .inp-mono { font-family: var(--mono); font-size: .8rem; }
+        textarea.inp { height: auto; padding: 12px 14px; resize: vertical; font-family: var(--mono); font-size: .8rem; line-height: 1.6; }
+
+        /* ── Buttons ── */
+        .btn { display: inline-flex; align-items: center; justify-content: center; gap: 7px; height: 36px; padding: 0 16px; border: none; border-radius: var(--r); font-family: var(--font); font-size: .85rem; font-weight: 600; cursor: pointer; transition: all .15s; outline: none; white-space: nowrap; }
+        .btn:active { transform: scale(.97); }
+        .btn:disabled { opacity: .4; cursor: not-allowed; }
+        .btn-p { background: var(--accent); color: #fff; }
+        .btn-p:hover { background: #2563eb; }
+        .btn-o { background: transparent; color: var(--fg3); border: 1px solid var(--border); }
+        .btn-o:hover { border-color: var(--fg4); color: var(--fg); }
+        .btn-d { background: var(--err-bg); color: var(--err); border: 1px solid rgba(239,68,68,.15); }
+        .btn-d:hover { background: rgba(239,68,68,.18); }
+        .btn-lg { height: 44px; padding: 0 24px; font-size: .95rem; }
+        .btn-icon { width: 32px; height: 32px; padding: 0; display: inline-flex; align-items: center; justify-content: center; border-radius: var(--r); background: transparent; color: var(--fg4); border: none; cursor: pointer; font-size: .9rem; transition: all .12s; }
+        .btn-icon:hover { color: var(--fg2); background: var(--surface2); }
+        .btn-icon.danger:hover { color: var(--err); background: var(--err-bg); }
+        .btn-icon.ok:hover { color: var(--ok); background: var(--ok-bg); }
+
+        /* ── Navbar ── */
+        .nav { display: flex; align-items: center; justify-content: space-between; height: 56px; padding: 0 24px; background: var(--bg2); border-bottom: 1px solid var(--border); position: sticky; top: 0; z-index: 40; backdrop-filter: blur(12px); }
+        .nav-left { display: flex; align-items: center; gap: 24px; height: 100%; }
+        .nav-brand { display: flex; align-items: center; gap: 10px; font-weight: 700; font-size: .95rem; }
+        .nav-brand .mark { width: 28px; height: 28px; background: linear-gradient(135deg, var(--accent), #6366f1); color: #fff; border-radius: 8px; display: flex; align-items: center; justify-content: center; font-size: 13px; font-weight: 700; }
+        .nav-tabs { display: flex; gap: 0; height: 100%; }
+        .nav-tab { display: flex; align-items: center; padding: 0 16px; font-size: .85rem; font-weight: 500; color: var(--fg4); cursor: pointer; border-bottom: 2px solid transparent; transition: all .15s; }
+        .nav-tab:hover { color: var(--fg2); }
+        .nav-tab.active { color: var(--fg); border-bottom-color: var(--accent); }
+        .nav-actions { display: flex; align-items: center; gap: 10px; }
+        .nav-meta { font-size: .75rem; color: var(--fg4); padding: 4px 12px; background: var(--surface); border-radius: 999px; border: 1px solid var(--border); font-family: var(--mono); }
+
+        /* ── Stats ── */
+        .stats { display: grid; grid-template-columns: repeat(5, 1fr); gap: 12px; margin-bottom: 24px; }
+        @media (max-width: 800px) { .stats { grid-template-columns: repeat(2, 1fr); } }
+        .stat { background: var(--surface); border: 1px solid var(--border); border-radius: var(--rl); padding: 18px 20px; transition: border-color .2s; }
+        .stat:hover { border-color: var(--border2); }
+        .stat-label { font-size: .75rem; color: var(--fg4); margin-bottom: 6px; text-transform: uppercase; letter-spacing: .05em; font-weight: 600; }
+        .stat-val { font-size: 2rem; font-weight: 700; letter-spacing: -.03em; line-height: 1.1; }
+        .dot { display: inline-block; width: 7px; height: 7px; border-radius: 50%; margin-right: 6px; vertical-align: middle; position: relative; top: -1px; }
+
+        /* ── Table ── */
+        .card { background: var(--surface); border: 1px solid var(--border); border-radius: var(--rl); overflow: hidden; }
+        .tbl-wrap { overflow-x: auto; }
+        table { width: 100%; border-collapse: separate; border-spacing: 0; }
+        thead th { padding: 0 16px; height: 42px; font-size: .7rem; font-weight: 600; color: var(--fg4); border-bottom: 1px solid var(--border); text-align: left; white-space: nowrap; text-transform: uppercase; letter-spacing: .06em; }
+        tbody td { padding: 10px 16px; border-bottom: 1px solid rgba(39,39,42,.5); font-size: .85rem; color: var(--fg2); vertical-align: middle; }
+        tbody tr { transition: background .1s; }
+        tbody tr:hover { background: rgba(255,255,255,.02); }
+        tbody tr:last-child td { border-bottom: none; }
+        tbody tr.selected { background: var(--accent-bg); }
+        .c-id { color: var(--fg5); font-family: var(--mono); font-size: .75rem; }
+        .c-key { font-family: var(--mono); font-size: .75rem; color: var(--fg3); background: var(--bg2); padding: 3px 10px; border-radius: 6px; display: inline-block; border: 1px solid var(--border); }
+        .c-date { color: var(--fg5); font-size: .75rem; }
+        .c-acts { display: flex; gap: 2px; }
+
+        /* ── Badges ── */
+        .badge { display: inline-flex; align-items: center; gap: 5px; padding: 3px 10px; border-radius: 999px; font-size: .7rem; font-weight: 600; text-transform: uppercase; letter-spacing: .04em; }
+        .badge::before { content: ''; width: 5px; height: 5px; border-radius: 50%; flex-shrink: 0; }
+        .badge-active { background: var(--ok-bg); color: var(--ok); }
+        .badge-active::before { background: var(--ok); }
+        .badge-inactive { background: var(--err-bg); color: var(--err); }
+        .badge-inactive::before { background: var(--err); }
+        .badge-exhausted { background: var(--warn-bg); color: var(--warn); }
+        .badge-exhausted::before { background: var(--warn); }
+        .badge-unknown { background: rgba(113,113,122,.15); color: var(--fg4); }
+        .badge-unknown::before { background: var(--fg5); }
+
+        .chk { width: 16px; height: 16px; accent-color: var(--accent); cursor: pointer; }
+
+        /* ── Batch bar ── */
+        .batch-bar { display: flex; align-items: center; gap: 10px; padding: 10px 18px; background: var(--surface2); border: 1px solid var(--accent); border-radius: var(--r); margin-bottom: 14px; animation: rise .2s ease both; box-shadow: 0 0 20px var(--accent-bg); }
+        .batch-bar .batch-count { font-size: .85rem; font-weight: 700; background: var(--accent); color: #fff; padding: 2px 12px; border-radius: 999px; }
+        .batch-bar .batch-label { font-size: .85rem; color: var(--fg3); }
+
+        /* ── Empty ── */
+        .empty { text-align: center; padding: 64px 24px; }
+        .empty .e-icon { font-size: 2.5rem; margin-bottom: 14px; opacity: .25; }
+        .empty p { color: var(--fg4); font-size: .9rem; }
+        .empty p+p { color: var(--fg5); margin-top: 4px; font-size: .8rem; }
+
+        /* ── Modal ── */
+        .modal-bg { position: fixed; inset: 0; background: rgba(0,0,0,.65); backdrop-filter: blur(6px); display: flex; align-items: center; justify-content: center; z-index: 100; padding: 24px; opacity: 0; visibility: hidden; transition: opacity .2s, visibility .2s; }
+        .modal-bg.open { opacity: 1; visibility: visible; }
+        .modal { width: 100%; max-width: 440px; background: var(--surface); border: 1px solid var(--border); border-radius: 16px; padding: 24px; box-shadow: 0 24px 64px rgba(0,0,0,.5); transform: scale(.95); transition: transform .2s cubic-bezier(.16,1,.3,1); }
+        .modal-bg.open .modal { transform: scale(1); }
+        .modal-title { font-size: 1.1rem; font-weight: 700; margin-bottom: 20px; }
+        .modal-field { margin-bottom: 16px; }
+        .modal-field label { display: block; font-size: .8rem; font-weight: 600; color: var(--fg3); margin-bottom: 6px; }
+        .modal-field .hint { color: var(--fg5); font-weight: 400; }
+        .modal-acts { display: flex; gap: 10px; margin-top: 24px; justify-content: flex-end; }
+
+        /* ── Toast ── */
+        .toast-c { position: fixed; top: 16px; right: 16px; z-index: 200; display: flex; flex-direction: column; gap: 8px; }
+        .toast { display: flex; align-items: center; gap: 10px; padding: 12px 18px; background: var(--surface); border: 1px solid var(--border); border-radius: var(--r); font-size: .85rem; font-weight: 500; color: var(--fg2); max-width: 400px; animation: toastIn .3s cubic-bezier(.16,1,.3,1) both; box-shadow: 0 8px 24px rgba(0,0,0,.3); }
+        .toast.out { animation: toastOut .2s ease both; }
+        .toast-icon { width: 22px; height: 22px; border-radius: 50%; display: flex; align-items: center; justify-content: center; font-size: 12px; flex-shrink: 0; }
+        .toast.success .toast-icon { background: var(--ok-bg); color: var(--ok); }
+        .toast.error .toast-icon { background: var(--err-bg); color: var(--err); }
+        .toast.info .toast-icon { background: var(--accent-bg); color: var(--accent2); }
+
+        /* ── Filter bar ── */
+        .filter-bar { display: flex; align-items: center; justify-content: space-between; flex-wrap: wrap; gap: 10px; margin-bottom: 16px; }
+        .filter-tags { display: flex; gap: 6px; flex-wrap: wrap; }
+        .filter-tag { display: inline-flex; align-items: center; gap: 6px; padding: 5px 14px; background: var(--surface); border: 1px solid var(--border); border-radius: 999px; font-family: var(--font); font-size: .8rem; font-weight: 600; color: var(--fg3); cursor: pointer; transition: all .15s; outline: none; }
+        .filter-tag:hover { border-color: var(--border2); color: var(--fg2); }
+        .filter-tag.active { background: var(--fg); color: var(--bg); border-color: var(--fg); }
+        .filter-tag-dot { width: 6px; height: 6px; border-radius: 50%; flex-shrink: 0; }
+        .filter-tag.active .filter-tag-dot { opacity: .7; }
+        .filter-tag-count { font-family: var(--mono); font-size: .75rem; opacity: .8; }
+        .agrp { display: flex; gap: 8px; flex-wrap: wrap; }
+        .btn-ok { background: var(--ok-bg); color: var(--ok); border: 1px solid rgba(34,197,94,.15); }
+        .btn-ok:hover { background: rgba(34,197,94,.18); }
+
+        /* ── Tab content ── */
+        .tab-content { display: none; }
+        .tab-content.active { display: block; }
+
+        /* ── Config ── */
+        .cfg-section { margin-bottom: 36px; }
+        .cfg-section h3 { font-size: 1.15rem; font-weight: 700; margin-bottom: 4px; }
+        .cfg-section .cfg-desc { font-size: .85rem; color: var(--fg4); margin-bottom: 24px; }
+        .cfg-row { margin-bottom: 22px; }
+        .cfg-row label { display: block; font-size: .85rem; font-weight: 600; margin-bottom: 3px; }
+        .cfg-row .cfg-hint { font-size: .75rem; color: var(--fg5); margin-bottom: 8px; }
+        .cfg-row .cfg-input-row { display: flex; gap: 10px; align-items: center; }
+        .cfg-row .cfg-input-row .inp { flex: 1; }
+        .toggle { position: relative; width: 48px; height: 26px; background: var(--border2); border-radius: 13px; cursor: pointer; transition: background .2s; border: none; }
+        .toggle.on { background: var(--accent); }
+        .toggle::after { content: ''; position: absolute; top: 3px; left: 3px; width: 20px; height: 20px; background: #fff; border-radius: 50%; transition: transform .2s; }
+        .toggle.on::after { transform: translateX(22px); }
+
+        /* ── Docs ── */
+        .docs { max-width: 740px; }
+        .docs h2 { font-size: 1.3rem; font-weight: 700; margin: 36px 0 14px; padding-bottom: 10px; border-bottom: 1px solid var(--border); }
+        .docs h2:first-child { margin-top: 0; }
+        .docs h3 { font-size: 1rem; font-weight: 600; margin: 22px 0 10px; color: var(--fg2); }
+        .docs p { margin-bottom: 14px; color: var(--fg3); font-size: .9rem; }
+        .docs code { background: var(--surface2); padding: 2px 7px; border-radius: 5px; font-family: var(--mono); font-size: .8rem; border: 1px solid var(--border); color: var(--accent2); }
+        .docs pre { background: var(--bg); color: var(--fg2); padding: 18px 22px; border-radius: var(--rl); border: 1px solid var(--border); overflow-x: auto; margin-bottom: 18px; font-family: var(--mono); font-size: .8rem; line-height: 1.7; }
+        .docs pre code { background: none; border: none; padding: 0; color: inherit; }
+        .docs table { width: 100%; margin-bottom: 18px; }
+        .docs table th { background: var(--surface); }
+        .docs .info-box { background: var(--accent-bg); border: 1px solid rgba(59,130,246,.2); border-radius: var(--rl); padding: 16px 20px; margin-bottom: 18px; font-size: .85rem; color: var(--fg2); }
+        .docs .info-box strong { color: var(--accent2); }
+
+        /* ── Proxy info ── */
+        .proxy-info { background: var(--accent-bg); border: 1px solid rgba(59,130,246,.15); border-radius: var(--rl); padding: 16px 20px; margin-bottom: 20px; font-size: .85rem; }
+        .proxy-info strong { color: var(--accent2); }
+        .proxy-info span { color: var(--fg3); }
+
+        /* ── Quota pill ── */
+        .quota-pill { font-family: var(--mono); font-size: .7rem; color: var(--fg4); background: var(--surface2); padding: 2px 8px; border-radius: 4px; border: 1px solid var(--border); }
+
+        /* ── Layout ── */
+        .main { max-width: 1160px; margin: 0 auto; padding: 28px 24px 60px; }
+        .hidden { display: none !important; }
+
+        @keyframes rise { from { opacity: 0; transform: translateY(10px); } to { opacity: 1; transform: translateY(0); } }
+        @keyframes toastIn { from { opacity: 0; transform: translateX(20px); } to { opacity: 1; transform: translateX(0); } }
+        @keyframes toastOut { from { opacity: 1; } to { opacity: 0; transform: translateX(20px); } }
+
+        @media (max-width: 768px) {
+            .nav { padding: 0 12px; }
+            .main { padding: 16px 12px 40px; }
+            .stats { grid-template-columns: repeat(2, 1fr); }
+            .agrp { width: 100%; }
+            .agrp .btn { flex: 1; font-size: .75rem; padding: 0 10px; }
+            .nav-meta { display: none; }
+            .nav-tab { padding: 0 10px; font-size: .8rem; }
+        }
+    </style>
+</head>
+<body>
+<div class="toast-c" id="toasts"></div>
+
+<!-- Login -->
+<div id="login-screen">
+    <div class="login-wrap">
+        <div class="login-card">
+            <div class="login-hdr">
+                <div class="logo">T</div>
+                <h1>Tavily Key Manager</h1>
+                <p>API key pool &amp; search proxy management</p>
+            </div>
+            <div style="margin-bottom:18px;">
+                <input id="pw-in" type="password" class="inp" placeholder="Admin password" onkeydown="if(event.key==='Enter')login()" autofocus>
+            </div>
+            <button onclick="login()" class="btn btn-p btn-lg" style="width:100%;">Sign in</button>
+            <div id="login-err" class="login-err hidden">Invalid credentials</div>
+        </div>
+    </div>
+</div>
+
+<!-- App -->
+<div id="app" class="hidden">
+    <nav class="nav">
+        <div class="nav-left">
+            <div class="nav-brand"><div class="mark">T</div>Tavily Keys</div>
+            <div class="nav-tabs">
+                <div class="nav-tab active" data-tab="keys">Keys</div>
+                <div class="nav-tab" data-tab="config">Config</div>
+                <div class="nav-tab" data-tab="tokens">Tokens</div>
+                <div class="nav-tab" data-tab="docs">Docs</div>
+            </div>
+        </div>
+        <div class="nav-actions">
+            <span id="nav-count" class="nav-meta"></span>
+            <button onclick="refresh()" class="btn-icon" title="Refresh" style="font-size:1.1rem;">&#8635;</button>
+            <button onclick="logout()" class="btn btn-o" style="height:30px;font-size:.75rem;padding:0 12px;">Sign out</button>
+        </div>
+    </nav>
+
+    <div class="main">
+        <!-- === KEYS TAB === -->
+        <div id="tab-keys" class="tab-content active">
+            <div class="stats" style="animation:rise .4s ease both;">
+                <div class="stat"><div class="stat-label">Total</div><div class="stat-val" id="s-total">-</div></div>
+                <div class="stat"><div class="stat-label"><span class="dot" style="background:var(--ok);"></span>Active</div><div class="stat-val" id="s-active">-</div></div>
+                <div class="stat"><div class="stat-label"><span class="dot" style="background:var(--err);"></span>Inactive</div><div class="stat-val" id="s-inactive">-</div></div>
+                <div class="stat"><div class="stat-label"><span class="dot" style="background:var(--warn);"></span>Exhausted</div><div class="stat-val" id="s-exhausted">-</div></div>
+                <div class="stat"><div class="stat-label">Pool Quota</div><div class="stat-val" id="s-quota" style="font-size:1.3rem;">-</div></div>
+            </div>
+
+            <div class="proxy-info" style="animation:rise .4s ease .05s both;">
+                <strong>Search Proxy</strong> &mdash;
+                <span>Set <code style="background:var(--surface2);border:1px solid var(--border);padding:2px 6px;border-radius:4px;font-family:var(--mono);font-size:.75rem;color:var(--accent2);">TAVILY_BASE_URL</code> to <code id="proxy-url" style="cursor:pointer;background:var(--surface2);border:1px solid var(--border);padding:2px 6px;border-radius:4px;font-family:var(--mono);font-size:.75rem;color:var(--fg2);" onclick="copyProxy()" title="Click to copy"></code></span>
+                <span id="s-usage" style="color:var(--fg5);margin-left:8px;"></span>
+            </div>
+
+            <div id="batch-bar" class="batch-bar hidden">
+                <span style="color:var(--fg3);">Selected</span>
+                <span class="batch-count" id="batch-count">0</span>
+                <span class="batch-label">items</span>
+                <div style="flex:1;"></div>
+                <button onclick="batchCheck()" class="btn btn-o" style="height:30px;font-size:.75rem;">Check</button>
+                <button onclick="batchDisable()" class="btn btn-o" style="height:30px;font-size:.75rem;">Disable</button>
+                <button onclick="batchEnable()" class="btn btn-o" style="height:30px;font-size:.75rem;">Enable</button>
+                <button onclick="batchDelete()" class="btn btn-d" style="height:30px;font-size:.75rem;">Delete</button>
+            </div>
+
+            <div class="filter-bar" style="animation:rise .4s ease .1s both;">
+                <div class="filter-tags">
+                    <button class="filter-tag active" data-filter="all" onclick="filterKeys('all',this)"><span class="filter-tag-label">All</span><span class="filter-tag-count" id="ft-all">0</span></button>
+                    <button class="filter-tag" data-filter="active" onclick="filterKeys('active',this)"><span class="filter-tag-dot" style="background:var(--ok);"></span><span class="filter-tag-label">Active</span><span class="filter-tag-count" id="ft-active">0</span></button>
+                    <button class="filter-tag" data-filter="inactive" onclick="filterKeys('inactive',this)"><span class="filter-tag-dot" style="background:var(--err);"></span><span class="filter-tag-label">Inactive</span><span class="filter-tag-count" id="ft-inactive">0</span></button>
+                    <button class="filter-tag" data-filter="exhausted" onclick="filterKeys('exhausted',this)"><span class="filter-tag-dot" style="background:var(--warn);"></span><span class="filter-tag-label">Exhausted</span><span class="filter-tag-count" id="ft-exhausted">0</span></button>
+                </div>
+                <div class="agrp">
+                    <button onclick="showModal('add')" class="btn btn-p">Add Key</button>
+                    <button onclick="showModal('import')" class="btn btn-o">Import</button>
+                    <button onclick="exportKeys()" class="btn btn-o">Export</button>
+                    <button onclick="healthcheckAll()" id="btn-hc" class="btn btn-ok">Test</button>
+                    <button onclick="deleteInactive()" class="btn btn-d">Delete</button>
+                </div>
+            </div>
+
+            <div class="card" style="animation:rise .4s ease .15s both;">
+                <div class="tbl-wrap">
+                    <table>
+                        <thead><tr>
+                            <th style="width:36px;"><input type="checkbox" class="chk" id="chk-all" onchange="toggleAll(this)"></th>
+                            <th style="width:44px;">ID</th>
+                            <th>Email</th>
+                            <th>API Key</th>
+                            <th>Status</th>
+                            <th>Quota</th>
+                            <th>Created</th>
+                            <th>Checked</th>
+                            <th>Uses</th>
+                            <th style="width:90px;text-align:right;">Actions</th>
+                        </tr></thead>
+                        <tbody id="keys-tbl"></tbody>
+                    </table>
+                </div>
+                <div id="empty-keys" class="empty hidden">
+                    <div class="e-icon">&#9711;</div>
+                    <p>No API keys in the pool</p>
+                    <p>Add keys manually or run the registration workflow</p>
+                </div>
+            </div>
+        </div>
+
+        <!-- === CONFIG TAB === -->
+        <div id="tab-config" class="tab-content">
+            <div class="cfg-section">
+                <h3>Configuration</h3>
+                <p class="cfg-desc">Manage authentication, proxy settings, and system behavior.</p>
+
+                <div class="cfg-row">
+                    <label>Admin Token</label>
+                    <div class="cfg-hint">Default admin access token with unlimited quota.</div>
+                    <div class="cfg-input-row">
+                        <input id="cfg-admin-token" type="text" class="inp inp-mono" readonly>
+                        <button onclick="copyVal('cfg-admin-token')" class="btn-icon" title="Copy">&#128203;</button>
+                    </div>
+                </div>
+
+                <div class="cfg-row">
+                    <label>Admin Password</label>
+                    <div class="cfg-hint">Password for the management dashboard.</div>
+                    <div class="cfg-input-row">
+                        <input id="cfg-admin-pw" type="text" class="inp">
+                        <button onclick="saveConfig('admin_password','cfg-admin-pw')" class="btn btn-p" style="height:44px;">Save</button>
+                    </div>
+                </div>
+
+                <div class="cfg-row">
+                    <label>Free Mode</label>
+                    <div class="cfg-hint">When enabled, proxy accepts any request without a valid token.</div>
+                    <div style="display:flex;align-items:center;gap:14px;margin-top:10px;">
+                        <button id="cfg-free-mode" class="toggle" onclick="toggleFreeMode()"></button>
+                        <span id="cfg-free-label" style="font-size:.85rem;color:var(--fg4);">Off</span>
+                    </div>
+                </div>
+
+                <div class="cfg-row">
+                    <label>Default Quota</label>
+                    <div class="cfg-hint">Default monthly request limit for new access tokens.</div>
+                    <div class="cfg-input-row">
+                        <input id="cfg-default-quota" type="number" class="inp" style="max-width:200px;">
+                        <button onclick="saveConfig('default_quota','cfg-default-quota')" class="btn btn-p" style="height:44px;">Save</button>
+                    </div>
+                </div>
+            </div>
+        </div>
+
+        <!-- === TOKENS TAB === -->
+        <div id="tab-tokens" class="tab-content">
+            <div class="abar" style="margin-top:8px;">
+                <div class="abar-title">Access Tokens</div>
+                <div class="agrp"><button onclick="showModal('add-token')" class="btn btn-p">Add Token</button></div>
+            </div>
+            <div class="card">
+                <div class="tbl-wrap">
+                    <table>
+                        <thead><tr>
+                            <th style="width:44px;">ID</th>
+                            <th>Token</th>
+                            <th>Name</th>
+                            <th>Type</th>
+                            <th>Quota</th>
+                            <th>Used</th>
+                            <th>Status</th>
+                            <th>Expires</th>
+                            <th>Last Used</th>
+                            <th style="width:90px;text-align:right;">Actions</th>
+                        </tr></thead>
+                        <tbody id="tokens-tbl"></tbody>
+                    </table>
+                </div>
+                <div id="empty-tokens" class="empty hidden">
+                    <div class="e-icon">&#9711;</div>
+                    <p>No access tokens</p>
+                    <p>Create tokens for users to access the proxy</p>
+                </div>
+            </div>
+        </div>
+
+        <!-- === DOCS TAB === -->
+        <div id="tab-docs" class="tab-content">
+            <div class="docs">
+                <h2>Tavily Search Proxy API</h2>
+                <p>Drop-in replacement for <code>api.tavily.com</code> with managed key pool, round-robin selection, and per-user quota management.</p>
+
+                <div class="info-box">
+                    <strong>Base URL:</strong> <code id="doc-base-url"></code>
+                </div>
+
+                <h2>Authentication</h2>
+                <p>Include your access token in the <code>Authorization</code> header:</p>
+                <pre><code>Authorization: Bearer sk-your-access-token</code></pre>
+                <p>If <strong>Free Mode</strong> is enabled, authentication is optional.</p>
+
+                <h2>Endpoints</h2>
+
+                <h3>POST /v1/search</h3>
+                <p>Web search. Drop-in replacement for <code>api.tavily.com/search</code>.</p>
+                <pre><code>curl -X POST BASE_URL/v1/search \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer sk-your-token" \
+  -d '{
+    "query": "latest AI news",
+    "max_results": 5,
+    "search_depth": "basic"
+  }'</code></pre>
+
+                <h3>POST /v1/extract</h3>
+                <p>Content extraction. Drop-in replacement for <code>api.tavily.com/extract</code>.</p>
+                <pre><code>curl -X POST BASE_URL/v1/extract \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer sk-your-token" \
+  -d '{"urls": ["https://example.com"]}'</code></pre>
+
+                <h3>GET /health</h3>
+                <p>Health check (no auth).</p>
+                <pre><code>curl BASE_URL/health</code></pre>
+
+                <h2>Python</h2>
+                <pre><code>import requests
+
+resp = requests.post(
+    "BASE_URL/v1/search",
+    headers={"Authorization": "Bearer sk-your-token"},
+    json={"query": "hello world", "max_results": 3}
+)
+print(resp.json())</code></pre>
+
+                <h2>Environment Variables</h2>
+                <pre><code>export TAVILY_BASE_URL=BASE_URL
+export TAVILY_API_KEY=sk-your-access-token</code></pre>
+
+                <h2>MCP Integration</h2>
+                <pre><code>{
+  "mcpServers": {
+    "tavily": {
+      "command": "npx",
+      "args": ["-y", "tavily-mcp@latest"],
+      "env": {
+        "TAVILY_API_KEY": "sk-your-access-token",
+        "TAVILY_BASE_URL": "BASE_URL"
+      }
+    }
+  }
+}</code></pre>
+
+                <h2>Cherry Studio</h2>
+                <p>In Cherry Studio settings, configure the Tavily plugin:</p>
+                <pre><code>API Base URL: BASE_URL
+API Key: sk-your-access-token</code></pre>
+
+                <h2>Quotas</h2>
+                <table>
+                    <thead><tr><th>Type</th><th>Quota</th><th>Notes</th></tr></thead>
+                    <tbody>
+                        <tr><td>Admin</td><td>Unlimited</td><td>Built-in admin token</td></tr>
+                        <tr><td>User</td><td>Configurable</td><td>Monthly per-token limit</td></tr>
+                        <tr><td>Free Mode</td><td>Unlimited</td><td>When free mode is on</td></tr>
+                    </tbody>
+                </table>
+                <p>When a token exceeds its quota or passes its expiry date, the API returns <code>429</code> or <code>401</code>.</p>
+            </div>
+        </div>
+    </div>
+</div>
+
+<!-- Modals -->
+<div id="modal-add" class="modal-bg" onclick="if(event.target===this)closeModals()">
+    <div class="modal">
+        <div class="modal-title">Add API Key</div>
+        <div class="modal-field"><label>Email</label><input id="add-email" type="text" class="inp" placeholder="user@example.com"></div>
+        <div class="modal-field"><label>Password <span class="hint">(optional)</span></label><input id="add-pw" type="text" class="inp" placeholder="Account password"></div>
+        <div class="modal-field"><label>API Key</label><input id="add-key" type="text" class="inp inp-mono" placeholder="tvly-..."></div>
+        <div class="modal-acts"><button onclick="closeModals()" class="btn btn-o">Cancel</button><button onclick="addKey()" class="btn btn-p">Add</button></div>
+    </div>
+</div>
+
+<div id="modal-import" class="modal-bg" onclick="if(event.target===this)closeModals()">
+    <div class="modal" style="max-width:540px;">
+        <div class="modal-title">Batch Import</div>
+        <div class="modal-field">
+            <label>JSON <span class="hint">(array of {email, password, api_key})</span></label>
+            <textarea id="import-json" class="inp" rows="10" placeholder='[{"email":"...","api_key":"tvly-..."}]'></textarea>
+        </div>
+        <div style="margin-bottom:14px;">
+            <label class="btn btn-o" style="cursor:pointer;">Upload JSON<input type="file" accept=".json" style="display:none;" onchange="loadFile(this)"></label>
+        </div>
+        <div class="modal-acts"><button onclick="closeModals()" class="btn btn-o">Cancel</button><button onclick="importKeys()" class="btn btn-p">Import</button></div>
+    </div>
+</div>
+
+<div id="modal-add-token" class="modal-bg" onclick="if(event.target===this)closeModals()">
+    <div class="modal">
+        <div class="modal-title">Create Access Token</div>
+        <div class="modal-field"><label>Name <span class="hint">(optional)</span></label><input id="tk-name" type="text" class="inp" placeholder="e.g. User A"></div>
+        <div class="modal-field"><label>Token <span class="hint">(blank = auto-generate)</span></label><input id="tk-token" type="text" class="inp inp-mono" placeholder="sk-..."></div>
+        <div class="modal-field"><label>Monthly Quota</label><input id="tk-quota" type="number" class="inp" value="1000" style="max-width:200px;"></div>
+        <div class="modal-field"><label>Expires <span class="hint">(optional, ISO date)</span></label><input id="tk-expires" type="date" class="inp" style="max-width:220px;"></div>
+        <div class="modal-acts"><button onclick="closeModals()" class="btn btn-o">Cancel</button><button onclick="createToken()" class="btn btn-p">Create</button></div>
+    </div>
+</div>
+
+<script>
+(() => {
+    let TOKEN = '';
+    const API = '';
+    let selectedIds = new Set();
+    let allKeys = [];
+    let currentFilter = 'all';
+
+    const $ = id => document.getElementById(id);
+    const hdr = () => ({ 'Authorization': `Bearer ${TOKEN}`, 'Content-Type': 'application/json' });
+
+    function toast(msg, type = 'info') {
+        const el = document.createElement('div');
+        el.className = `toast ${type}`;
+        const icons = { success: '\u2713', error: '\u2717', info: 'i' };
+        el.innerHTML = `<span class="toast-icon">${icons[type]||icons.info}</span><span>${msg}</span>`;
+        $('toasts').appendChild(el);
+        setTimeout(() => { el.classList.add('out'); setTimeout(() => el.remove(), 200); }, 3500);
+    }
+
+    document.querySelectorAll('.nav-tab').forEach(tab => {
+        tab.addEventListener('click', () => {
+            document.querySelectorAll('.nav-tab').forEach(t => t.classList.remove('active'));
+            document.querySelectorAll('.tab-content').forEach(c => c.classList.remove('active'));
+            tab.classList.add('active');
+            $('tab-' + tab.dataset.tab).classList.add('active');
+            if (tab.dataset.tab === 'config') loadConfig();
+            if (tab.dataset.tab === 'tokens') loadTokens();
+        });
+    });
+
+    window.login = async function() {
+        TOKEN = $('pw-in').value.trim();
+        if (!TOKEN) return;
+        try {
+            const r = await fetch(`${API}/api/stats`, { headers: hdr() });
+            if (!r.ok) throw 0;
+            $('login-screen').classList.add('hidden');
+            $('app').classList.remove('hidden');
+            localStorage.setItem('tkm_token', TOKEN);
+            refresh();
+        } catch {
+            $('login-err').classList.remove('hidden');
+            setTimeout(() => $('login-err').classList.add('hidden'), 3000);
+        }
+    };
+    window.logout = function() {
+        TOKEN = '';
+        localStorage.removeItem('tkm_token');
+        $('app').classList.add('hidden');
+        $('login-screen').classList.remove('hidden');
+        $('pw-in').value = '';
+    };
+
+    window.refresh = async function() {
+        selectedIds.clear();
+        updateBatchBar();
+        await Promise.all([loadStats(), loadKeys()]);
+    };
+
+    async function loadStats() {
+        try {
+            const r = await fetch(`${API}/api/stats`, { headers: hdr() });
+            const d = await r.json();
+            $('s-total').textContent = d.total_keys;
+            $('s-active').textContent = d.active_keys;
+            $('s-inactive').textContent = d.inactive_keys;
+            $('s-exhausted').textContent = d.exhausted_keys;
+            $('s-quota').textContent = d.total_quota_remaining != null ? d.total_quota_remaining.toLocaleString() : '\u2014';
+            $('nav-count').textContent = `${d.active_keys}/${d.total_keys}`;
+            $('s-usage').textContent = `\u00b7 ${(d.total_usage || 0).toLocaleString()} proxy calls`;
+        } catch { toast('Failed to load stats', 'error'); }
+    }
+
+    async function loadKeys() {
+        try {
+            const r = await fetch(`${API}/api/keys`, { headers: hdr() });
+            const d = await r.json();
+            allKeys = d.keys || [];
+            updateFilterCounts();
+            renderKeys();
+        } catch { toast('Failed to load keys', 'error'); }
+    }
+    function updateFilterCounts() {
+        $('ft-all').textContent = allKeys.length;
+        $('ft-active').textContent = allKeys.filter(k => k.status === 'active').length;
+        $('ft-inactive').textContent = allKeys.filter(k => k.status === 'inactive').length;
+        $('ft-exhausted').textContent = allKeys.filter(k => k.status === 'exhausted').length;
+    }
+    window.filterKeys = function(filter, el) {
+        currentFilter = filter;
+        document.querySelectorAll('.filter-tag').forEach(t => t.classList.remove('active'));
+        el.classList.add('active');
+        selectedIds.clear(); updateBatchBar();
+        renderKeys();
+    };
+    function renderKeys() {
+        const filtered = currentFilter === 'all' ? allKeys : allKeys.filter(k => k.status === currentFilter);
+        const tbody = $('keys-tbl');
+        if (!filtered.length) { tbody.innerHTML = ''; $('empty-keys').classList.remove('hidden'); return; }
+        $('empty-keys').classList.add('hidden');
+        tbody.innerHTML = filtered.map(k => {
+            const ks = k.api_key.length > 20 ? k.api_key.substring(0,10)+'\u2026'+k.api_key.slice(-6) : k.api_key;
+            const cr = k.created_at ? new Date(k.created_at).toLocaleDateString('en-CA') : '\u2014';
+            const ch = k.last_checked ? new Date(k.last_checked).toLocaleDateString('en-CA') : '\u2014';
+            const sel = selectedIds.has(k.id) ? 'checked' : '';
+            const qr = k.quota_remaining != null ? k.quota_remaining : '\u2014';
+            return `<tr class="${selectedIds.has(k.id)?'selected':''}">
+                <td><input type="checkbox" class="chk" data-id="${k.id}" ${sel} onchange="toggleSel(${k.id},this.checked)"></td>
+                <td class="c-id">${k.id}</td>
+                <td style="color:var(--fg3);font-size:.85rem;">${esc(k.email)}</td>
+                <td><span class="c-key">${esc(ks)}</span></td>
+                <td><span class="badge badge-${k.status}">${k.status}</span></td>
+                <td><span class="quota-pill">${qr}</span></td>
+                <td class="c-date">${cr}</td>
+                <td class="c-date">${ch}</td>
+                <td class="c-id">${k.use_count||0}</td>
+                <td><div class="c-acts" style="justify-content:flex-end;">
+                    <button class="btn-icon" onclick="copyKey('${escA(k.api_key)}')" title="Copy">&#128203;</button>
+                    <button class="btn-icon ok" onclick="checkKey(${k.id})" title="Test">&#9889;</button>
+                    <button class="btn-icon danger" onclick="deleteKey(${k.id})" title="Delete">&#128465;</button>
+                </div></td></tr>`;
+        }).join('');
+    }
+
+    function esc(s) { const d = document.createElement('div'); d.textContent = s; return d.innerHTML; }
+    function escA(s) { return s.replace(/'/g, "\\'").replace(/"/g, '&quot;'); }
+
+    window.toggleSel = function(id, checked) {
+        if (checked) selectedIds.add(id); else selectedIds.delete(id);
+        updateBatchBar();
+        const row = document.querySelector(`input[data-id="${id}"]`)?.closest('tr');
+        if (row) row.classList.toggle('selected', checked);
+    };
+    window.toggleAll = function(el) {
+        document.querySelectorAll('#keys-tbl .chk').forEach(c => {
+            c.checked = el.checked;
+            const id = parseInt(c.dataset.id);
+            if (el.checked) selectedIds.add(id); else selectedIds.delete(id);
+            c.closest('tr').classList.toggle('selected', el.checked);
+        });
+        updateBatchBar();
+    };
+    function updateBatchBar() {
+        const bar = $('batch-bar');
+        if (selectedIds.size > 0) { bar.classList.remove('hidden'); $('batch-count').textContent = selectedIds.size; }
+        else { bar.classList.add('hidden'); }
+        const allChk = $('chk-all');
+        if (allChk) allChk.checked = selectedIds.size > 0 && selectedIds.size === document.querySelectorAll('#keys-tbl .chk').length;
+    }
+
+    window.batchDelete = async function() {
+        if (!selectedIds.size || !confirm(`Delete ${selectedIds.size} selected keys?`)) return;
+        try {
+            await fetch(`${API}/api/keys/batch-delete`, { method: 'POST', headers: hdr(), body: JSON.stringify({ ids: [...selectedIds] }) });
+            toast(`Deleted ${selectedIds.size} keys`, 'success'); selectedIds.clear(); refresh();
+        } catch { toast('Batch delete failed', 'error'); }
+    };
+    window.batchCheck = async function() {
+        if (!selectedIds.size) return;
+        toast('Checking selected keys\u2026', 'info');
+        try {
+            const r = await fetch(`${API}/api/keys/batch-check`, { method: 'POST', headers: hdr(), body: JSON.stringify({ ids: [...selectedIds] }) });
+            const d = await r.json();
+            toast(`Checked ${d.checked} \u2014 ${d.active} active`, 'success'); refresh();
+        } catch { toast('Batch check failed', 'error'); }
+    };
+    window.batchDisable = async function() {
+        if (!selectedIds.size) return;
+        try {
+            await fetch(`${API}/api/keys/batch-status`, { method: 'POST', headers: hdr(), body: JSON.stringify({ ids: [...selectedIds], status: 'inactive' }) });
+            toast(`Disabled ${selectedIds.size} keys`, 'success'); selectedIds.clear(); refresh();
+        } catch { toast('Failed', 'error'); }
+    };
+    window.batchEnable = async function() {
+        if (!selectedIds.size) return;
+        try {
+            await fetch(`${API}/api/keys/batch-status`, { method: 'POST', headers: hdr(), body: JSON.stringify({ ids: [...selectedIds], status: 'active' }) });
+            toast(`Enabled ${selectedIds.size} keys`, 'success'); selectedIds.clear(); refresh();
+        } catch { toast('Failed', 'error'); }
+    };
+
+    window.showModal = function(name) {
+        document.querySelectorAll('.modal-bg').forEach(m => m.classList.remove('open'));
+        $(`modal-${name}`).classList.add('open');
+    };
+    window.closeModals = function() { document.querySelectorAll('.modal-bg').forEach(m => m.classList.remove('open')); };
+    document.addEventListener('keydown', e => { if (e.key === 'Escape') closeModals(); });
+
+    window.addKey = async function() {
+        const email = $('add-email').value.trim(), pw = $('add-pw').value.trim(), key = $('add-key').value.trim();
+        if (!email || !key) { toast('Email and API key required', 'error'); return; }
+        try {
+            const r = await fetch(`${API}/api/keys`, { method: 'POST', headers: hdr(), body: JSON.stringify({ email, password: pw, api_key: key }) });
+            if (!r.ok) throw new Error(await r.text());
+            toast('Key added', 'success'); closeModals(); $('add-email').value=''; $('add-pw').value=''; $('add-key').value=''; refresh();
+        } catch (e) { toast(`Failed: ${e.message}`, 'error'); }
+    };
+    window.importKeys = async function() {
+        try {
+            let keys = JSON.parse($('import-json').value.trim());
+            if (!Array.isArray(keys)) keys = [keys];
+            const r = await fetch(`${API}/api/keys/import`, { method: 'POST', headers: hdr(), body: JSON.stringify({ keys }) });
+            if (!r.ok) throw new Error(await r.text());
+            const d = await r.json();
+            toast(`Imported ${d.imported} keys`, 'success'); closeModals(); $('import-json').value=''; refresh();
+        } catch (e) { toast(`Import failed: ${e.message}`, 'error'); }
+    };
+    window.loadFile = function(input) {
+        const file = input.files[0]; if (!file) return;
+        const reader = new FileReader();
+        reader.onload = e => { $('import-json').value = e.target.result; };
+        reader.readAsText(file);
+    };
+    window.deleteKey = async function(id) {
+        if (!confirm('Delete this key?')) return;
+        try { await fetch(`${API}/api/keys/${id}`, { method: 'DELETE', headers: hdr() }); toast('Deleted', 'success'); refresh(); }
+        catch { toast('Failed', 'error'); }
+    };
+    window.checkKey = async function(id) {
+        try {
+            const r = await fetch(`${API}/api/keys/${id}/check`, { method: 'POST', headers: hdr() });
+            const d = await r.json();
+            const msg = d.quota_remaining != null ? `${d.status} \u2014 quota: ${d.quota_remaining}` : `${d.status}: ${d.message}`;
+            toast(msg, d.status === 'active' ? 'success' : 'error'); refresh();
+        } catch { toast('Check failed', 'error'); }
+    };
+    window.healthcheckAll = async function() {
+        const btn = $('btn-hc'); const orig = btn.textContent;
+        btn.textContent = 'Checking\u2026'; btn.disabled = true;
+        try {
+            const r = await fetch(`${API}/api/keys/healthcheck`, { method: 'POST', headers: hdr() });
+            const d = await r.json();
+            toast(`Checked ${d.checked} \u2014 ${d.active} active`, 'success'); refresh();
+        } catch { toast('Health check failed', 'error'); }
+        finally { btn.textContent = orig; btn.disabled = false; }
+    };
+    window.deleteInactive = async function() {
+        if (!confirm('Delete ALL inactive and exhausted keys?')) return;
+        try {
+            const r = await fetch(`${API}/api/keys/inactive`, { method: 'DELETE', headers: hdr() });
+            const d = await r.json();
+            toast(`Deleted ${d.deleted} keys`, 'success'); refresh();
+        } catch { toast('Failed', 'error'); }
+    };
+    window.fetchNextKey = async function() {
+        try {
+            const r = await fetch(`${API}/api/keys/next`, { headers: hdr() });
+            if (!r.ok) throw new Error('No active keys');
+            const d = await r.json();
+            await navigator.clipboard.writeText(d.api_key);
+            toast(`Copied: ${d.api_key.substring(0,16)}\u2026`, 'success');
+        } catch (e) { toast(e.message, 'error'); }
+    };
+    window.copyKey = async function(key) {
+        try { await navigator.clipboard.writeText(key); toast('Copied', 'success'); } catch { toast('Copy failed', 'error'); }
+    };
+    window.exportKeys = async function() {
+        try {
+            const r = await fetch(`${API}/api/keys/export`, { headers: hdr() });
+            if (!r.ok) throw new Error('Export failed');
+            const data = await r.json();
+            const blob = new Blob([JSON.stringify(data, null, 2)], { type: 'application/json' });
+            const url = URL.createObjectURL(blob);
+            const a = document.createElement('a'); a.href = url; a.download = 'tavily-keys-export.json'; a.click();
+            URL.revokeObjectURL(url);
+            toast(`Exported ${data.length} keys`, 'success');
+        } catch (e) { toast(e.message, 'error'); }
+    };
+    window.copyProxy = async function() {
+        try { await navigator.clipboard.writeText(window.location.origin); toast('URL copied', 'success'); } catch {}
+    };
+
+    async function loadConfig() {
+        try {
+            const r = await fetch(`${API}/api/config`, { headers: hdr() });
+            const cfg = await r.json();
+            $('cfg-admin-token').value = cfg.admin_token || '';
+            $('cfg-admin-pw').value = cfg.admin_password || '';
+            $('cfg-default-quota').value = cfg.default_quota || '1000';
+            const fm = (cfg.free_mode || 'false') === 'true';
+            $('cfg-free-mode').classList.toggle('on', fm);
+            $('cfg-free-label').textContent = fm ? 'On' : 'Off';
+        } catch { toast('Failed to load config', 'error'); }
+    }
+    window.saveConfig = async function(key, inputId) {
+        const val = $(inputId).value;
+        try {
+            await fetch(`${API}/api/config`, { method: 'PATCH', headers: hdr(), body: JSON.stringify({ configs: { [key]: val } }) });
+            toast(`Saved`, 'success');
+            if (key === 'admin_password' && val) { TOKEN = val; localStorage.setItem('tkm_token', TOKEN); }
+        } catch { toast('Save failed', 'error'); }
+    };
+    window.toggleFreeMode = async function() {
+        const btn = $('cfg-free-mode');
+        const newVal = btn.classList.contains('on') ? 'false' : 'true';
+        try {
+            await fetch(`${API}/api/config`, { method: 'PATCH', headers: hdr(), body: JSON.stringify({ configs: { free_mode: newVal } }) });
+            btn.classList.toggle('on', newVal === 'true');
+            $('cfg-free-label').textContent = newVal === 'true' ? 'On' : 'Off';
+            toast(`Free mode ${newVal === 'true' ? 'enabled' : 'disabled'}`, 'success');
+        } catch { toast('Failed', 'error'); }
+    };
+    window.copyVal = async function(id) {
+        try { await navigator.clipboard.writeText($(id).value); toast('Copied', 'success'); } catch {}
+    };
+
+    async function loadTokens() {
+        try {
+            const r = await fetch(`${API}/api/tokens`, { headers: hdr() });
+            const tokens = await r.json();
+            const tbody = $('tokens-tbl');
+            if (!tokens.length) { tbody.innerHTML = ''; $('empty-tokens').classList.remove('hidden'); return; }
+            $('empty-tokens').classList.add('hidden');
+            const now = new Date();
+            tbody.innerHTML = tokens.map(t => {
+                const ts = t.token.length > 20 ? t.token.substring(0,10)+'\u2026'+t.token.slice(-6) : t.token;
+                const lu = t.last_used ? new Date(t.last_used).toLocaleDateString('en-CA') : '\u2014';
+                const type = t.is_admin ? '<span class="badge badge-active">admin</span>' : '<span class="badge badge-exhausted">user</span>';
+                let expDisp = '\u2014';
+                let expired = false;
+                if (t.expires_at) {
+                    const ed = new Date(t.expires_at);
+                    expDisp = ed.toLocaleDateString('en-CA');
+                    if (ed < now) { expired = true; expDisp = `<span style="color:var(--err)">${expDisp}</span>`; }
+                }
+                return `<tr${expired?' style="opacity:.5"':''}>
+                    <td class="c-id">${t.id}</td>
+                    <td><span class="c-key">${esc(ts)}</span></td>
+                    <td style="color:var(--fg3)">${esc(t.name||'\u2014')}</td>
+                    <td>${type}</td>
+                    <td class="c-id">${t.is_admin ? '\u221e' : t.quota_limit}</td>
+                    <td class="c-id">${t.is_admin ? '\u2014' : t.quota_used}</td>
+                    <td><span class="badge badge-${t.status}">${t.status}</span></td>
+                    <td class="c-date">${expDisp}</td>
+                    <td class="c-date">${lu}</td>
+                    <td><div class="c-acts" style="justify-content:flex-end;">
+                        <button class="btn-icon" onclick="copyKey('${escA(t.token)}')" title="Copy">&#128203;</button>
+                        ${!t.is_admin ? `<button class="btn-icon" onclick="resetTokenUsage(${t.id})" title="Reset">&#8635;</button>` : ''}
+                        ${!t.is_admin ? `<button class="btn-icon danger" onclick="deleteToken(${t.id})" title="Delete">&#128465;</button>` : ''}
+                    </div></td></tr>`;
+            }).join('');
+        } catch { toast('Failed to load tokens', 'error'); }
+    }
+    window.createToken = async function() {
+        const name = $('tk-name').value.trim();
+        const token = $('tk-token').value.trim();
+        const quota = parseInt($('tk-quota').value) || 1000;
+        const expiresRaw = $('tk-expires').value;
+        const expires_at = expiresRaw ? new Date(expiresRaw + 'T23:59:59Z').toISOString() : null;
+        try {
+            const r = await fetch(`${API}/api/tokens`, { method: 'POST', headers: hdr(), body: JSON.stringify({ name, token, quota_limit: quota, expires_at }) });
+            if (!r.ok) throw new Error(await r.text());
+            const d = await r.json();
+            toast(`Created: ${d.token.substring(0,16)}\u2026`, 'success');
+            closeModals(); $('tk-name').value=''; $('tk-token').value=''; $('tk-expires').value='';
+            loadTokens();
+        } catch (e) { toast(`Failed: ${e.message}`, 'error'); }
+    };
+    window.deleteToken = async function(id) {
+        if (!confirm('Delete this token?')) return;
+        try { await fetch(`${API}/api/tokens/${id}`, { method: 'DELETE', headers: hdr() }); toast('Deleted', 'success'); loadTokens(); }
+        catch { toast('Failed', 'error'); }
+    };
+    window.resetTokenUsage = async function(id) {
+        try { await fetch(`${API}/api/tokens/${id}/reset`, { method: 'POST', headers: hdr() }); toast('Reset', 'success'); loadTokens(); }
+        catch { toast('Failed', 'error'); }
+    };
+
+    const baseUrl = window.location.origin;
+    $('proxy-url').textContent = baseUrl;
+    $('doc-base-url').textContent = baseUrl;
+    document.querySelectorAll('#tab-docs pre code').forEach(el => {
+        el.textContent = el.textContent.replace(/BASE_URL/g, baseUrl);
+    });
+
+    const saved = localStorage.getItem('tkm_token');
+    if (saved) {
+        TOKEN = saved;
+        fetch(`${API}/api/stats`, { headers: hdr() })
+            .then(r => { if (r.ok) { $('login-screen').classList.add('hidden'); $('app').classList.remove('hidden'); refresh(); } })
+            .catch(() => {});
+    }
+})();
+</script>
+</body>
+</html>