Run the UI Locally

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 to make sure your environment is set up
Have a valid LLM and embedding provider configured (see Setup Configuration). 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

Install Cognee

pip install cognee

Add data and build a knowledge graph

Load some data into Cognee and run cognify to build the knowledge graph before launching the UI.

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())

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.

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, and the backend API is available at http://localhost:8000. Press Ctrl+C to stop the server when you are done.

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).

Full example

The complete script below combines all three steps:

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())

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

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.

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.

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:

# .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.

UI_APP_URL is unrelated to the MCP server’s API_URL variable, which instead points the Cognee MCP server at a self-hosted backend. The two are easy to confuse because both wire a component to the Cognee API.

Troubleshooting the local UI

"Cognee frontend is not available" / prompted to download

In a pip-installed package, the frontend is not bundled in the runtime environment. On first launch, start_ui() looks for a local cognee-frontend directory and, if it can’t find one, prints:

The cognee frontend is not available on your system.

It then asks Would you like to download the frontend now? (y/N). Answer y to download the frontend that matches your installed version from GitHub releases and cache it in ~/.cognee/ui-cache/ (a one-time setup per cognee version, reused offline afterwards).To skip the prompt and download automatically, pass auto_download=True to cognee.start_ui(). The cognee-cli -ui command already sets this, so it never prompts.If the download fails with a 404, the release for your version does not exist on GitHub yet or the installed version is a development/mismatched build. Install a stable release of cognee (pip install -U cognee) and try again.

localhost refuses to connect (ERR_CONNECTION_REFUSED)

If the browser can’t reach http://localhost:3000, the frontend server isn’t running. Check these in order:

Node.js and npm are installed. The UI runs on Next.js and needs Node.js. If either tool is missing, start_ui() first tries to install nvm and Node.js automatically on supported platforms; if that fails, it logs Cannot start UI and you should install Node.js from nodejs.org before relaunching.
The port is free. start_ui() returns None and logs ports already in use if port 3000 (frontend) or 8000 (backend) is taken. Stop the conflicting process, or pass a different port / backend_port.
Give Next.js time to compile. After launch the server prints The UI will be available once Next.js finishes compiling. The first compile takes a few seconds — reload once you see the [FRONTEND] logs report it’s ready.
Watch the [FRONTEND] logs. If the process exits early, start_ui() logs Frontend server failed to start — the streamed [FRONTEND] output above it shows the underlying error (for example a failed npm install).

Next steps

Cognee Cloud

Move to the hosted version for managed infrastructure and collaboration features.

Core Concepts

Learn about remember, recall, improve, and forget operations.

Getting Started

Local UI

Navigating the UI

Cloud Functionality

Agent Integrations

Connections

Reference

Start the local UI

Full example

Add an LLM API key from the dashboard

Connect the UI to the backend

Troubleshooting the local UI

Next steps

Cognee Cloud

Core Concepts

​Start the local UI

​Full example

​Add an LLM API key from the dashboard

​Connect the UI to the backend

​Troubleshooting the local UI

​Next steps

Cognee Cloud

Core Concepts

Start the local UI

Full example

Add an LLM API key from the dashboard

Connect the UI to the backend

Troubleshooting the local UI

Next steps