How to Access the FreeLLMAPI Admin Dashboard: Complete Setup and Login Guide

The FreeLLMAPI admin dashboard runs on port 3001 by default and automatically detects first-run setup through the /api/auth/status endpoint, presenting either an account creation form or login screen based on your server state.

FreeLLMAPI provides a React-based admin dashboard that ships alongside the router server, giving you full control over API keys, provider routing, and analytics through a web interface. This guide walks you through accessing the dashboard based on how it's implemented in the tashfeenahmed/freellmapi source code, from initial setup to daily administration.

Understanding the Dashboard Architecture

The dashboard consists of two tightly integrated components:

• Express server (server/src/app.ts) — Serves static UI files and exposes /api/* admin endpoints
• React SPA (client/src/main.tsx) — Boots the interface and handles authentication flows

All admin functionality routes through server/src/routes/auth.ts, which implements session-based authentication using signed cookies or Bearer tokens passed in the Authorization header.

Starting the Server

Before accessing the dashboard, ensure your FreeLLMAPI router is running:

# Docker Compose (recommended)

docker-compose up -d

# Or local development

npm run dev  # in server/ directory

By default, the server listens on port 3001. The dashboard becomes available immediately once the process starts.

First-Run Setup: Creating the Admin Account

When no dashboard users exist, FreeLLMAPI detects this state and requires initial setup. The status endpoint at GET /api/auth/status returns needsSetup: true in this case, triggering the setup flow in the UI.

Verify Setup Requirement (API)

curl -s http://localhost:3001/api/auth/status | jq .

{
  "needsSetup": true,
  "authenticated": false,
  "email": null
}

Source reference: server/src/routes/auth.ts lines 73-80 implement this check against the user database.

Create the Initial Admin Account

The setup endpoint (POST /api/auth/setup) creates the first admin account. For local access, no additional verification is required:

curl -X POST http://localhost:3001/api/auth/setup \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"SuperSecret123"}' \
  | jq .

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…",
  "email": "admin@example.com"
}

Remote Setup with Verification Code

If accessing from a remote host (detected by IP), the server requires a one-time setup code printed to the server logs:

# First, check logs for setup code

docker logs freellmapi-server  # look for: "Setup code: ABCD-EFGH-1234"

# Then include it in your request

curl -X POST http://localhost:3001/api/auth/setup \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"SuperSecret123","setupCode":"ABCD-EFGH-1234"}' \
  | jq .

Source reference: server/src/routes/auth.ts lines 83-96 implement this security measure.

Logging Into an Existing Dashboard

For subsequent access, use the login endpoint (POST /api/auth/login):

curl -X POST http://localhost:3001/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"SuperSecret123"}' \
  | jq .

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…",
  "email": "admin@example.com"
}

Using the Web Interface

Browser Access

Navigate directly to the server root:

open http://localhost:3001   # macOS

# or manually enter http://localhost:3001 in any browser

The AuthGate component (client/src/components/auth-gate.tsx lines 29-71) immediately queries /api/auth/status and renders the appropriate form:

• Setup mode — Shows "Create your account" form posting to /api/auth/setup
• Login mode — Shows email/password form posting to /api/auth/login

Upon successful authentication, setToken stores the session and the full dashboard renders with navigation to keys, routing rules, and analytics.

Making Authenticated API Calls

Extract and use your token for programmatic access:

TOKEN=$(curl -s -X POST http://localhost:3001/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"SuperSecret123"}' | jq -r .token)

curl -H "Authorization: Bearer $TOKEN" http://localhost:3001/api/keys | jq .

Key Implementation Files

Understanding these source files helps troubleshoot access issues:

File	Purpose
server/src/routes/auth.ts	Authentication endpoints: status, setup, login, logout
server/src/app.ts	Mounts admin router and static file serving
client/src/components/auth-gate.tsx	React auth gate with setup/login form logic
client/src/main.tsx	Dashboard SPA entry point
docs/architecture.md	High-level auth and routing documentation

Troubleshooting Common Access Issues

Dashboard shows 404

Verify the server built the client assets. The Express app serves static files from the client build directory—run npm run build in the client/ folder if developing locally.

Remote access blocked

Check for setup code requirement in server logs. The IP detection in auth.ts requires verification codes for non-local hosts.

Session expires immediately

Ensure JWT_SECRET is set in your environment. Session tokens are signed with this secret; missing configuration causes immediate invalidation.

Summary

• FreeLLMAPI admin dashboard runs at http://localhost:3001 by default, served by the same Express process handling API requests
• First-run detection via /api/auth/status automatically guides you through account creation
• Authentication supports both session cookies and Authorization: Bearer tokens for API access
• Remote setup security requires a one-time code from server logs when accessing from external IPs
• AuthGate component in client/src/components/auth-gate.tsx orchestrates the UI flow between setup and login states

Frequently Asked Questions

How do I reset a forgotten admin password?

FreeLLMAPI does not implement automated password recovery in the open-source version. You must access the server filesystem directly to reset credentials, or redeploy with fresh state. Check server/src/routes/auth.ts for the user storage mechanism—typically SQLite or your configured database.

Can I run the dashboard on a different port?

Yes. The port is configured through environment variables in server/src/app.ts. Set PORT=3002 or your preferred value before starting the server, then access the dashboard at that port.

Is HTTPS supported for the admin dashboard?

The Express server in server/src/app.ts handles HTTP by default. For production HTTPS, deploy behind a reverse proxy (nginx, Traefik, Caddy) or modify the server bootstrap code to provide TLS certificates directly.

What's the difference between dashboard authentication and API key authentication?

Dashboard auth (session tokens via /api/auth/login) grants administrative access to configure providers and routing. API key authentication (passed to /v1/chat/completions) controls access to the LLM inference endpoints. These systems are separate—dashboard users manage API keys that external clients use.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}