# What is LlamaBoard and How Does It Work: The Complete Guide to LlamaFactory's Web UI

> Discover LlamaBoard, the Gradio web UI for LlamaFactory. Easily configure, launch, and monitor LLM fine-tuning jobs via your browser. No Python code needed.

- Repository: [Yaowei Zheng/LlamaFactory](https://github.com/hiyouga/LlamaFactory)
- Tags: how-to-guide
- Published: 2026-03-04

---

**LlamaBoard is the interactive Gradio-based web interface for LlamaFactory that enables users to configure, launch, and monitor LLM fine-tuning jobs through a browser without writing Python code.**

LlamaBoard serves as the graphical front-end for the **LlamaFactory** open-source project, providing a browser-based alternative to command-line training workflows. This web UI abstracts complex training configurations into intuitive forms and dashboards, allowing researchers and developers to execute SFT, LoRA, RLHF, and DPO training jobs while monitoring progress in real time.

## LlamaBoard Architecture and Core Components

### Entry Point and CLI Integration

The `llamafactory-cli webui` command serves as the primary entry point, defined in [`src/launcher.py`](https://github.com/hiyouga/LlamaFactory/blob/main/src/launcher.py). This CLI wrapper parses command-line arguments and invokes the `launch()` function from [`src/webui.py`](https://github.com/hiyouga/LlamaFactory/blob/main/src/webui.py), initiating the Gradio server on port **7860** by default.

### Web UI Server ([`src/webui.py`](https://github.com/hiyouga/LlamaFactory/blob/main/src/webui.py))

The [`src/webui.py`](https://github.com/hiyouga/LlamaFactory/blob/main/src/webui.py) module constructs the Gradio interface using `gr.Blocks()`, organizing functionality into three primary tabs:

- **Training**: Configuration forms for model selection, dataset upload, LoRA/QLoRA parameters, and hyperparameters
- **Inference**: Model loading and chat interface for testing checkpoints
- **Monitor**: Real-time visualization of training metrics and system utilization

### Training Engine Integration

When users initiate training, [`src/webui.py`](https://github.com/hiyouga/LlamaFactory/blob/main/src/webui.py) spawns a subprocess via `subprocess.Popen` to execute [`src/train.py`](https://github.com/hiyouga/LlamaFactory/blob/main/src/train.py). This process isolation prevents the Gradio event loop from blocking during GPU-intensive operations. The `train.run()` function handles the actual training logic, supporting SFT, LoRA, QLoRA, DeepSpeed, and FSDP configurations.

## How LlamaBoard Works: Operational Workflow

### Configuration and Launch Process

LlamaBoard translates UI form inputs into YAML-compatible configurations that mirror LlamaFactory's CLI arguments. When users click **Start**, the system:

1. Validates model paths, dataset formats, and hyperparameter ranges
2. Serializes configurations into temporary YAML files or command-line arguments
3. Invokes the training subprocess with GPU allocation and distributed training flags

### Real-Time Monitoring and Logging

The [`src/llamafactory/extras/logging.py`](https://github.com/hiyouga/LlamaFactory/blob/main/src/llamafactory/extras/logging.py) module implements a custom `logging.Handler` that bifurcates output streams:

- **File logging**: Writes structured logs to `logs/llamaboard.log`
- **UI streaming**: Emits formatted messages to the Gradio output component via websocket
- **External trackers**: Integrates with TensorBoard, Wandb, MLflow, and SwanLab through `SummaryWriter` events

Simultaneously, [`src/llamafactory/extras/plotting.py`](https://github.com/hiyouga/LlamaFactory/blob/main/src/llamafactory/extras/plotting.py) generates Matplotlib and Plotly visualizations for loss curves, learning rate schedules, and GPU utilization metrics that render in the **Monitor** tab.

### Model Export and Checkpoint Management

Upon training completion, LlamaBoard exposes trained checkpoints through the **Inference** tab for immediate testing. The export functionality serializes LoRA adapters or merged full models into downloadable zip archives, leveraging the same serialization logic used in the CLI workflow.

## Practical Usage Examples

### Launching LlamaBoard from Command Line

Start the web interface with default settings:

```bash
llamafactory-cli webui

```

Specify custom host and port for remote access:

```bash
llamafactory-cli webui --host 0.0.0.0 --port 8000

```

### Programmatic Launch in Python

Integrate LlamaBoard into custom applications:

```python
from llamafactory.webui import launch

config = {
    "model_name_or_path": "meta-llama/Meta-Llama-3-8B",
    "train_dataset": "data/v1_sft_demo.jsonl",
    "lora_rank": 8,
    "monitor": "llamaboard"
}

launch(config=config, share=True)  # share=True creates public Gradio link

```

### Running Training via Web Interface

1. Navigate to `http://127.0.0.1:7860` after launching
2. Select the **Training** tab and configure:
   - Model: `meta-llama/Meta-Llama-3-8B`
   - Dataset: Upload JSONL file or select predefined dataset
   - Method: LoRA with rank 8
   - Hyperparameters: Learning rate 1e-4, 3 epochs
3. Click **Start** to initiate the subprocess
4. Switch to the **Monitor** tab to observe real-time loss curves and GPU utilization

### Side-by-Side Monitoring with TensorBoard

While LlamaBoard runs, launch TensorBoard in a separate terminal:

```bash
tensorboard --logdir logs/tensorboard

```

Access TensorBoard at `http://localhost:6006` to view the same training metrics that appear in LlamaBoard's **Monitor** tab.

## Summary

- **LlamaBoard** is the official Gradio-based web interface for LlamaFactory, providing browser-based control over LLM fine-tuning workflows.
- The architecture separates concerns between the UI server ([`src/webui.py`](https://github.com/hiyouga/LlamaFactory/blob/main/src/webui.py)), CLI launcher ([`src/launcher.py`](https://github.com/hiyouga/LlamaFactory/blob/main/src/launcher.py)), and training engine ([`src/train.py`](https://github.com/hiyouga/LlamaFactory/blob/main/src/train.py)), using subprocess isolation to maintain UI responsiveness.
- Real-time monitoring relies on custom logging handlers in [`src/llamafactory/extras/logging.py`](https://github.com/hiyouga/LlamaFactory/blob/main/src/llamafactory/extras/logging.py) and plotting utilities in [`src/llamafactory/extras/plotting.py`](https://github.com/hiyouga/LlamaFactory/blob/main/src/llamafactory/extras/plotting.py), supporting both built-in visualizations and external trackers like TensorBoard and Wandb.
- Users can launch LlamaBoard via `llamafactory-cli webui`, programmatically through the Python API, or within Docker containers exposing port 7860.

## Frequently Asked Questions

### What is the difference between LlamaBoard and LlamaFactory?

LlamaFactory is the underlying Python framework and CLI tool for fine-tuning large language models, while **LlamaBoard** is the optional Gradio-based web interface built on top of it. LlamaBoard provides graphical forms and dashboards that generate the same YAML configurations and training commands used by the LlamaFactory CLI, making it accessible to users who prefer browser-based workflows over terminal commands.

### Can I use LlamaBoard for distributed training with DeepSpeed or FSDP?

Yes. LlamaBoard supports distributed training configurations including **DeepSpeed** and **FSDP** (Fully Sharded Data Parallel). When configuring a training job in the web interface, you can select distributed training options and specify ZeRO stages or sharding strategies. The UI passes these parameters to [`src/train.py`](https://github.com/hiyouga/LlamaFactory/blob/main/src/train.py), which initializes the appropriate distributed backend before spawning the training subprocess.

### How does LlamaBoard handle real-time log streaming without blocking the interface?

LlamaBoard uses **subprocess isolation** to prevent the Gradio event loop from freezing during GPU-intensive operations. When you click **Start**, [`src/webui.py`](https://github.com/hiyouga/LlamaFactory/blob/main/src/webui.py) spawns the training process via `subprocess.Popen`. A background thread polls the subprocess stdout/stderr, parsing specially formatted log lines (tagged with `[LLAMABOARD]`) to update the UI components. This architecture ensures the browser interface remains responsive while training progresses on the GPU.

### Is it possible to run LlamaBoard in a Docker container?

Yes. LlamaBoard is fully containerized through the official Dockerfiles in the `docker/` directory (such as `docker/docker-cuda/Dockerfile`). These images expose port **7860** by default and include all dependencies required to run the Gradio interface. You can launch the container with GPU support and access LlamaBoard through your browser at `http://localhost:7860`, making it suitable for cloud deployments and reproducible environments.