Skip to main content
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

1

Install Cognee

pip install cognee
2

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

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.
VariableRead byDefaultPurpose
NEXT_PUBLIC_LOCAL_API_URLLocal UI frontendhttp://localhost:8000Backend API base URL used by the local UI. Set this when the backend is not reachable at the default local address.
UI_APP_URLBackend APIhttp://localhost:3000Origin 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_ORIGINSBackend 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.

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