# How to Access the llmfit Web Dashboard: Complete Setup Guide

> Learn how to access the llmfit Web dashboard with this complete setup guide. Run the binary with the --serve flag and open the provided URL to get started.

- Repository: [Alex Jones/llmfit](https://github.com/AlexsJones/llmfit)
- Tags: how-to-guide
- Published: 2026-08-19

---

**To access the llmfit Web dashboard, run the binary with the `--serve` flag and open the printed URL (default `http://127.0.0.1:8080/`) in your browser.**

The llmfit project, hosted at `AlexsJones/llmfit`, bundles a lightweight HTTP server that serves an interactive web dashboard built with React. When launched in serve mode, the application automatically detects your hardware specifications and exposes a REST API that powers the browser-based interface for exploring model compatibility scores.

## Launching the Dashboard

The llmfit binary uses **Clap** for command-line parsing and exposes a `serve` subcommand that initializes the web interface.

### Build and Run

Compile the project in release mode for optimal performance, then start the server:

```bash

# Build the binary

cargo build --release

# Start the dashboard server (default: 127.0.0.1:8080)

cargo run --release -- --serve

```

Upon startup, the process executes the `run_serve` function in [`llmfit-tui/src/serve_api.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-tui/src/serve_api.rs), which prints the listening address:

```text
llmfit dashboard listening on http://127.0.0.1:8080/
  GET /health
  GET /api/v1/system
  GET /api/v1/models?limit=20&min_fit=marginal&sort=score

```

Open the printed URL in any modern browser to load the **React** single-page application.

### Custom Host and Port

To bind the server to a specific network interface or port, use the `--host` and `--port` options:

```bash

# Expose to all network interfaces on port 3000

cargo run --release -- --serve --host 0.0.0.0 --port 3000

```

## Architecture Overview

The dashboard consists of a Rust backend serving embedded static assets and a React frontend that consumes JSON endpoints.

### Backend Implementation

In [`llmfit-tui/src/serve_api.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-tui/src/serve_api.rs), the `run_serve` function constructs an **Axum** router within a **Tokio** runtime. The server performs three critical tasks:

- **Hardware Detection**: Calls `SystemSpecs::detect` to gather system specifications
- **Asset Serving**: Serves embedded web files ([`index.html`](https://github.com/AlexsJones/llmfit/blob/main/index.html), JavaScript, CSS) via `serve_web_path` and `find_web_asset`, using a static `ASSET_MAP` for lookups with proper `Content-Type` headers
- **API Routing**: Registers REST endpoints under `/api/v1/*` that return JSON serialized by helper functions in [`llmfit-tui/src/serve_shared.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-tui/src/serve_shared.rs)

The `AppState` struct maintains shared state across requests, including the detected hardware specifications and model database.

### Frontend Implementation

The dashboard interface lives in the `llmfit-web/` directory:

- **[`llmfit-web/index.html`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-web/index.html)**: The HTML shell that loads the React application
- **[`llmfit-web/src/main.jsx`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-web/src/main.jsx)**: The React entry point that initializes the SPA and makes API calls to the backend

When you access the root URL, the Axum server returns [`index.html`](https://github.com/AlexsJones/llmfit/blob/main/index.html), which bootstraps the React app. The frontend then fetches data from `/api/v1/system` and `/api/v1/models` to render the hardware summary and sortable model fit tables.

## API Endpoints and Direct Access

The dashboard is supported by a REST API that you can also query directly without the web interface.

### Available Routes

- **`GET /health`**: Returns server health status
- **`GET /api/v1/system`**: Returns hardware specifications as JSON (handled by `system_json` in [`serve_shared.rs`](https://github.com/AlexsJones/llmfit/blob/main/serve_shared.rs))
- **`GET /api/v1/models`**: Returns model compatibility data with optional query parameters (`limit`, `ram_gb`, `min_fit`, `sort`)

### Querying the API

Retrieve system information directly using **curl**:

```bash

# Get hardware specifications

curl http://127.0.0.1:8080/api/v1/system

```

Filter model results based on your hardware constraints:

```bash

# List top 5 models that fit a 16 GB RAM machine

curl "http://127.0.0.1:8080/api/v1/models?limit=5&ram_gb=16"

```

The JSON responses are marshalled through helper functions in [`serve_shared.rs`](https://github.com/AlexsJones/llmfit/blob/main/serve_shared.rs), converting core structures like `SystemSpecs` and `ModelFit` into serialized format.

## Summary

- Launch the dashboard by running the llmfit binary with the `--serve` flag
- The server binds to `127.0.0.1:8080` by default, configurable via `--host` and `--port`
- The backend uses **Tokio** and **Axum** (`run_serve` in [`llmfit-tui/src/serve_api.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-tui/src/serve_api.rs)) to serve embedded React assets and REST endpoints
- The frontend is a React SPA located in `llmfit-web/` that consumes `/api/v1/*` endpoints
- Direct API access is available for system information and model compatibility queries

## Frequently Asked Questions

### What port does the llmfit Web dashboard use by default?

By default, the server listens on port **8080** bound to localhost (`127.0.0.1`). The `run_serve` function in [`llmfit-tui/src/serve_api.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-tui/src/serve_api.rs) prints the exact URL on startup, which typically displays as `http://127.0.0.1:8080/`.

### Can I access the dashboard API without opening the web interface?

Yes. The REST API endpoints are accessible via standard HTTP clients. You can query endpoints like `/api/v1/system` and `/api/v1/models` directly using curl or any HTTP library, as the backend serves JSON independently of the React frontend.

### Where is the React frontend code located in the repository?

The frontend source resides in the `llmfit-web/` directory. The entry point is [`llmfit-web/index.html`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-web/index.html), which loads the JavaScript bundle from [`llmfit-web/src/main.jsx`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-web/src/main.jsx). These assets are embedded into the binary at compile time and served by the Axum router in [`serve_api.rs`](https://github.com/AlexsJones/llmfit/blob/main/serve_api.rs).

### Which Rust web framework does llmfit use to serve the dashboard?

The project uses **Axum** for HTTP routing and **Tokio** for the asynchronous runtime. The implementation in [`llmfit-tui/src/serve_api.rs`](https://github.com/AlexsJones/llmfit/blob/main/llmfit-tui/src/serve_api.rs) creates the router, handles static asset serving through `serve_web_path`, and manages the `SystemSpecs` state shared across requests.