# How to Start the Streamlit Frontend UI for Graph-RAG Agent

> Start the Streamlit frontend UI for your Graph-RAG Agent by running streamlit run frontend/app.py from the repository root. Access the web interface at http://localhost:8501.

- Repository: [GLK/graph-rag-agent](https://github.com/1517005260/graph-rag-agent)
- Tags: how-to-guide
- Published: 2026-02-23

---

**Run `streamlit run frontend/app.py` from the repository root to launch the Graph-RAG Agent web interface on `http://localhost:8501`.**

The graph-rag-agent repository ships with a standalone Streamlit frontend that communicates with the FastAPI backend via HTTP. This guide explains exactly how to start the Streamlit frontend UI using the official entry point and configuration files found in the `frontend/` directory.

## Launch Command and Entry Point

The frontend entry point is located at [`frontend/app.py`](https://github.com/1517005260/graph-rag-agent/blob/main/frontend/app.py). This script initializes the entire user interface through its `main()` function, which orchestrates page configuration, session state management, and component rendering.

To start the UI, execute the following from the repository root:

```bash
cd graph-rag-agent/
streamlit run frontend/app.py

```

By default, this starts a local web server on `http://localhost:8501` and opens the interface in your default browser.

### What Happens When You Launch

When you run the launch command, [`frontend/app.py`](https://github.com/1517005260/graph-rag-agent/blob/main/frontend/app.py) executes the following initialization sequence:

1. **Configures the page** via `st.set_page_config` – sets the title, icon, and wide layout mode.
2. **Initializes session state** via `init_session_state` – preserves chat history, selected agent, and debug flags across reruns.
3. **Starts performance monitoring** via `init_performance_monitoring`.
4. **Injects custom CSS** via `custom_css` for styling adjustments.
5. **Renders the sidebar** via `display_sidebar` for navigation and settings.
6. **Displays the chat interface** via `display_chat_interface`, or a two-column layout with `display_debug_panel` on the right when debug mode is enabled.

## Configuration via Environment Variables

The frontend reads configuration from environment variables defined in [`frontend/frontend_config/settings.py`](https://github.com/1517005260/graph-rag-agent/blob/main/frontend/frontend_config/settings.py). These settings allow you to customize the backend connection and default behavior without modifying code.

### Override the Backend API URL

By default, the frontend connects to `http://localhost:8000`. To point it to a different FastAPI backend:

```bash
export FRONTEND_API_URL="http://my-server:8000"
streamlit run frontend/app.py

```

### Enable Debug Mode

To start the UI with the debug panel visible by default:

```bash
export FRONTEND_DEFAULT_DEBUG=true
streamlit run frontend/app.py

```

This activates the two-column layout in `display_chat_interface`, showing the debug panel alongside the chat interface.

## Programmatic Launch Methods

For automated deployments or Docker containers, you can launch the frontend programmatically using Python's `subprocess` module:

```python
import subprocess

# Optional: Start the FastAPI backend

subprocess.Popen(["python", "server/main.py"])

# Launch the Streamlit frontend

subprocess.run(
    ["streamlit", "run", "frontend/app.py"],
    check=True
)

```

This approach ensures the backend is running before the frontend attempts to connect via the HTTP client defined in [`frontend/utils/api.py`](https://github.com/1517005260/graph-rag-agent/blob/main/frontend/utils/api.py).

## Key Frontend Architecture Files

Understanding these files helps troubleshoot startup issues:

- **[`frontend/app.py`](https://github.com/1517005260/graph-rag-agent/blob/main/frontend/app.py)** – Main entry point containing the `main()` function that wires together all UI components.
- **[`frontend/frontend_config/settings.py`](https://github.com/1517005260/graph-rag-agent/blob/main/frontend/frontend_config/settings.py)** – Loads `FRONTEND_API_URL`, `FRONTEND_DEFAULT_DEBUG`, and other environment variables.
- **[`frontend/utils/api.py`](https://github.com/1517005260/graph-rag-agent/blob/main/frontend/utils/api.py)** – HTTP client wrapper that respects the `FRONTEND_API_URL` setting when communicating with the backend.
- **[`frontend/components/chat.py`](https://github.com/1517005260/graph-rag-agent/blob/main/frontend/components/chat.py)** – Implements the chat interface that renders messages and handles streaming responses.

## Summary

- The primary entry point for the Streamlit frontend is [`frontend/app.py`](https://github.com/1517005260/graph-rag-agent/blob/main/frontend/app.py), which contains the `main()` function orchestrating the UI.
- Launch the interface by running `streamlit run frontend/app.py` from the repository root, accessible by default at `http://localhost:8501`.
- Configure the backend connection using the `FRONTEND_API_URL` environment variable defined in [`frontend/frontend_config/settings.py`](https://github.com/1517005260/graph-rag-agent/blob/main/frontend/frontend_config/settings.py).
- Enable debug mode by setting `FRONTEND_DEFAULT_DEBUG=true` to activate the two-column layout with the debug panel.
- For production deployments, use programmatic launch methods to manage both the FastAPI backend and Streamlit frontend processes.

## Frequently Asked Questions

### What port does the Graph-RAG Agent frontend use by default?

The Streamlit frontend starts on port **8501** by default (`http://localhost:8501`). This is Streamlit's default behavior and can be changed using Streamlit's command-line flags, such as `streamlit run frontend/app.py --server.port 8502`.

### Why does the frontend fail to connect to the backend?

The frontend attempts to reach the FastAPI backend at the URL specified by `FRONTEND_API_URL` (default: `http://localhost:8000`). If the backend isn't running on that address, the HTTP client in [`frontend/utils/api.py`](https://github.com/1517005260/graph-rag-agent/blob/main/frontend/utils/api.py) will throw connection errors. Ensure you've started the backend with `python server/main.py` and that the `FRONTEND_API_URL` environment variable matches your backend's actual address.

### Can I run the frontend without the debug panel?

Yes. The debug panel only appears when `debug_mode` is enabled in the session state. By default, this is controlled by the `FRONTEND_DEFAULT_DEBUG` environment variable (set to `false` by default). Running `streamlit run frontend/app.py` without setting this variable starts the normal single-column chat interface via `display_chat_interface`.

### How do I customize the default agent shown in the UI?

The default agent selection is configured through environment variables loaded by [`frontend/frontend_config/settings.py`](https://github.com/1517005260/graph-rag-agent/blob/main/frontend/frontend_config/settings.py). Set the appropriate `FRONTEND_` variables in your `.env` file or export them before starting the application. The `init_session_state` function in [`frontend/app.py`](https://github.com/1517005260/graph-rag-agent/blob/main/frontend/app.py) reads these values to initialize the session state on startup.