How to Enable and Customize the Gradio User Interface for Testing and Interaction in Private‑GPT

To enable the Gradio UI in Private‑GPT, set ui.enabled: true in your configuration file, adjust the path, default_mode, and system prompts under the ui section, then run python -m private_gpt.main to mount the interface at the configured endpoint.

The Gradio web interface in the zylon-ai/private-gpt repository provides a visual way to test RAG (Retrieval-Augmented Generation), search, and summarization modes without writing API calls. By default, the UI is disabled and must be activated through YAML configuration, after which it exposes a fully customizable frontend mounted on your FastAPI application.

Enabling the Gradio Interface

The UI is controlled by the UISettings class defined in [private_gpt/settings/settings.py](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/settings/settings.py). To activate the interface, locate your active configuration file (for example, private_gpt.yaml, settings.yaml, or a profile-specific file) and add or modify the ui block.

Set enabled to true and define the path where the interface will be served:

ui:
  enabled: true          # Enable the web interface

  path: "/ui"            # URL route where Gradio will be mounted

If enabled remains false (the default), the launcher will skip mounting the UI entirely, making the backend API-only.

Configuring UI Behavior and Defaults

Once enabled, you can customize interaction defaults through the same configuration section. The model exposes several fields that populate the initial state of the Gradio components in [private_gpt/ui/ui.py](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/ui/ui.py).

Default Mode Selection

Specify which operating mode the UI should start in using default_mode. Valid values correspond to the application’s ingestion strategies:

ui:
  default_mode: "RAG"    # Options: RAG, Search, Basic, Summarize

System Prompts

Pre-load default system instructions for different interaction types using the following keys. These strings populate the system prompt text boxes when the UI initializes:

ui:
  default_chat_system_prompt: "You are a helpful AI assistant."
  default_query_system_prompt: "Answer the question based only on the provided context."
  default_summarization_system_prompt: "Provide a concise summary of the following content."

File Management Controls

Toggle visibility of destructive file actions with boolean flags. When set to false, the corresponding buttons are hidden from the interface:

ui:
  delete_file_button_enabled: true       # Show/hide single file delete

  delete_all_files_button_enabled: false # Show/hide delete all files

These values are passed directly to the visible parameter of Gradio Button components in the UI building logic.

Launching the Interface

After updating your configuration, you have two methods to start the interface depending on whether you need the full API backend or just the frontend.

Full Server Mode (Recommended)

Run the main application to start the FastAPI server with the UI automatically mounted at the configured path:

python -m private_gpt.main

Alternatively, using Uvicorn directly:

uvicorn private_gpt.main:app --host 0.0.0.0 --port 8001

The launcher code in [private_gpt/launcher.py](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/launcher.py) checks settings().ui.enabled and, if true, calls blocks.mount_gradio_app(app, path=settings().ui.path) to integrate the Gradio blocks with the FastAPI application.

Standalone UI Mode (Testing Only)

For rapid frontend iteration without the full backend ingestion pipeline, execute the UI module directly:

python -m private_gpt.ui.ui

This invokes the if __name__ == "__main__" block at the bottom of [private_gpt/ui/ui.py](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/ui/ui.py), launching Gradio on its own local server (typically http://127.0.0.1:7860). Note that this mode runs the UI in isolation and may lack full backend functionality unless properly initialized.

Customizing the Theme and Styling

Visual customization is handled within [private_gpt/ui/ui.py](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/ui/ui.py). The interface uses the gr.themes.Soft theme with a slate primary hue by default.

To modify the color scheme, locate the gr.Blocks constructor (typically inside the _build_ui_blocks method or similar) and adjust the theme parameters:

# In private_gpt/ui/ui.py

theme = gr.themes.Soft(primary_hue="teal")  # Change from slate to teal

with gr.Blocks(title="Private‑GPT", theme=theme, css=...) as blocks:
    # UI definition continues...

For deeper styling, edit the embedded CSS string passed to the css parameter. This allows you to adjust logo dimensions, header backgrounds, chat bubble colors, and footer layouts without altering the core application logic.

Key Source Files and Architecture

Understanding the codebase structure helps with advanced customizations:

• [private_gpt/settings/settings.py](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/settings/settings.py) – Contains the UISettings Pydantic model that validates all ui.* configuration keys.
• [private_gpt/launcher.py](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/launcher.py) – Orchestrates application startup; conditionally mounts the Gradio app based on settings().ui.enabled.
• [private_gpt/main.py](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/main.py) – Entry point that initializes the FastAPI application and triggers the launcher.
• [private_gpt/ui/ui.py](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/ui/ui.py) – Core UI implementation including Gradio blocks, callback handlers, file upload/delete logic, and mode switching.
• [private_gpt/ui/images.py](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/ui/images.py) – Stores the SVG logo and other image assets rendered in the header.

Summary

• Set ui.enabled: true in your YAML configuration to activate the Gradio interface.
• Customize the mount path, default_mode, and system prompts through the ui configuration section.
• Control file management visibility with delete_file_button_enabled and delete_all_files_button_enabled flags.
• Launch the full stack with python -m private_gpt.main or test the UI standalone with python -m private_gpt.ui.ui.
• Modify visual themes and CSS in [private_gpt/ui/ui.py](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/ui/ui.py) to match your branding.

Frequently Asked Questions

How do I change the default chat mode from RAG to Basic?

Set ui.default_mode: "Basic" in your configuration file. Valid options are RAG, Search, Basic, and Summarize, which correspond to the different interaction modes defined in the ingestion service. Restart the server after saving the configuration change.

Where can I hide the delete file buttons for safety?

In your configuration YAML, set ui.delete_file_button_enabled: false and ui.delete_all_files_button_enabled: false. These booleans control the visible attribute of the Gradio Button components in [private_gpt/ui/ui.py](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/ui/ui.py), completely removing the UI elements rather than just disabling them.

What is the difference between running main.py and ui.py directly?

Running python -m private_gpt.main starts the complete FastAPI application with all API routes, ingestion workers, and the Gradio UI mounted as a sub-application. Running python -m private_gpt.ui.ui executes only the Gradio frontend code via the if __name__ == "__main__" block, which is useful for rapid UI prototyping but does not initialize the full backend context database or ingestion pipeline.

How do I customize the Gradio theme colors?

Edit the theme instantiation in [private_gpt/ui/ui.py](https://github.com/zylon-ai/private-gpt/blob/main/private_gpt/ui/ui.py). Change the primary_hue parameter in gr.themes.Soft(primary_hue="slate") to any Gradio-supported color name or hex code (e.g., "blue", "#FF5733"). You can also pass custom CSS strings to the css parameter in gr.Blocks to override specific component styles.

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