> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognee.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Run the UI Locally

> Launch the Cognee Cloud UI on your own machine — no account required

The Cognee Cloud UI can run entirely on your local machine using `cognee.start_ui()`. This gives you the same interface as Cognee Cloud without needing an account or any cloud infrastructure.

**Before you start:**

* Complete the [Quickstart](/getting-started/quickstart) to make sure your environment is set up
* Have a valid LLM and embedding provider configured (see [Setup Configuration](/setup-configuration/overview)). You don't have to pre-configure the LLM API key — in local mode you can paste it into the UI after launch (see below).

## Start the local UI

<Steps>
  <Step title="Install Cognee">
    ```bash theme={null}
    pip install cognee
    ```
  </Step>

  <Step title="Add data and build a knowledge graph">
    Load some data into Cognee and run `cognify` to build the knowledge graph before launching the UI.

    ```python theme={null}
    import asyncio
    import cognee

    async def main():
        await cognee.add("Natural language processing (NLP) is an interdisciplinary subfield of computer science.")
        await cognee.add("Machine learning (ML) is a subset of artificial intelligence.")
        await cognee.cognify()

    asyncio.run(main())
    ```
  </Step>

  <Step title="Launch the UI server">
    Call `cognee.start_ui()` to start the local frontend and backend servers. Setting `open_browser=True` opens the interface in your default browser automatically.

    ```python theme={null}
    import os
    import signal
    import time
    import cognee

    child_pids = []
    server = cognee.start_ui(
        pid_callback=child_pids.append,
        port=3000,
        open_browser=True,
        start_backend=True,
        backend_port=8000,
    )

    if server:
        print("UI available at http://localhost:3000")
        try:
            while server.poll() is None:
                time.sleep(1)
        except KeyboardInterrupt:
            server.terminate()
            server.wait()
            for pid in child_pids:
                if pid != server.pid:
                    os.kill(pid, signal.SIGTERM)
    ```

    The UI is available at **[http://localhost:3000](http://localhost:3000)**, and the backend API is available at **[http://localhost:8000](http://localhost:8000)**. Press `Ctrl+C` to stop the server when you are done.

    <Note>
      `start_ui()` launches the frontend in local mode. If you didn't configure an LLM API key beforehand, the Overview shows a banner with an **Add your LLM API key** modal — paste your key there and it is applied to the running backend immediately, with no `.env` edit or restart. See [LLM API key (local mode)](/cognee-cloud/ui/dashboard#llm-api-key-local-mode).
    </Note>
  </Step>
</Steps>

## Full example

The complete script below combines all three steps:

```python theme={null}
import asyncio
import os
import signal
import time
import cognee


async def main():
    # Add sample data
    await cognee.add(
        "Natural language processing (NLP) is an interdisciplinary subfield of computer science and information retrieval."
    )
    await cognee.add(
        "Machine learning (ML) is a subset of artificial intelligence that focuses on algorithms and statistical models."
    )

    # Build the knowledge graph
    await cognee.cognify()

    # Start the UI and backend
    child_pids = []
    server = cognee.start_ui(
        pid_callback=child_pids.append,
        port=3000,
        open_browser=True,
        start_backend=True,
        backend_port=8000,
    )

    if server:
        print("UI available at http://localhost:3000")
        print("Press Ctrl+C to stop...")
        try:
            while server.poll() is None:
                time.sleep(1)
        except KeyboardInterrupt:
            server.terminate()
            server.wait()
            for pid in child_pids:
                if pid != server.pid:
                    os.kill(pid, signal.SIGTERM)
    else:
        print("Failed to start the UI server.")


if __name__ == "__main__":
    asyncio.run(main())
```

<Note>
  `cognee.start_ui()` launches the same frontend that powers Cognee Cloud. Data stays on your machine — nothing is sent to any external service.
</Note>

## Add an LLM API key from the dashboard

Cognee needs an LLM API key to process uploads. If you launch `cognee.start_ui()` or `cognee-cli -ui` without `LLM_API_KEY` set in your environment, the dashboard detects the missing key on load and shows a yellow warning banner:

> No LLM API key configured — Cognee can't process uploads until you add one.

Click **Add your API key now →** to open a modal, paste your key, and save. The UI sends the key to the running backend via `POST /v1/settings`, which also exports it as `LLM_API_KEY` into the backend process environment — the next upload works immediately, with no restart or `.env` edit required.

The modal uses whatever provider and model the backend is currently configured with (defaults to `openai` / `gpt-5-mini`). To use a different provider or model, set `LLM_PROVIDER` and `LLM_MODEL` in your environment before launching the UI, then paste the matching API key in the modal.

<Note>
  The pasted key lives in the backend process only. It is not persisted to a `.env` file, so it will be lost when the backend restarts. For a permanent setup, add `LLM_API_KEY` (and any other provider variables) to your `.env` before starting the UI.
</Note>

## Connect the UI to the backend

The local UI and the Cognee backend API are separate servers. When you use `cognee.start_ui(..., start_backend=True)` or `cognee-cli -ui`, the UI runs on **port 3000** and the backend runs on **port 8000** by default. If you run either service on a different host or port, configure both the frontend's backend URL and the backend's allowed browser origins.

| Variable                    | Read by           | Default                 | Purpose                                                                                                                          |
| --------------------------- | ----------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `NEXT_PUBLIC_LOCAL_API_URL` | Local UI frontend | `http://localhost:8000` | Backend API base URL used by the local UI. Set this when the backend is not reachable at the default local address.              |
| `UI_APP_URL`                | Backend API       | `http://localhost:3000` | Origin allowed through the backend's CORS policy. Set this to the UI's URL when you serve the UI on a different host or port.    |
| `CORS_ALLOWED_ORIGINS`      | Backend API       | —                       | Comma-separated list of allowed origins. When set, it takes precedence over `UI_APP_URL` — use it to allow more than one origin. |

For example, if the UI and backend are served from different machines:

```dotenv theme={null}
# .env
NEXT_PUBLIC_LOCAL_API_URL=http://192.168.1.20:8000
UI_APP_URL=http://192.168.1.50:3000
```

Restart the UI and backend after changing these values so both processes read the updated environment.

<Note>
  `UI_APP_URL` is unrelated to the MCP server's `API_URL` variable, which instead points the [Cognee MCP server](/cognee-mcp/mcp-quickstart#api-mode-shared-knowledge-graph) at a self-hosted backend. The two are easy to confuse because both wire a component to the Cognee API.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="Cognee Cloud" href="/cognee-cloud/overview" icon="cloud">
    Move to the hosted version for managed infrastructure and collaboration features.
  </Card>

  <Card title="Core Concepts" href="/core-concepts/overview" icon="brain">
    Learn about remember, recall, improve, and forget operations.
  </Card>
</CardGroup>