llamactl/docs/user-guide/web-ui.md

Web UI Guide

The Llamactl Web UI provides an intuitive interface for managing your Llama.cpp instances.

Overview

The web interface is accessible at http://localhost:8080 (or your configured host/port) and provides:

• Instance management dashboard
• Real-time status monitoring
• Configuration management
• Log viewing
• System information

Dashboard

Instance Cards

Each instance is displayed as a card showing:

• Instance name and status indicator
• Model information (name, size)
• Current state (stopped, starting, running, error)
• Resource usage (memory, CPU)
• Action buttons (start, stop, configure, logs)

Status Indicators

• 🟢 Green: Instance is running and healthy
• 🟡 Yellow: Instance is starting or stopping
• 🔴 Red: Instance has encountered an error
• ⚪ Gray: Instance is stopped

Creating Instances

Add Instance Dialog

1. Click the "Add Instance" button

2. Fill in the required fields:

   • Name: Unique identifier for your instance
   • Model Path: Full path to your GGUF model file
   • Port: Port number for the instance

3. Configure optional settings:

   • Threads: Number of CPU threads
   • Context Size: Context window size
   • GPU Layers: Layers to offload to GPU
   • Additional Options: Advanced Llama.cpp parameters

4. Click "Create" to save the instance

Model Path Helper

Use the file browser to select model files:

• Navigate to your models directory
• Select the .gguf file
• Path is automatically filled in the form

Managing Instances

Starting Instances

1. Click the "Start" button on an instance card
2. Watch the status change to "Starting"
3. Monitor progress in the logs
4. Instance becomes "Running" when ready

Stopping Instances

1. Click the "Stop" button
2. Instance gracefully shuts down
3. Status changes to "Stopped"

Viewing Logs

1. Click the "Logs" button on any instance
2. Real-time log viewer opens
3. Filter by log level (Debug, Info, Warning, Error)
4. Search through log entries
5. Download logs for offline analysis

Configuration Management

Editing Instance Settings

1. Click the "Configure" button
2. Modify settings in the configuration dialog
3. Changes require instance restart to take effect
4. Click "Save" to apply changes

Advanced Options

Access advanced Llama.cpp options:

# Example advanced configuration
options:
  rope_freq_base: 10000
  rope_freq_scale: 1.0
  yarn_ext_factor: -1.0
  yarn_attn_factor: 1.0
  yarn_beta_fast: 32.0
  yarn_beta_slow: 1.0

System Information

Health Dashboard

Monitor overall system health:

• System Resources: CPU, memory, disk usage
• Instance Summary: Running/stopped instance counts
• Performance Metrics: Request rates, response times

Resource Usage

Track resource consumption:

• Per-instance memory usage
• CPU utilization
• GPU memory (if applicable)
• Network I/O

User Interface Features

Theme Support

Switch between light and dark themes:

1. Click the theme toggle button
2. Setting is remembered across sessions

Responsive Design

The UI adapts to different screen sizes:

• Desktop: Full-featured dashboard
• Tablet: Condensed layout
• Mobile: Stack-based navigation

Keyboard Shortcuts

• Ctrl+N: Create new instance
• Ctrl+R: Refresh dashboard
• Ctrl+L: Open logs for selected instance
• Esc: Close dialogs

Authentication

Login

If authentication is enabled:

1. Navigate to the web UI
2. Enter your credentials
3. JWT token is stored for the session
4. Automatic logout on token expiry

Session Management

• Sessions persist across browser restarts
• Logout clears authentication tokens
• Configurable session timeout

Troubleshooting

Common UI Issues

Page won't load:

• Check if Llamactl server is running
• Verify the correct URL and port
• Check browser console for errors

Instance won't start from UI:

• Verify model path is correct
• Check for port conflicts
• Review instance logs for errors

Real-time updates not working:

• Check WebSocket connection
• Verify firewall settings
• Try refreshing the page

Browser Compatibility

Supported browsers:

• Chrome/Chromium 90+
• Firefox 88+
• Safari 14+
• Edge 90+

Mobile Access

Responsive Features

On mobile devices:

• Touch-friendly interface
• Swipe gestures for navigation
• Optimized button sizes
• Condensed information display

Limitations

Some features may be limited on mobile:

• Log viewing (use horizontal scrolling)
• Complex configuration forms
• File browser functionality