Skip to content

Security model

In local mode the portal is built for one person on their own machine. It has no login. What keeps it safe is where it listens, what it refuses to do, and what it is never given. This page lists those boundaries so you can judge them.

It listens on loopback only

whygraph up publishes the portal on 127.0.0.1 and nothing else, and runs it on its own Docker network so other containers on the default bridge cannot reach its listener either. Outside the image, whygraph portal refuses any non-loopback --host unless you pass --dev-expose, which exists for development.

The database is network-only

The portal's own database runs in a second container, whygraph-portal-postgres, that publishes no port: it is reachable only from containers on the portal's whygraph-portal network, never from your host or your LAN.

  • Its password is generated on the first whygraph up into postgres.password in the data directory, mode 0600. It is mounted into both containers as a file, so it is never in an environment value, a command line, docker inspect, a log line or the portal's API.
  • Every data directory gets its own password, so another WhyGraph portal on the same network (a development one, say) cannot log in to yours.
  • Inside the database container, local connections need no password - that is how whygraph backup runs pg_dump. Anyone who can docker exec into it is already your user, who owns the database's files in the data directory anyway: the boundary is the same.

Your browser cannot be used against it

A local server with no login is a target for any web page you visit. The portal closes the usual routes:

  • Every /api request, GETs included, must carry an X-WhyGraph-Client: 1 header. A web page cannot add a custom header to a cross-origin request without a permission check the portal never grants, and the portal never sends CORS headers.
  • /api and /mcp reject Sec-Fetch-Site: cross-site and same-site, and any Origin that is not exactly the portal's own address (null included).
  • The Host header must be 127.0.0.1, localhost or [::1] with the portal's port, which defeats DNS rebinding: a rebinding domain carries its own name in Host.

Shared machines

Local mode is for single-user machines

The portal is reachable by every user of the machine through the loopback address, and it holds your LLM API keys and GitHub tokens. On a machine that other people log in to, another user can open the portal, read your projects' history and spend your keys. Do not run local mode on a shared host. For several people, use production mode, which has real accounts; otherwise use one machine per person.

The Welcome screen says the same thing the first time you open the portal.

Production mode

Setup is in Run in production.

