Start the portal¶
You need the Docker install - the portal runs in the WhyGraph
image, and the whygraph shim on your PATH starts and stops it.
That starts two named containers in the background - whygraph-portal, the portal itself, and
whygraph-portal-postgres, the Postgres database it keeps its own data in - waits until the database is
ready, and prints the portal's address:
Open http://127.0.0.1:8765. Both containers restart with Docker (--restart unless-stopped), so you
start them once, not per session. The database container has no published port: only the portal can
reach it, over their private Docker network. Idle, it uses about 30 MiB of RAM; the shared CodeGraph
server adds about 130-300 MiB while it runs and is stopped after 10 idle minutes.
Docker is the only install
The portal needs the Docker install. Running whygraph portal natively exists for WhyGraph
development and is not supported for everyday use; see the
CLI reference.
First run¶
The first time you open the portal it shows a Welcome screen. Enter your name and continue - that creates the single local user. The screen also shows the portal's mode (Local) and the folders it can see, and carries the shared-machine note.
You land on an empty Projects page, and it is a short checklist instead of a blank one:
- Add an LLM key - under Settings, so descriptions, rationale cards and Chat have a model.
- Add a project - share a folder that holds your repositories if you have not yet, then add a project.
- Connect your agent - from the project's Overview, once it exists.
Each step has one button and ticks itself off when it is done. Dismiss hides the checklist in this browser, and Getting started in the Projects header brings it back; it disappears for good when every step is done. Projects can be added before a key is saved - the first scan never calls an LLM.
The host commands¶
These run on your host, through the shim, not inside a container of their own.
| Command | What it does |
|---|---|
whygraph up [--port N] [--add-folder DIR] |
Start the portal and its database, or recreate the portal when the folders, port or image changed. Already running with nothing changed is a no-op. |
whygraph down |
Stop and remove both containers, the portal first. It waits up to 30 seconds so a running scan is stopped cleanly and recorded as interrupted. |
whygraph status |
Each container's state (running, restarting or not created), plus the URL, image, database image and shared folders. |
whygraph logs |
Follow the portal container's logs. The database has its own: docker logs whygraph-portal-postgres. |
whygraph folders [--remove DIR] |
List the shared folders, or remove one (which recreates the portal container). |
whygraph backup |
Dump the portal database into the data directory. See Backup and restore. |
whygraph update [--version X.Y.Z] [--check] [--force] |
Update to the newest release (or a given one): download its installer, dump the database, install, recreate the portal. --check only reports. See Upgrading. |
Stopping the portal never touches your repositories or the data directory. Start it again and everything is where you left it.
Choosing a port¶
The default is 8765. To use another one:
The port is remembered in ~/.config/whygraph/port, so a later plain whygraph up keeps it. Without
--port and without that file, the shim reads the exported WHYGRAPH_PORT, then falls back to
8765.
A port change also has consequences for the repositories you already added: their markers and some agent config entries carry the port. The portal rewrites what it safely can when it starts and reports, per project, what is left. See Connecting agents.
Where your data goes¶
| Path on the host | Holds |
|---|---|
~/.local/share/whygraph (override with WHYGRAPH_DATA) |
Everything the portal keeps: see the next table |
~/.config/whygraph/folders |
One shared folder per line |
~/.config/whygraph/port |
The port chosen with --port |
Inside the data directory:
| Path | Holds |
|---|---|
postgres/ |
The portal database's files (projects, settings, encrypted keys, scan history), one subdirectory per Postgres major version |
postgres.password |
The database password, generated on the first whygraph up (mode 0600) |
secret.key |
The encryption key for the keys and tokens stored in the database |
projects/ |
Each project's WhyGraph history, projects/<org>/<slug>/whygraph.db (projects/local/<slug>/ in local mode), with its project.json identity file and migration backups/. Back it up with the rest of the data directory |
backups/ |
Database dumps from whygraph backup and the automatic pre-upgrade dump |
runs/ |
Scan progress and log files |
logs/codegraph.log (and .1) |
The hosted CodeGraph server's log, rotated at 1 MiB. Disposable |
locks/codegraph/ |
One small lock file per project, so a scan and the CodeGraph tools never write an index at once. Safe to leave in place; disposable |
codegraph-home/ |
The CodeGraph server's working directory and home. Empty, because its telemetry is off. Disposable |
repos/ |
Production mode only: the copies of the repositories imported from GitHub |
The data directory is created with mode 0700, owned by you, and the database files in it are owned
by you too. Keep it out of every project folder: the portal refuses to share a folder that contains it
or sits inside it.
Stopping and upgrading¶
whygraph down stops the portal and its database; the data stays in the data directory. To upgrade,
run whygraph update, which dumps the database, installs the newer version and runs whygraph up for
you. Re-running the installer by hand also works: it changes the image the shim uses, and the next
whygraph up notices the new image and recreates the portal container, with the same data. When a release also
moves the pinned Postgres image, up first dumps the running database into backups/, then recreates
the database container too. See Upgrading.
Removing WhyGraph¶
There is no uninstall command. To remove WhyGraph from a machine:
- Remove each project in the portal and let it strip what it wrote to the repository (the git hooks
and markers; see Adding projects). Your repositories keep their
.codegraph/index and the history stays in the data directory either way, until you delete the data directory in step 3. whygraph down.- Delete the data directory (
~/.local/share/whygraph; this deletes all project history too, so copyprojects/first if you want it),~/.config/whygraph, and thewhygraphandwhygraph-mcpscripts the installer put on yourPATH(~/.local/binby default). - Optionally, remove the images (
docker image ls ghcr.io/mtrdesign/whygraph, thendocker image rmthe ones listed, and the same forpostgres) and the network (docker network rm whygraph-portal).
Take a backup first if you may want the portal's data back.
Environment credentials do not reach the portal¶
Nothing from your shell environment is passed into the container. GH_TOKEN, GITHUB_TOKEN,
ANTHROPIC_API_KEY, OPENAI_API_KEY, DEEPSEEK_API_KEY and OPENROUTER_API_KEY set on your host
are ignored by the portal - enter keys and tokens under Settings in the portal instead.
The first whygraph up that finds one of these variables set prints a one-time note naming them (never
their values).
If something is in the way¶
- A leftover
whygraph-servecontainer from 1.x may hold port 8765.whygraph upwarns about it; remove it withwhygraph serve --stop. - CodeGraph crashed or will not start.
whygraph logsshows the tail of a crash; the full server log islogs/codegraph.log, and a project's Overview opens it with Open CodeGraph log. - A crash-looping portal shows as
restartinginwhygraph status;whygraph logshas the reason. A portal that cannot reach its database within a minute exits, and Docker retries it; check thedatabase:line ofwhygraph statusanddocker logs whygraph-portal-postgres. upsays the database did not become ready. No portal is started;docker logs whygraph-portal-postgreshas the reason.uprefuses a database another Postgres major version created, after a release moved the pin. Follow the dump and restore recipe.upsayspostgres.passwordis missing but the database exists. Restore the file from your backup of the data directory. A new password would not open the existing database.- A second portal on the same data directory, or on the same database, is refused: the portal holds an exclusive lock on both.