Skip to content

The portal

The portal is WhyGraph's front door. It is one long-running server that holds all your projects, shows each one in the Explorer and the Chat assistant, runs every scan, and serves each project's evidence and rationale to your coding agents over HTTP MCP at /mcp/<slug>.

You start it once with whygraph up, open it in a browser, and add repositories from the Projects page. There is no per-repo setup command: the portal does what whygraph init used to do, with a preview of every file it will touch.

flowchart LR
    browser["Browser<br/>(Explorer + Chat)"]
    agents["Claude Code, Cursor,<br/>VS Code, Codex"]
    subgraph portal["whygraph-portal (Docker, 127.0.0.1 only)"]
        api["API + MCP<br/>/api, /mcp/&lt;slug&gt;"]
        runner["Scan runner"]
    end
    subgraph pg["whygraph-portal-postgres (Docker, no published port)"]
        db[("Portal database<br/>projects, settings,<br/>encrypted keys, scan history")]
    end
    repos[("Your repos<br/>(shared folders)")]

    browser --> api
    agents -- "HTTP MCP" --> api
    api --> db
    api --> runner
    runner -- "whygraph scan" --> repos
    api -- "reads .whygraph + .codegraph" --> repos
    hooks["git hooks"] -- "POST /api/projects/&lt;slug&gt;/scans" --> api

What lives where

Thing Where
Portal settings, project list, API keys and GitHub tokens (encrypted), scan history The portal database: Postgres in the whygraph-portal-postgres container, its files in postgres/ under the portal's data directory, ~/.local/share/whygraph on your host
The encryption key for those keys and tokens, and database backups The data directory, as secret.key and backups/
A project's evidence, descriptions, rationale cache and chat history The repository itself, in .whygraph/whygraph.db
A project's CodeGraph index The repository itself, in .codegraph/
Clones of GitHub repositories you added by URL Under the data directory, in repos/<slug>
The folders, port and image the portal was started with ~/.config/whygraph on your host

Because each project's databases stay in its own repository, removing a project from the portal never deletes your history, and a 1.x repository keeps the data it already has. See Upgrading. The portal's own database is the one thing to back up; see Backup and restore.

Where to next

  • Start the portal

    whygraph up, the first-run setup, and the other host commands.

    Start the portal

  • Shared folders

    The portal runs in Docker and only sees the folders you share with it.

    Shared folders

  • Adding projects

    A local repo or a GitHub URL, configure, initialize, first scan.

    Adding projects

  • Connecting agents

    The MCP entry each agent gets, and what to know about ports and approval prompts.

    Connecting agents

  • Security model

    Loopback only, where keys live, and what the portal will not do to your repo.

    Security model

  • Backup and restore

    whygraph backup, the automatic dump before an upgrade, and how to restore.

    Backup and restore

  • Upgrading

    From 1.x, add your repos like new ones.

    Upgrading