Everything above describes local mode. In production mode the portal is reached over the network, so the checks change:

  • Sign-in is GitHub. Users sign in through an OAuth App with the read-only read:user scope and GitHub two-factor authentication required. The portal sends a random state and a PKCE challenge (S256) whose verifier it keeps in memory, bound to a host-only cookie, so the callback only works in the browser that started it and only once, within 10 minutes. GitHub redirects to a page of the app (/auth/github), which strips the one-time code from the address bar before posting it, so the /api origin checks need no exception, and the access log redacts that query. The portal reads the user, then revokes GitHub's token at once and keeps none. It stores the GitHub id (the identity), username, display name and avatar, never an email. Only the bootstrap admin has a password (argon2, 15 characters minimum, a common-password blocklist). A disabled account is refused at sign-in and its sessions end at once.
  • Sessions. The session is a random token whose hash only is stored in the database; the cookie is HttpOnly, SameSite=Lax, Secure over https, and set on the base host so it reaches every organization. Sessions last 30 days at most and 7 days idle, a password change rotates the current one and ends the others, and a reset ends all of them. Sign-in, setup and reset happen on the base host only.
  • Hosts. The Host must be the base host or exactly one valid label under it (<org>.<base host>); anything else, including www. and lookalike suffixes, gets 421. An organization is served only on its own host, and membership is checked on every request.
  • Origin. X-WhyGraph-Client is still required, cross-site and same-site requests to /api are refused, and an Origin must be exactly the request's own host, so a page on one organization cannot write to another's host. No CORS headers are sent.
  • Headers. Every response carries X-Frame-Options: DENY, a frame-ancestors 'none' content security policy, Referrer-Policy: same-origin and nosniff; /api responses and any response that sets a cookie are no-store; over https there is HSTS with includeSubDomains. A full script content security policy is not part of this release.
  • Throttling. Password sign-in failures are limited per account and address, GitHub sign-in starts and callbacks, setup and reset per address, adding members per organization (60 an hour, so the add form cannot be used to probe which usernames have accounts), and imports per organization (30 an hour). Webhook deliveries are not throttled: the signature check rejects a forged one first.
  • Roles. Members read and use projects; admins also manage people and per-project settings and keys; only owners touch owners and change the organization's settings and organization-level keys. Chat sessions are private to the user who started them. See Members.
  • No user-controlled markup is rendered on an organization host, because the session cookie is shared across them.
  • A dedicated base host. The cookie reaches every subdomain, so the base host must belong to WhyGraph alone. See why.
  • Instance admins can read every organization, read-only, and every such request is logged. Authentication events go to the whygraph.portal.audit log.
  • Projects come only from GitHub, through the GitHub App. The server refuses any other source. The app's private key never leaves the portal process: for each fetch and scan the portal mints an installation token scoped to the one repository and to read-only access (contents, metadata, pull requests, issues), valid for at most an hour. A scan receives it through a file in the data directory (runs/<id>.token, mode 0600, written atomically), never its environment; the portal rewrites the file before the token expires and deletes it when the scan ends, and leftovers are removed at start. CodeGraph never sees that file's name.
  • No personal access tokens. Storing a GitHub token is refused in production; every GitHub call a project makes uses the app's token. The import page's user authorization (8 hours) is kept in memory for the session, never in the database or a response, and must belong to the GitHub account the user signed in with.
  • Webhooks are verified first. POST /github/webhook is served only on the base host. The body is capped at 5 MiB, X-Hub-Signature-256 is required and compared in constant time against the raw body before anything is parsed (the older SHA-1 header alone is refused), and a missing or wrong signature is answered 401 and logged as webhook_rejected. A replayed delivery id is ignored. Projects are found by GitHub's numeric repository and installation ids, never by name.
  • A repository that tracks WhyGraph's state is refused. A repository whose commits contain .whygraph/ or .codegraph/ is not imported, and a fetch that finds them on the default branch fails before the checkout: a committed index, marker or backup would otherwise be served to every member. (A repository cannot influence where a project's WhyGraph database is: it is always in the portal's data directory.) See Run in production.
  • Git ignores global and system config. Every git process for a server copy runs with GIT_CONFIG_GLOBAL=/dev/null and GIT_CONFIG_NOSYSTEM=1, so an insteadOf, http.* or include in the host's git config cannot redirect a fetch. origin is set from the repository id before every fetch, and the checkout runs with hooks disabled.
  • No server paths. API answers never name a server path: a project imported from GitHub has no root in its payload, and removing one names no clone folder. A run's log starts with the user-level command ($ scan <flags>; the full command line goes to the portal's own log at debug level), and every log line and event, git's error text included, has the clone rewritten to . and the data directory to <data>. Local mode keeps the full paths and command line: they are your own machine's.
  • What is off. No shared folders, no local repositories, no /mcp, no git-hook scans. Agents reach a production portal's projects through a connected machine, not directly.

Connected machines

