HelpDesk First
Level-1 IT support self-service portal built with Next.js, TypeScript, and Tailwind CSS.
Production: https://helpdesk-first.vercel.app
New here? Read the product overview: how it
works, who it is for, safety model, data/vendors, and rollout status.
What it does
HelpDesk First helps users resolve common Level-1 IT problems without needing to run the website locally. It includes a searchable knowledge base of 100 common support issues, category and platform filters, and a guided troubleshooting flow with success feedback and escalation reports.
Network-related guides also include a browser-based network check widget for measuring connectivity to this site.
Cloud features include installable/offline PWA support, ticket screenshots,
live ticket status, web push alerts, and a public system status page. Apply
supabase/cloud-features.sql after the base
schema, then configure the service-role key, webhook secret, VAPID keys, and
optional Sentry variables from .env.example. Wire the Supabase ticket
webhook to /api/push/ticket-webhook; Sentry and push notifications are
no-ops when unconfigured.
Accounts (Supabase)
Optional accounts power bookmarks, saved guide progress, guide ratings, and support tickets. Apply supabase/schema.sql, then set NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY in your environment. Password reset uses Supabase email; add <site>/auth/callback to the Supabase Redirect URL allowlist (the existing https://helpdesk-first.vercel.app/** wildcard covers it). The site works without these variables; accounts are simply disabled.
Signup security
Set NEXT_PUBLIC_TURNSTILE_SITE_KEY to enable the Cloudflare Turnstile widget on
signup, login, admin login, and password-reset forms. Configure the Turnstile
secret in Supabase Authentication → Attack Protection, not in the app. Turn on
Authentication → Email → Confirm email and update the confirmation template to
include {{ .Token }} alongside the confirmation link so users can verify with
the 6-digit code or the link.
AI rate limiting
For production, set HELP_DESK_AI_RATE_LIMIT_PROVIDER=upstash and configure UPSTASH_REDIS_REST_URL plus UPSTASH_REDIS_REST_TOKEN (or connect the Vercel Upstash integration, which provides KV_REST_API_URL / KV_REST_API_TOKEN) to use a distributed Upstash Redis limiter. Local AI intake requires HELP_DESK_AI_RATE_LIMIT_PROVIDER=memory; otherwise /api/ai/intake returns 429 Rate limiting is not configured. Keep the provider set to memory for local development and previews.
Grounded provider and knowledge governance features are disabled by default.
Set HELP_DESK_AI_PROVIDER=mock (or anthropic/shadow with a server-only
ANTHROPIC_API_KEY), HELP_DESK_AI_MODEL, and
HELP_DESK_AI_DAILY_CALL_BUDGET as needed. Set
HELP_DESK_KNOWLEDGE_GOVERNANCE_ENABLED=true only after applying
supabase/knowledge-governance.sql; this enables approved-guide governance,
citations, provider telemetry, and the admin Knowledge page.
Requester agent (Phase C1)
The optional requester-side agent is disabled by default. Apply
supabase/requester-agent.sql, then set
HELP_DESK_REQUESTER_AGENT_ENABLED=true and explicitly allow organizations
with HELP_DESK_REQUESTER_AGENT_ORG_ALLOWLIST. C1 is read-only: it searches
approved guides, reads stored diagnostics, reads the signed-in requester's
directory status, and reads that requester's ticket history. It never changes
device, account, ticket, or organization state. Keep actions, autorun, and
vision disabled. Phase C4 screenshot input is documented in
SETUP-NOTES-C4.md and remains disabled unless
HELP_DESK_REQUESTER_AGENT_VISION_ENABLED=true and the organization is
allowlisted.
Use HELP_DESK_AI_PROVIDER=mock for a deterministic Wi-Fi smoke test. The
agent uses bounded budgets, untrusted-data wrapping, denylist/tripwire safety
halts, kill-switch checks, and an append-only encrypted session audit. Set
the C1 budget variables in .env.example; enable only with a pilot watch and
the existing human handoff path. The legacy assistant remains unchanged when
UI v2 or the requester-agent flag is off. Research and live device collection
remain deferred to C2 on the staff-side path.
Requester-agent web search is separately disabled by default with
HELP_DESK_AGENT_WEB_SEARCH_ENABLED=false; it also requires
HELP_DESK_RESEARCH_ENABLED=true and a configured research provider. Searches
are limited to three per session. Community sources are context only, never
instructions or action evidence; user steps still come from approved guides.
See SETUP-NOTES-PR15.md before enabling.
Requester-agent C2
Requester actions are disabled by default. Enable the base agent and action
flag separately, and allowlist the organization before piloting. Every action
is policy checked, consent bound to a run and plan step, gateway executed,
verified, rollback-aware, and confirmed by the requester before resolution.
See SETUP-NOTES-C2.md and the pilot runbook for setup and verification.
Phase C3 ladder setup and session consent are documented in
SETUP-NOTES-C3.md and docs/REQUESTER-AGENT-C3.md.
Operations export
Apply supabase/operations.sql, then set
OPERATIONS_EXPORT_KEY, optional OPERATIONS_PSEUDONYM_SALT, and
the secure admin dashboard variables in .env.example. Export with
curl -H "Authorization: Bearer $OPERATIONS_EXPORT_KEY" https://your-site.example/api/admin/operations/export.
The response maps to LiveTicketsTable: Ticket ID, Created At, Updated At,
Status, Priority, Category, Issue Title, User Key, Assigned Agent, SLA Due,
First Response At, Resolved At, Platform, and Has Attachment. Age Minutes and
SLA State remain Excel formulas. Traffic and agent queue data map to
TrafficTimelineTable and AgentQueueTable.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
