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), including LLM_API_KEY. The local UI has no in-app field for it, so set it in your environment or .env before you start.

Start the local UI

Install Cognee

pip install cognee

Store some memory

Store content with remember() before launching the UI — it ingests the data and builds the knowledge graph in one call, so the interface has something to show.

import asyncio
import cognee

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

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. Set LLM_API_KEY (and any other provider variables) in your environment or .env before starting it — Cognee cannot process uploads without one, and the UI has no in-app field for it.

Run it with Docker instead

If you have the cognee repository checked out, the bundled Compose file ships a ui profile that starts the frontend and backend together — no pip install or start_ui() call needed:

docker compose --profile ui up

The UI is served on http://localhost:3000 and the backend on http://localhost:8000, the same ports start_ui() uses. The ui profile runs the published cognee/cognee-ui image rather than building from your checkout, so you can also run the UI on its own — against a backend started any other way — with plain docker run:

docker run -p 3000:3000 -e COGNEE_BACKEND_URL=https://cognee.example.com cognee/cognee-ui

Leave COGNEE_BACKEND_URL unset for the usual localhost setup. See Connect the UI to the backend for how it relates to NEXT_PUBLIC_LOCAL_API_URL, and Docker Deployment for the ui-dev profile, which builds the hot-reloading UI from source instead.

Full example

The complete script below combines all three steps:

import asyncio
import os
import signal
import time
import cognee


async def main():
    # Store sample data — ingests it and builds the knowledge graph
    await cognee.remember(
        [
            "Natural language processing (NLP) is an interdisciplinary subfield of computer science and information retrieval.",
            "Machine learning (ML) is a subset of artificial intelligence that focuses on algorithms and statistical models.",
        ]
    )

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

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
`COGNEE_BACKEND_URL`	Local UI server, at run time	Unset — the browser derives the address (see below)	Backend API base URL, read on every request rather than baked into the build. Set this to point a UI container at a backend; it is the only one of the two that a prebuilt image can honour.
`NEXT_PUBLIC_LOCAL_API_URL`	Local UI frontend, at build time	In the browser, the page’s own protocol and hostname on port `8000`; server-side, `http://localhost:8000`	The older, build-time way to set the same thing. Still honoured, so existing setups keep working, but `NEXT_PUBLIC_*` values are inlined into the JavaScript bundle by `next build` and cannot be changed on an already-built image.
`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.

COGNEE_BACKEND_URL must be an absolute http(s) URL, for example http://localhost:8000. Anything else is a configuration error: in the Docker image the entrypoint reports it and refuses to start, rather than booting and failing every request. A trailing slash is stripped. Because the browser calls the backend directly, the value is the address as seen from the browser — a container name or an internal-only hostname will not work. Give either variable a scheme, host, and port only — the UI appends /api/v1/... itself. When neither variable is set, the UI resolves the backend address in the browser from the page you are on, so API calls stay on the host you typed in the address bar. The resolution order is:

COGNEE_BACKEND_URL, if set. The UI server renders it into the page on each request, and the browser reads it from there — which is how one prebuilt image can serve any backend.
NEXT_PUBLIC_LOCAL_API_URL, if set — whatever value was inlined when the UI was built, in the browser and on the server.
In the browser — the current page’s protocol and hostname, with the port pinned to 8000. Loading the UI on http://127.0.0.1:3000 targets http://127.0.0.1:8000; on http://localhost:3000 it targets http://localhost:8000.
During server-side rendering, where there is no browser location — http://localhost:8000.

Only the protocol and hostname come from the browser; the port is always 8000 unless you override one of the variables. Set a backend URL when the backend lives on a different machine than the UI, or on a port other than 8000 — COGNEE_BACKEND_URL if you are running the published UI image, NEXT_PUBLIC_LOCAL_API_URL if you build the frontend yourself. Deriving the host in the browser keeps the auth cookie on the host you are browsing, but it does not exempt you from the backend’s CORS policy. start_ui() and cognee-cli -ui start the backend with the default allowed origin http://localhost:3000, so browsing the UI on any other host — http://127.0.0.1:3000 included — needs a matching UI_APP_URL (or CORS_ALLOWED_ORIGINS) on the backend:

# .env — browsing the UI on 127.0.0.1 instead of localhost
UI_APP_URL=http://127.0.0.1:3000

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.

Cloud-only pages

The local UI is the same frontend as Cognee Cloud, but the pages that report on a hosted workspace’s usage and spend are not part of the open-source build. In local mode they render a text-only notice — Build your own dashboard from the API, or use the hosted one in Cognee Cloud — with an Open Cognee Cloud link, instead of the real surface:

Surface	Local mode
Activity	Activity is a Cognee Cloud feature
Analytics	Analytics is a Cognee Cloud feature
Memory Coverage	Memory Coverage is a Cognee Cloud feature
Overview → memory flow diagram	Live memory graph is a Cognee Cloud feature, over a blurred placeholder
Overview → Cost Savings, Memory Coverage, Activity panels	The same notice inside each panel frame

Billing also does not apply locally, and the credit banners and pulse survey described on the Overview page never appear. Of the sidebar footer’s controls, only Onboarding is shown locally — Book a call and Feedback are cloud-only. Everything else works the same locally as it does in the cloud: Datasets, Search, Skills, Sessions, the Graph page, and Integrations.

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.

The auth cookie is host-scoped, and localhost and 127.0.0.1 are distinct hosts to the browser even though they resolve to the same machine. If the page and the API are not on the same host, the cookie never applies to the requests that check it: the GET /api/v1/users/me check comes back 401 and the UI sends you back to /local-login on every attempt.The UI now derives the API host from the page you loaded, so the cookie is always set on the host you are browsing. What it does not do is widen the backend’s CORS policy. If you sign in on a host other than localhost, work through these in order:

Allow the origin you browse to. start_ui() and cognee-cli -ui start the backend allowing only http://localhost:3000, so signing in on http://127.0.0.1:3000 is refused before the cookie is ever set — the login form reports Cannot connect to local backend at http://127.0.0.1:8000. Is it running?. Set UI_APP_URL (or CORS_ALLOWED_ORIGINS) to the exact origin in your address bar and restart the backend — see Connect the UI to the backend.
Check COGNEE_BACKEND_URL and NEXT_PUBLIC_LOCAL_API_URL. Either explicit value wins over the browser-derived host — COGNEE_BACKEND_URL first. If one points at a different hostname than the one in your address bar, either unset it or make the two match.
Clear stale cookies for the old host after changing any of this, then sign in again.

The simplest fix is to browse the UI on http://localhost:3000, which every default already covers.

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

Run it with Docker instead

Full example

Connect the UI to the backend

Cloud-only pages

Troubleshooting the local UI

Next steps

Cognee Cloud

Core Concepts

​Start the local UI

​Run it with Docker instead

​Full example

​Connect the UI to the backend

​Cloud-only pages

​Troubleshooting the local UI

​Next steps

Cognee Cloud

Core Concepts

Start the local UI

Run it with Docker instead

Full example

Connect the UI to the backend

Cloud-only pages

Troubleshooting the local UI

Next steps