A platform project lets a local portal read a platform's history for one project. The credential for that is a connection token, and the design assumes the local portal runs on a developer's laptop and a repository on it is untrusted.

  • One token reaches one project, as one person. The token is wgc_ plus 32 random bytes. The platform stores only its SHA-256, so a database read cannot be replayed as a token. It names a project by id, never by slug, and the person's role and membership are re-checked on every call, so a role change applies to the next request and a removed member is cut off at once. An instance admin's read-only access never gets a token, and a token never carries an administrator's powers or a session.
  • Revocation follows membership. Removing a member, a member leaving, disabling an account, deleting a project or an organization, an admin revoking one token, and "Remove from this machine" all revoke the affected tokens, each with a reason the local portal can show. Re-enabling a disabled account does not restore its tokens: link again. A token unused for 90 days expires, and one never used expires after an hour, which cleans up a link abandoned halfway.
  • Linking is OAuth 2.0 authorization code with PKCE (S256). The local portal is a native app on a port the platform cannot know in advance, so the redirect is exactly http://127.0.0.1:<port>/connect/callback. The code lasts 60 seconds, works once, and is spent even when its verification fails. The platform builds the redirect itself, from a request it validated before rendering anything, so the consent page can only send the browser to a URL the server returned. Allow is skipped only when the platform vouches for an intent it issued to the same person, project and port.
  • The iss check. Every redirect carries the platform's own address (RFC 9207), and the local portal refuses a callback whose iss is not the platform it started with, before it uses the code. PKCE alone does not stop a rogue platform from being swapped in mid-flow; this does. The local portal also asks the address you entered for the platform's own address and follows it only to the immediate parent (an organization's address under the platform), which must confirm itself; any other answer is refused before consent.
  • /api/v1 takes a bearer token and nothing else. On that path the platform reads the Authorization: Bearer header and never a cookie, and everywhere else it ignores a bearer header and reads only the session cookie. A bearer token is not ambient, so a web page cannot use one, and the CSRF checks of the session routes need nothing new. Failed token lookups are throttled per address; evidence and rationale requests are throttled per token, limited to two at a time per organization, and capped in git work and body size per request. Git's own error text never appears in a response.
  • The token is never exposed. It lives encrypted in the local portal's database (the same Fernet store as other secrets), is decrypted only into the client that calls the platform, and is never in an API response, a log line, an error message, a command line or a child process's environment. wgc_ tokens are masked like GitHub's in anything a run writes. A scan child gets no token: the child environment is an allowlist the token is not on.
  • Only pushed data leaves your machine. See what leaves your machine. The client also checks every request body against the same models the platform enforces, and caps what it reads back.
  • A platform address is https. The local portal calls exactly two origins, the platform's base host and its organization host, follows no redirects, and refuses http (a development switch allows loopback only).
  • The local pages cannot be framed. In local mode every page the portal serves, not only /api, carries X-Frame-Options: DENY and frame-ancestors 'none', so /link and /connect/callback cannot be clickjacked. Local mode still sets no CORS headers.
  • The deep link carries no credential. Connect local WhyGraph links to http://127.0.0.1:<port>/link with the platform, organization, project and a one-time intent. The intent only lets the platform skip its Allow page for the same signed-in person, the same project and the same port, once, within 15 minutes; it grants nothing on its own, your local portal still asks you to press Connect, and the platform page never contacts the local one. Because that click on the platform is the approval, the card says under the button what it grants: WhyGraph on that port reads the project as you and, if your role allows, asks for rationale cards with the organization's AI keys. A made-up or expired intent, another person, another project or another port, and a project that lost its GitHub access, all get the normal Allow page.
  • A pre-approved link is bound to the port on the card. That port must be your own WhyGraph's: whatever answers there receives the link, and the platform will not ask again. Your local portal keeps the intent out of its access log (the /link and /setup queries are blanked), and the platform keeps it out of its own (/connect and the /signin round trip).
  • Visible to admins. An owner or admin of a project sees the machine name each member gave their connection, and can revoke it. See Connected machines.

Keys and tokens

  • LLM API keys and GitHub tokens are stored in the portal database encrypted (Fernet), and the API is write-only for them: the UI shows set ...a1b2, never the key.
  • Key tails are only for whoever can change the key. The last four characters, the "last used" time and the key actions go only to a caller who may change that key: an organization's keys to its owners, a project's keys to its admins. Everyone else gets "set" or "not set" and nothing more, in the API answer itself, not only in the page. An organization key's tail never appears on a project's settings.
  • "Test key" tests the stored key, never a typed one. No route accepts a key to test. The test makes one free, read-only call with the stored key - the provider's model listing (Anthropic, OpenAI, DeepSeek) or key endpoint (OpenRouter); Ollama has no key to test - follows no redirect, stops after 10 seconds, and reduces the answer to one word (works, rejected, rate limited, unreachable, unexpected). The provider's body is never returned, so a test cannot read what an address serves. Tests are limited to 10 per person and 60 per organization an hour, are not counted as usage, and in production each one is a key_tested security event naming the scope, provider and result, never the key.
  • Model suggestions use the stored key and return only model names. A model field's suggestions come from the provider's model listing, called with the stored key - never one you type - with no redirect followed and a 10-second limit. Only strings shaped like model ids are returned, at most 2,000, so a custom address cannot be used to read what it serves. Listings are limited to 30 per person and 120 per organization an hour (past that, a short built-in list is shown), are not counted as usage, and are open only to whoever can change that key: organization owners for the organization's keys, project admins for a project's.
  • A custom endpoint is tested where it points. When a provider has a custom base_url, the test calls that address with the key - the address the portal already sends that key to for every model call - so a test learns nothing an owner could not see from Chat's model list for the same endpoint. The address is not restricted to public networks, because a self-hosted gateway on a private address is a normal setup; the hourly limit bounds it.
  • The GitHub token test is local-only. It runs the add-project form's repository check against the project's own GitHub remote. Production stores no GitHub token, and answers 404 to it.
  • The encryption key is secret.key in the data directory. This protects a database dump (a whygraph backup file, say) or a copy of the database's files on their own. It does not protect against someone who can read your data directory, which holds both, which is why that directory is 0700 and the portal will not share a folder that contains it. A dump together with secret.key is as sensitive as the live data directory; backups/ is 0700 too.
  • Nothing from your shell environment enters the container. Keys you export in your shell are not passed to the portal. A portal started outside Docker removes ANTHROPIC_API_KEY, OPENAI_API_KEY, DEEPSEEK_API_KEY, OPENROUTER_API_KEY, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL and OPENAI_BASE_URL from its environment at start and logs their names: only keys and endpoints stored under Settings are used.
  • A scan runs as a child process with an allowlisted environment (PATH, HOME, locale, TZ, TLS and proxy variables). Keys and tokens reach it only as the variables that one scan needs, and any key that appears in a run's progress or log file is masked to its last four characters. Anything shaped like a provider key (sk-ant-..., sk-proj-..., sk-or-v1-...) is masked as well, even a key the portal never handed to the scan.
  • A GitHub token used for a fetch (in production, the installation token) is handed to git through a host-scoped credential helper. It is not in .git/config, argv, logs or run files, and is not sent to any other host. Anything shaped like a GitHub token in a run's output is masked, even when a tool already masked part of it.
  • Changing a provider's endpoint clears the key stored for the old one, and an endpoint found in a repository's whygraph.toml is never imported. A committed file cannot redirect your key to another server.

What agent activity records

A project's Overview counts the calls agents make: every MCP tool, resource and prompt call, and every /api/v1 data call of a connected machine. Counts only: per project, day and call name, how many calls, how many ended in a tool error or an internal error, and their total duration - never an argument, a result or an error message. A counter row holds the project, a UTC day, the source, who made the call (a person or a connection), the tool's name and those numbers - never a path, a symbol, an argument or anything a call returned. The names are WhyGraph's own or one of the four CodeGraph tools; any other name is never stored. Tool calls the Chat assistant makes are counted the same way (source chat, no person or connection, never arguments). A caller can only add to its own rows, and rows are kept 400 days. See Agent activity.

What the GitHub crawl stores

Besides commits, pull requests and issues, the scan keeps a few more facts from GitHub, in the project's own database:

  • Reviewer identities. For a pull request, the logins of the users and bots asked to review it and of those who reviewed it, with the review decision and the time of the first review. Team review requests are not read: an installation token cannot read teams. If GitHub answers FORBIDDEN under reviewRequests, that part is dropped and the rest of the crawl is kept.
  • Milestones, with their due dates and counts.
  • Tags, fetched into a private namespace, refs/whygraph/tags/*, with --prune. Fetching them into refs/tags/* would let a hostile tag shadow a branch or another ref WhyGraph resolves, and pruning makes a tag deleted upstream disappear here too. Tag names are untrusted data: they are never used as a path, in a shell command or as instructions in a prompt.

Repository content is not trusted

A repository - a GitHub clone above all - can contain anything. The portal treats it that way.

A scan runs as a child process inside the project's folder, in Python's safe path mode (-P, PYTHONSAFEPATH=1): the folder is never on the module search path, so a repository that commits a whygraph/ package cannot replace the portal's code.

The portal never follows a symbolic link out of a project's folder. When .whygraph/, .codegraph/, the CodeGraph index, .gitignore, whygraph.toml, a portal marker, an agent config file or a bundled agent folder (such as .claude/) is a link, the portal refuses it with an unsafe_path error: initializing, the Explorer, Chat, the MCP endpoint and scans all stop for that project, a whygraph.toml link is not imported, and removing the project leaves the linked files alone. Replace the link with a real file or folder to continue.

CodeGraph, which builds the code index, follows symbolic links out of the repository on purpose. So before every index build or refresh WhyGraph lists the files CodeGraph would read - tracked and untracked files, files in embedded repositories, and folders a codegraph.json include adds - and refuses to run CodeGraph while any of them is a link that leads out of the project's folder. A link that stays inside the folder is fine. There is no setting to skip the check and no partial index: the scan reports the links (the first five by name), the CodeGraph step fails, and the rest of the scan still runs. Replace each link with a regular file or remove it, then scan again.

An index built before this version may hold symbols read through a symbolic link that leaves the repository; the first scan after upgrading rebuilds it from scratch (once - a stamp beside the index, .codegraph/whygraph-guard, records that it was rebuilt). Until the links are gone the rebuild is refused like any other index build, and the scan after they are removed runs it.

The CodeGraph endpoint

/mcp/<slug>/code serves CodeGraph's tools from a child process, so it is held to the same rules as anything that reads a repository.

  • Only four tools. codegraph_explore, codegraph_node, codegraph_search and codegraph_impact are served, all read-only. Any other name is refused before it reaches the child.
  • The project is pinned. projectPath is not in the advertised schemas, and a value that names any other directory is refused; the portal always sets it to the project's root. file on codegraph_node and codegraph_impact is checked to stay inside the project, depth is at most 3, and every argument has a size cap. The request body is capped at 1 MiB, on this endpoint and on /mcp/<slug>.
  • Nothing runs by itself. The server starts with no file watcher, no background daemon, no telemetry, no update check and no downloads, and the bridge never builds an index: only a scan does. Every CodeGraph process ignores the host's global and system git configuration.
  • The same gate as /mcp/<slug>. The Host / Origin guard, the organization membership check and the Initialize gate apply to /mcp/<slug>/code exactly as to /mcp/<slug>; the endpoint is stateless and has no session id.
  • Who it runs as. The hosted CodeGraph runs as the portal's user inside the container (local mode only); the tool allowlist, the argument policing and the projectPath pin confine it, not a separate user id.
  • What an error means. A bridge error is isError: true and begins [WhyGraph]; anything inside a successful result is repository content, including a line that looks like a WhyGraph note.

Configuration from a repository

An imported whygraph.toml contributes only an allowlist of settings (models, tuning keys and a few [scan] keys). The WhyGraph database is always in the portal's data directory and the CodeGraph index always at <repo>/.codegraph/codegraph.db, whatever a file says. A remote or default_branch value that could be read by git as an option is dropped.

A committed codegraph.json is CodeGraph's own configuration and is honoured as written: extensions, include, includeIgnored and exclude change which files of the repository are indexed. It is repository-controlled configuration, so it cannot widen the index beyond the project's folder: the symbolic-link check above walks every folder its include and includeIgnored patterns add, and a codegraph.json that is itself a link out of the folder is refused.

Hooks

The git hook helper lives in the git directory (.git/whygraph/whygraph-scan), not in the working tree, so a commit pulled from a remote cannot replace it: git never checks files out into .git/. It reads .whygraph/portal.env with sed and validates the two values it takes (a slug and a port); it never sources the file. It ignores the file if git tracks it or it is a symbolic link, and it never writes its log or pending flag through a symbolic link. It only ever sends a request to 127.0.0.1 and never runs a scan itself.

Clones

Local mode clones nothing: a local project is a folder you shared. In production the portal clones only a repository the GitHub App covers, from WHYGRAPH_GITHUB_URL (https except on loopback), with a restricted protocol list, into repos/<org>/<project> under its data directory. It removes a failed clone it created and will not delete a directory it did not. The code that deletes a project's history works the same way: it only removes a real directory (never a symbolic link) at the expected depth under projects/.

A clone never contains a symbolic link: it is made with core.symlinks=false in its own git config, and every sync checks out the same way, so a link a repository commits arrives as a plain file holding the link's target. One repository can therefore not point into another tenant's clone or the portal's data. A clone made by an earlier version is fixed by its next sync, which rewrites any link still on disk as a plain file and drops the cached rationale cards of those files; at start the portal queues one such sync, with a scan, for every clone that does not have core.symlinks=false yet.

The update check

The portal looks for a newer release once a day. This is the only thing it fetches that has nothing to do with your projects, and what it sends is one request:

GET https://api.github.com/repos/mtrdesign/whygraph/releases?per_page=30
User-Agent: whygraph-portal
Accept: application/vnd.github+json
X-GitHub-Api-Version: 2022-11-28

plus the HTTP client's standard Accept-Encoding and Connection headers. No version, identifier, cookie, token or project name goes with it; GitHub sees the machine's IP address, as with any git fetch. whygraph update makes the same request when you run it, from a short-lived container of the current image, with User-Agent: whygraph-cli. From the answer the portal keeps only version numbers, publish times and whether a release is marked as needing manual steps. The link to the release notes is built by the portal, so nothing from the response is shown as text or followed as a link. The check never runs as part of a scan, and a failure is shown only as "Last check failed".

To turn it off:

  • Local portal: the toggle in the global Settings. The portal started by whygraph up gets none of your shell's environment, so a variable set there has no effect.
  • Production, or whygraph portal run directly: WHYGRAPH_UPDATE_CHECK=0 or DO_NOT_TRACK=1 in the portal's own environment. See Configuration.

The check is separate from CodeGraph, which makes no telemetry, no update check and no downloads (see The CodeGraph endpoint). A local portal makes its first check the first time it starts after an update, before you can reach the toggle; production egress rules will see the call to api.github.com.

Project notes

A project note is text a member (or an agent, for a member to confirm) wrote and the assistant and MCP agents later read, which makes it a channel for prompt injection: a hostile issue, pull request or file can talk an agent into proposing a note, and a confirmed note then sits in front of every later session. The controls:

  • Agents propose; people confirm. No surface a model reads - find_notes, the rationale card, the note resource - ever returns a proposed note, and an agent has no tool to confirm one. Confirmation is a member action and is audited (the note id, the actor, whether the confirmer was also the proposer; never the text).
  • A wide note needs a second confirmer. A note anchored to the whole project, or to a top-level folder or something broader, reaches nearly every session. Its proposer cannot confirm it or mark it still true, and only a project admin can change its text while confirming it. 403 note_needs_second_confirmer.
  • MCP proposals need project.read. The tool is a write, but it only creates a proposal that waits for review, so any member who can read the project can propose through their agent. It is capped: 20 per member and 50 per project per day, and 200 waiting at once. Reject all from this origin clears one member's runaway agent without confirming anything.
  • Notes are data, never instructions. The assistant's system prompt and the MCP instructions say so; a note is rendered on one line, its text quoted and whitespace collapsed, wherever it goes into plain text; text with control characters is refused; notes are never fed to rationale generation; and Chat's starting overview carries only a count of project-wide notes, never their text.
  • Anchors are paths of an untrusted repository. They go through the same symbolic-link and containment checks as every other repository path; the denied paths of Chat's file tool (.git, .whygraph, .codegraph, whygraph.toml, .env*) cannot be anchors.
  • Chat cannot load images from a model. A Markdown image in a reply is shown as its alt text and a link, never fetched, because a loaded image URL could carry what the model had read out of the portal.
  • A check on a constraint is a text search, never a command. The text and the glob are checked against a short character set (no quote, backtick, backslash or ..) and reach git grep as arguments, so no shell reads them. A wrong check, from a bad or injected note that a person confirmed, can stop a run or fail a step's Verify, but it cannot change a file. It also needs a confirmed note: a proposal's check does nothing. See A check on a constraint.
  • No text in logs. Audit and log fields carry ids and enums, never a note's text, an origin or a ref.
  • Statistics cannot read notes. The Chat statistics tool refuses the notes table.

Residual risk in local mode. The portal has no login, so any local process acts as the single local user. An agent that can run shell commands on your machine can call the portal's notes routes and confirm its own proposal, exactly as it could edit CLAUDE.md or your code. WhyGraph does not ask an agent to do that and no tool result or bundled file names those routes, but the confirmation step is a guard against injected text, not against a local program that already acts as you. On a production portal every member signs in, and a project note is visible to every member who can open the project (proposals included).

Claude Code hook output

The helper that Claude Code's notes hooks run prints only one of two shapes: {} or a fixed two-key envelope for its own event, with additionalContext as the only payload. The portal writes every " inside that text as \u0022, and the helper refuses any answer that holds a literal " there, so nothing can follow the text to add a key such as continue or decision. A note reaches the model labelled as member-written data, not instructions.

Project transfer

A bundle from Export and import is untrusted input, including one you made.

  • Admin only. Export and import need project.configure, and both are refused on a linked project. A production org's exports and imports are written to the security event log, never with any text.
  • Read as an archive, never extracted. Entry names, flags, sizes, counts, the central directory and every member's hash are checked before a line is parsed; a hostile or oversized archive is refused with nothing written. Row, line and total-size limits apply while reading.
  • Validated, not trusted. Every record is parsed against a strict model; control characters are replaced, over-long fields skipped. Anchor paths go through the same deny-list and containment checks as a note written by hand.
  • Confirmed notes reach agents, so the preview shows every wide one verbatim before you apply. Imported rationale cards are marked and removable in one step; descriptions are only validated.
  • Who wrote it is display-only. Names in a bundle never map to a member of the target.
  • The bundle may hold secrets in your chats (tool output with file contents). Delete it after use. No key, token or password is ever exported.

Project purpose

Generating a project purpose sends repository text to the model behind the project's [analyze] setting - the provider, or the custom base_url you configured, such as a gateway or Ollama on your machine. Check that destination before you generate. One call sends, at most 24 KB in all:

  • the README (up to 12 KB) and a few documents (docs/index.md, docs/README.md, CONTRIBUTING.md, 4 KB each);
  • the package manifests reduced: the package name and description, script names and dependency names only - never versions, URLs or the whole file;
  • the top-level file and folder names, the configured area names, and history counts (commit count, date range, the share of changes per top-level folder).

Never read or sent: the working tree (everything comes from the git object store at HEAD, so untracked files, symbolic links and submodules are skipped), .env and credential files, commit subjects, pull request titles, and author names or emails. Token patterns are redacted from every text before it is sent.

The repository is untrusted input here too: its text goes inside a random, per-call fence that the prompt calls data, never instructions. The model's answer is parsed and rebuilt from four labelled values with fixed length caps, and refused (no retry, so no second spend) if it contains a link, a command-like character or a missing label; only the rebuilt text is stored. The result is a proposal that no model reads until it is confirmed.

Accepted residual risk. The admin who generates a purpose may confirm it without anyone else reading it, so a hostile README could steer the draft and an admin who confirms without reading would put it in front of Chat sessions. The controls are the ones above (rebuilt and bounded text, shown beside its sources, one explicit click, admin-only edits) and the audit event purpose_generated (counts only, never the text). The call is metered like any other, and cannot be made on a linked project.

What the portal writes to your repository

Only when you initialize a project, only what the preview listed, and only after you confirm: .gitignore entries, git hooks, agent MCP entries and assets, and the two marker files in .whygraph/. Agent files you did not name are not touched, unparseable files are refused rather than overwritten, tracked files need your confirmation, and a backup is kept under .whygraph/backups/.

Adding a project without initializing it writes nothing.

The hosted CodeGraph writes inside the portal's data directory, never the repository: <data>/logs/codegraph.log (mode 0600) holds the server's stderr - CodeGraph's notices and, on an error, repository paths, never file contents.