Running Supbuddy 3.8.0 or earlier? It can no longer update itself. Run npx supbuddy@latest once, or download the latest version.

Supbuddy docs

Run multiple Supabase projects at once on one Mac, each with its own custom local domain.

Getting started

There are two ways to run Supbuddy. Use the macOS desktop app (steps below), or the command-line interface, which runs on macOS and Linux. For the CLI, install it with npx supbuddy@latest and jump to Command-line interface. The app and the CLI share the same state, so you can use either or both.

1. Install

Download the latest .dmg from the download page. Drag Supbuddy.app into /Applications and launch it. Supbuddy is signed and notarized; macOS will not show a Gatekeeper warning. Requires an Apple Silicon Mac (M1/M2/M3/M4, arm64). The desktop app is macOS-only in v2, but the headless CLI runs on Linux too. See Command-line interface.

Updates. Supbuddy updates itself from supbuddy.app: Check for Updates… in the tray, and a quiet daily check. An update is installed only when all three of these hold:

  • it is signed with the key the app was built with;
  • the archive's own Info.plist names Supbuddy at exactly the version offered;
  • that version is newer than the one you run.

From 3.8.2, the update is installed with the same care. The dialog shows Installing… while this runs; Gatekeeper's check can take a minute or two.

  • It is unpacked, written to the disk, and copied beside the current app. That copy is checked: it must pass codesign --verify, be accepted by Gatekeeper, and be signed by Supbuddy's Apple team.
  • Where the disk allows (APFS does), that copy is swapped in in one step. Elsewhere, the current app is moved aside first and put back if the new one cannot be put in place.
  • What is moved aside must be the version you were running. If something else updated the app meanwhile, that update is kept and this one stops. In the rare case that the swap cannot be undone, this update stays installed and the message says where the other version is.
  • The previous app is deleted only once the new one is confirmed on the disk. When that cannot be confirmed, the previous app is kept and the dialog says where.
  • If anything fails before the swap, the app you have is left as it was. In the rare case that the previous app cannot be put back, the error says where it is, and checking for updates again puts the update in place.
  • If the app is in a system folder you cannot write to, such as Applications on an account that is not an administrator, macOS asks for an administrator's password once. (A folder counts as a system folder when it and every folder above it belong to root, their permissions do not let you write to them, and none carries an ACL entry that allows anything. Deny-only ACLs are fine.) Root then copies the update into a folder only it can write, checks it there (Gatekeeper's check runs only here), flushes it to the disk, and moves it in. If it cannot confirm the update is on the disk, it keeps the previous app and the dialog says where.
  • If the app is in a folder of your own that is not writable, no password is asked for: Supbuddy says so. Make the folder writable, or move the app to Applications.
  • If the folder is writable but the app will not move — it is locked (Get Info → Locked) or belongs to another account — the update stops and says so, without asking for a password.
  • An app opened from a disk image, or one macOS runs from a read-only copy (often one opened straight from Downloads), cannot be updated in place. Supbuddy says so and asks for no password. Quit it, move it to Applications, open it from there, then check again.
  • Restart Now opens the new version. Anything the update could not clean up is listed so you can deal with it yourself. Temporary copies left by an update that was interrupted are removed by the next one, except those only an administrator can remove, which are listed. A previous app that is the only copy of the app is never removed: it is listed, with where to move it back.

The app carries no password or token for this. Supbuddy 3.8.0 and earlier cannot update themselves any more: they can no longer reach the update server. Update them once, either way:

  • Run npx supbuddy@latest in a terminal. This is the command the old app's own Check for Updates suggests. It offers to update the app:
    • The new app must be Supbuddy at the offered, newer version, signed by Supbuddy's Apple team and accepted by Gatekeeper, all checked on a staged copy.
    • A swap that fails puts the previous app back.
    • It never quits the app. If Supbuddy is open, quit and reopen it to use the new version.
    • Without a terminal prompt, npx supbuddy@latest update --yes --no-restart does the same.
  • Or install the latest version from the download page.

From then on, updates work on their own.

2. Trust the local Certificate Authority

Caddy mints its local CA the first time the proxy starts — no mapping required, so you can trust it before you add anything. With the proxy running, open the app, click the gear (top right) and, on the General tab, find the CA Certificate row and click Install. There is no first-launch prompt for this: until the CA is trusted the row shows an amber dot and not trusted, and supbuddy doctor reports ca-not-trusted. Supbuddy adds the CA (Caddy's internal PKI at ~/Library/Application Support/Supbuddy/caddy-data/caddy/pki/authorities/local/root.crt) to your System keychain via sudo security add-trusted-cert; macOS asks for your password once. (On macOS 15+ that system-wide step is no longer permitted to a background helper, so Install falls back to per-user trust — see below.) Caddy does not self-install trust (the generated Caddyfile sets skip_install_trust), so this button is what makes the padlock green — fully quit and reopen your browser afterward to pick it up. Every Supbuddy domain then gets HTTPS with no per-domain prompts or warnings. (On Windows the install is manual: Supbuddy shows the PowerShell Import-Certificate … -CertStoreLocation Cert:\LocalMachine\Root command to run as Administrator.)

Install waits for macOS's dialogs, and the row shows Installing… with a spinner until the install ends, however it ends — the button can't be clicked again meanwhile. Only one install runs at a time, whoever asked: a request made while one runs — from the row, the System Doctor or an agent — joins it rather than opening a second set of dialogs. An install the Doctor or an agent starts shows Installing… on the row too, and how it ended is shown under it. Each dialog's answer is waited for 3 minutes, the administrator prompt's through the app too (an older daemon stops waiting for it after 2 when the app shows it). If Supbuddy stops waiting for an administrator prompt that is still open, it says so rather than reporting a failure: answer or close that prompt before you click Install again. (Approving it late trusts the CA on macOS 14 and earlier; on macOS 15+ it can't, because the per-user step that follows is no longer waiting.) The row keeps re-reading the trust for a while afterwards, and re-reads it whenever Settings opens. If the install can't finish, the reason — and, when the installer gives them, the steps to finish by hand — stay pinned under the row with the time it ended, until the CA reads trusted. While the row isn't trusted, Show beside Install reveals root.crt in Finder.

For AI agents: if HTTPS for a Supbuddy domain is untrusted — the browser shows NET::ERR_CERT_AUTHORITY_INVALID, supbuddy doctor reports ca-not-trusted, or MCP get_ca_status returns installed: false without trustUnknown — call MCP install_ca, or ask the user to click Install in Settings → General → CA Certificate. With certPath: null there is no readable CA root yet: start the proxy first; if it stays null while the proxy runs, run doctor, which names the root's path and why it can't be read. With a certPath but expiresAt: null the root can't be read, and install_ca would refuse it: run supbuddy doctor (or MCP doctor) — its ca-not-trusted finding says how to recover. Don't run security add-trusted-cert yourself; when the result has needsManual: true, show its message (the steps) to the user verbatim. On macOS, a get_ca_status with rootChanged and remediation means the CA root is not the one this Mac trusted before: trusting the new one needs someone at the Mac's screen, so show the user remediation.steps rather than wait on an install_ca nobody can approve — see Remote setup: what needs a screen session. get_trust_status is a different thing — bundled-runtime trust for tools with their own JavaScript runtime (below) — and says nothing about the system CA.

On macOS 15 (Sequoia) and later, Install trusts the CA for your user account. Apple now routes system-wide trust changes through an authorization dialog that macOS refuses to show to a background helper — being root is no longer enough, and the attempt comes back as SecTrustSettingsSetTrustSettings: The authorization was denied since no user interaction was possible. Supbuddy still tries the system-wide install first (it works on Sonoma and earlier, and covers every user on the machine); when macOS refuses it, Supbuddy adds the root to your login keychain instead and macOS shows "You are making changes to your Certificate Trust Settings" — confirm with your login password. Browsers honour user-domain trust exactly the same way. Removing the CA is supbuddy ca uninstall (or MCP uninstall_ca) — the app has no Uninstall button — and it removes the root from both keychains. If you dismiss that dialog, Supbuddy pins the reason and the exact command under the CA Certificate row so you can run it yourself — without sudo, which would land back in the domain macOS just refused:

security add-trusted-cert -r trustRoot -k ~/Library/Keychains/login.keychain-db \
  ~/Library/Application\ Support/Supbuddy/caddy-data/caddy/pki/authorities/local/root.crt

Caddy names its root by year, so each yearly rotation (or a data wipe) leaves a same-name root behind with a different key. On every Install, Supbuddy first removes any stale Caddy Local Authority roots whose fingerprint doesn't match the current one, then adds the current root — leftover mismatched roots otherwise make Firefox-family browsers fail with SEC_ERROR_BAD_SIGNATURE. This cleanup runs against whichever keychain the install targets, and trust detection reads both the System and login keychains, so a root trusted per-user still reports as installed.

Firefox, Zen, and Brave keep their own certificate store that Supbuddy can't reach (they don't consult the System keychain). After a CA change, either delete any stale Caddy Local Authority entries from the browser's own certificate manager and re-import the new root, or — on Firefox/Zen — set security.enterprise_roots.enabled to true in about:config so the browser reads the System keychain.

If Supbuddy detects an AI tool that ships its own JavaScript runtime (Claude Code, Cursor, Windsurf, Continue, Codex CLI, OpenCode, etc.) it will also offer to enable Bundled-runtime trust, in a one-time prompt the first time the app finds one of them. Those tools don't read the system Keychain (they carry their own Mozilla CA bundle), so without this setup the first OAuth/MCP connection to a *.test URL fails with unable to get local issuer certificate. Enable it once and Supbuddy keeps it in sync (including across yearly Caddy CA rotation). See the Bundled-runtime trust section under Settings → General for details.

If you skip the prompt, enable it any time under Settings → General → Bundled-runtime trust.

3. Add your first project

Click Add project in the Configure tab and pick a project root folder (the one with package.json and/or supabase/config.toml). Supbuddy scans it and creates auto-mapped subdomains based on what it finds:

  • Supabase Kong → api.<project>.test
  • Supabase Studio → studio.<project>.test
  • Supabase Inbucket / Mailpit → mail.<project>.test
  • Each detected app (Next.js, Vite, etc.) → <app-name>.<project>.test

The default TLD is .test. You can change it project-wide in Settings → General → Default TLD. A real public suffix such as .com or .dev asks you to confirm first, as the default TLD and as a project's or a mapping's own (see Custom domains & TLDs).

.local is fine again, from 3.5.18. Earlier versions made every managed domain resolve slowly — a name resolved in milliseconds once and then stalled five seconds per concurrent lookup, so curl, a single fetch and dig all looked healthy while any page issuing several requests at once failed with what looked like a connect timeout on the proxy. The advice used to be to move off .local, on the grounds that macOS reserves it for multicast DNS (RFC 6762). That was only half right, and the half that mattered was ours: Supbuddy's DNS server answered only A for managed domains and forwarded the IPv6 (AAAA) lookup to the upstream resolver, which never answers for a local name — so no reply was sent at all and the client waited out its own timeout. A name on a non-reserved suffix stalled identically (5003 ms against .local's 5002 ms), which is what proved the suffix was not the cause. Supbuddy now answers AAAA itself with ::1; because that is a positive answer it also satisfies macOS's multicast rule, so .local resolves in single-digit milliseconds like any other suffix. (A client that prefers IPv6 is refused on [::1]:443 and falls back to IPv4 in about 3 ms — there is deliberately no IPv6 redirect, because one was tried and it silently broke the backend HTTPS port.) There is no need to rename your domains. doctor still ships dns-local-tld-mdns-stall as a canary — if it fires on 3.5.18 or newer, check supbuddy version first, since an updated app can still be attached to an older daemon. One thing the suffix can still cause is the opposite symptom — the name not resolving at all on Sonoma and later, because mDNS owns the namespace by a path /etc/resolver does not govern. That is rarer, it is not slowness, and the only fix is a different TLD; see the PROXY ERROR banner.

4. Start the proxy

Toggle the project on. Supbuddy starts Caddy on port 8443 (HTTPS) and starts its built-in DNS server on the configured DNS port (5353 by default), or the next free port if that one is taken. If you want real ports 80/443 instead of 8080/8443, enable port forwarding in Settings → Network. Supbuddy inserts a pfctl redirect rule into /etc/pf.conf (asks for sudo once) and reports whether the redirect is actually being enforced via a live 443 probe — not merely that the rule is on disk. If port forwarding is on but 443 won't connect, see Port forwarding is on but 443 won't connect.

Enforcement has a third state: unknown. The 443 probe only means something when something is listening behind the redirect, so if the HTTPS port has no listener — most often when no mapping is enabled yet, which generates a Caddyfile with no site blocks — Supbuddy reports enforcement as unknown rather than off. In that state it shows no "not enforcing" badge, no red banner, and never asks for your password: a redirect it cannot observe is not a redirect it can call broken.

When a start asks for your password, and when it doesn't. A start asks only for work it actually has to do:

  • DNS. It writes only the /etc/resolver files that are missing or say something other than what Supbuddy would write, and reloads macOS's resolver only when it wrote or removed a file, or when a managed domain does not answer through /etc/resolver.
  • Port forwarding. pf rules survive a quit and are lost on reboot, so a start leaves pf alone when it was applied since the last reboot and nothing about it has changed — the ports, LAN sharing, and the anchor and /etc/pf.conf on disk. When a start leaves pf alone, Supbuddy checks 443 as soon as something is being served behind it, and re-applies pf (one prompt) if the redirect turns out to be dead.

So stopping and starting again with nothing changed asks for no password — as long as macOS is loading Supbuddy's /etc/resolver files. On a Mac that doesn't (see the /etc/hosts fallback below), every start still reloads the resolver and asks. With port forwarding on, the first start after a reboot, or after a port change, asks once to re-apply pf (a LAN-sharing change updates pf when you make it — see LAN sharing). A resolver file that is missing or out of date is written at the next start, which asks for it — though registering or enabling a project usually writes its file there and then. Retry in the app always re-runs every privileged step, whatever looks applied; supbuddy proxy restart re-applies only what its audit flags.

If the one-time sudo prompt is cancelled or fails, Supbuddy no longer aborts the start: Caddy still comes up and HTTPS keeps working on the high port (8443), and the proxy shows a degraded error state with a Retry so you can re-run the privileged setup. The CA is still generated in this state. You have three minutes to answer an admin prompt, through the app or not (older builds gave up after 30 seconds and then discarded the result of a password typed later, reporting work that had actually succeeded as failed; through the app, an older daemon gives up after 2 minutes). Each answer is matched to the prompt it answers, so a prompt answered late can never be read as the answer to a newer one. The app itself waits 15 seconds for a Start, Stop or Retry to answer. Past that it says there is no answer yet and that the action may still be running, rather than that it failed; the proxy's state updates when it finishes.

Core concepts

Four things to understand:

  • Project: a folder you registered. Holds detected apps (Next.js, Vite, etc.), detected services (Supabase stack, Docker Compose services), and a list of mappings. What the app asks the daemon to read, write or run in a folder is done only in a registered project's folder. This covers the env files, the Supabase details and config, supabase init, Compose, the Next.js and Vite config fixes, and the connection's env files. A file must be inside that folder by its real path when the request arrives, resolved as the system resolves it, so a symlink in the project that points elsewhere counts as outside it, and a path with a . or .. part is refused outright. The readiness card's env fix is held to its own project the same way. The env view's read and the config editor's secret target follow the rule MCP's connection tools use: a nested project's file linked to its enclosing project's is taken, and an enclosing project's request for a nested project's file is refused. The env files listed for a project (the app's env list and MCP get_env_files) are its own .env, .env.local, .env.development, .env.production, .env.test and .env.example, and each apps/<name>/.env and apps/<name>/.env.local. One in the folder of a project registered inside it, or linked into one, is that project's: the app's list leaves it out, and get_env_files lists it with no keys and the reason (it is in the folder of a project registered inside this one, so its keys are not listed here; ask through that project). Anything else is refused with the reason. MCP's file tools hold a path to some registered project's folder the same way (scope_denied): an absolute path, compared through the file system as it is sent, with no . or .. part, and not through a symlink that points nowhere. read_env_file, write_env_file, copy_env_var, preview_next_origins, apply_next_origins, preview_vite_hosts and apply_vite_hosts also take an optional project_id: given one, each path is held to that project as the connection tools hold theirs (its own folder, or an enclosing project's; not a nested project's or another project's), and a plan for a write is refused at once when it isn't (the CLI's env copy, env write and project env-read take --project). write_connection adds .env.supbuddy to the .gitignore of the git repository that holds the file, so an app with its own .git inside the project gets it in its own. The entry is a bare .env.supbuddy, which git matches at any depth, so the file stays ignored when its folder is renamed or moved. A .env.supbuddy linked to a file of another name gets that file's own path from that repository's root instead, anchored (/shared/config.json), so it ignores that file and no other config.json. A line already there counts only when it ignores the file where it is (/.env.supbuddy ignores the top folder's alone), read as git reads it. A .env.supbuddy that is a link into another project's folder, or from an enclosing project into a nested one's, is refused before any .gitignore is touched. With the entry in place, before the keys are written, Supbuddy asks git itself about the file, in that repository (git check-ignore --no-index and git ls-files --error-unmatch, read-only, with no shell, no file system monitor (a repository's core.fsmonitor command is not run) and one 5-second bound for all its questions, ignoring any GIT_DIR-style or GIT_*_PATHSPECS variables it inherited), once git has said the folder is in its work tree (git rev-parse --is-inside-work-tree printing true). If a later .gitignore line takes it back (one starting with !, in a deeper folder say), or the repository already tracks it, the file is still written and the result says so, naming the git command that shows or fixes it (git check-ignore -v --no-index -- <file>, git rm --cached -- <file>): in write_connection's ignoreWarnings and warnings, and in the Connect panel's write result. The config editor's secret extraction asks git the same about the env file it moves secrets into (see Config editor: secret extraction). Without git, with a git that does not answer (macOS's /usr/bin/git with no Command Line Tools), outside a repository, or past the bound, nothing more is said. The files Supbuddy writes there (.env.supbuddy and its port follow, the Connect panel's Apply, MCP's write_env_file and copy_env_var, the config editor's secrets, .gitignore, and the Next.js and Vite config fixes) are opened as the file that check found, and Apply's, the follow's and MCP's env writes land whole, keeping the file's mode (a read-only file is refused; an env file they create, .env.supbuddy included, is its owner's only, 0600) (see Backups and safe writes: Apply's backup goes to Supbuddy's own folder, not the project). A symlink inside the project to a file inside it is written through, and so is a nested project's file linked to its enclosing project's (apps/web/.env.local to the root's .env.local, the monorepo layout). Every other link across a project's edge is refused, even when it is swapped in after the check: one that leads out of every project, one from a project into a sibling project's folder, and one from an enclosing project into a nested project's. A file with another name (a hard link) is refused too, read or written, checked on the open file up to the moment it is replaced: its real path is the project's, but it could be another project's file, and Supbuddy can't find its other names to tell. .env.supbuddy's .gitignore entry is added first, so a .gitignore that can't be updated stops the write. Apply, the config fixes and MCP's env writes write only over the content they read, and an edit made between their read and their write is kept, with the fix answering that the file changed. The env files read for you are read the same way after their check: the Connect panel's diff, Apply and its list of targets, read_env_file and get_env_files, the app's env view, the .env.local a Supabase start reads, the .env a bundle export carries (and the cloud push's stack export), the .env Compose's project name may come from, and the env files the readiness check reads. For those three, a refused .env is handled as follows. A bundle export stops with the reason. Compose's project name is unknown, since Compose reads that file for COMPOSE_PROJECT_NAME, so Supbuddy leaves the stack alone: a Compose start or stop is refused with the reason, a cloud push carries none of its Compose services, a scan lists no Compose services, and the doctor removes no volume of it. The project's card says why (Compose stack left alone, a warning with the reason, since there is no Compose tab then), and so do MCP register_project (compose_note), scan_project (composeNote) and get_project (composeNote); the next scan that lists the stack clears it. To keep such a .env (a git worktree's linked to the main checkout's, a 1Password FIFO), give the Compose file a top-level name:: Supbuddy takes the project's name from it, passes it to Compose as --project-name, and does not read the .env for it. A nested project's .env linked to its enclosing project's is read, by the doctor's check too. Readiness fails its scan with the reason, as for a file it can't read; an env file in a registered project nested in the one it scans is that project's, so the enclosing project's scan takes it as none, rather than failing. One that leads out of the project by then, a FIFO, or a hard link is refused with the reason (scope_denied over MCP; get_env_files lists it with the reason; a start goes on without it and says so, in a note on its progress stream and in its completed message, which the app, if open when the start finishes, shows as a warning that stays until you close it; a legacy VM project's move to Host says so on its Supabase step and its final message), never read. A Compose file that is not a regular file, such as a FIFO, is never read or waited on by Supbuddy, and a folder where it finds one is not handed to Compose, which could wait on a FIFO too: the project's Compose name is unknown, so a Compose start or stop is refused with the reason, the scan lists no Compose services and the card says why, and the checks that must know whose a stack is, the doctor's and a delete's, hold its stacks back. The same holds for the scan's other reads (a package.json, pnpm-workspace.yaml, a framework config such as next.config.js or vite.config.ts) and a bundle import's (its manifest.json, compose.yml, .env and archives): one that is not a regular file is never opened to wait on, and is read as one Supbuddy can't read, so the scan goes on without it and the import refuses the bundle, saying it is not a regular file. The file opened must also be the one that check saw, by its device, inode and birth time: one swapped in between that check and the open, a link retargeted included, is refused the same way, saying it changed while it was being opened, and a link that stays put is followed, as before (SUP-414). On a filesystem that keeps no birth time, a replacement that is given the removed file's inode at once can't be told apart, so this is a best effort, not a guarantee. A .gitignore Supbuddy can't read is refused, never replaced. A project's own supabase/config.toml (and config.hosted.toml, and the config editor's backups) is read and written only inside the project's folder too: the config editor and read_supabase_config, Save, a backup restore, the analytics toggle, accepting a config fix, restoring the hosted snapshot, the Thin port block (conversion, rename, rollback, switch back to Host) and supabase init all refuse a config that resolves outside the folder, or into the folder of a project registered inside it, before they stop, copy or write anything, with the reason and the way out: copy the config into the project's folder, or register the folder it is in as the project. A config linked from inside the folder (a monorepo's apps/db/supabase/config.toml to the root's) still works. The readers that only take its ports or its stack's id from it read it the same way: a start's and a restart's port check and their port-conflict advice, a Thin start's check of its block and the block's commit and rollbacks, the checks around a stop, a repoint's reads (Edit Project, Select Folder, set_supabase_config_path), a switch to the mode a project is already in, the cleanup on delete, the project scan, Docker event matching, isolation drift, a legacy VM project's retried move to Thin, the analytics reading, a running stack's reachability, the config writers' check that a running Thin stack keeps a name, .env.supbuddy's port follow, a delete's shared-teardown checks, a delete resumed at boot, the doctor's orphan-volume check and the reset's Thin restore. A config linked out of the folder, or a FIFO in its place, is one they can't read: never followed, never waited on. Each does what it did for a config it can't read, and says why where it refuses or holds something back: a start's and a restart's port check use the CLI's stock ports, and a conflict on one says those are the stock ports, not the project's, and why the config wasn't read; a container restart is refused, saying why; a delete's teardown holds back every stack, and the app's delete answer names the project whose config can't be read, and why (the trash expiry and a delete resumed at boot log it); elsewhere there is no stack id. A config linked into the folder of a project registered inside this one is refused naming that project's folder. A Thin project's Stop through such a config is refused, naming the stop by id (supabase stop --project-id <managed id>). A folder you choose with the folder picker (Add Project's folder and its preview, Select Folder, and the bundle export and import folders) is taken only as picked in the app while it runs, and only for what it was picked for: the picker's title says which (the project's folder, where to save a bundle, the bundle to import, the folder to import into), and a folder picked as an export's destination can't then become a project's folder. Anything else is refused with <channel>: <field> is not a folder you picked for this in Supbuddy. Choose it with the folder picker. A rescan of a project's own folder needs no pick; if the project's folder moved since the app last read it (the CLI or MCP moved it), the rescan says so: projects:scan: this project's folder changed since the app last read it. Reload the projects and try again. Each scan, folder preview, Supabase details read and env-file read carries its own request id, which the daemon's answer repeats, so an answer reaches only the request it is for: two rescans at once can't swap results, and a details read that ran out of time can't fill the next project's dialog with its answer. The app's other per-project reads carry one too: the config editor's (reading, parsing and writing out the TOML, checking it, its backups and its secrets), the Connect panel's (the preview, the env files, each file's diff, the TOML audit, the connection test), each card's cloud status, sync status, push-dialog repository and env preview, its analytics flag, script logs, AI tools settings and readiness scan, and the Next.js and Vite fix dialogs' previews and a bundle import's check. So two config editors open at once can't swap the text Save writes, one cloud card can't show another project's stack, a preview can't show another config file's change, and an import can't ask about another bundle's domain.
  • Mapping: a domain → port pair (e.g. api.acme.test → 54321). Auto-generated mappings are tied to a detected service or app; you can also create manual ones. A mapping's domain, like a project's, is a domain name: dot-separated parts of letters, digits and inner hyphens, at least two (api.acme.test), at most 63 characters between dots and 253 in all. A mapping's may also start with one wildcard part (*.acme.test, served with a wildcard certificate for every name one part under acme.test, not acme.test itself) and use underscores (my_app.acme.test). The mapping dialog types both, and dots in a project mapping's subdomain: * as the subdomain makes *.<project domain>, and a * anywhere but as the whole first part is refused with where it may go. A project's domain may not. A wildcard mapping resolves through Supbuddy's DNS, in a project or manual: a manual *.foo.test answers each name one part under foo.test (a.foo.test), as Caddy serves it. It must sit under a name of its own, like *.myapp.test: one straight on a TLD (*.test, which a manual mapping named only * makes) gets its site block and certificate but no resolver file, since that file would capture the whole TLD, so it does not resolve. Wildcard and underscore names are not written into the /etc/hosts fallback, which has no wildcards and takes only plain DNS names, so on a Mac using that fallback they don't resolve. A name whose resolver file would hold an underscore, such as a manual my_app.test, gets no resolver file, so it resolves only where something else answers it (a .localhost name in a browser); under a name without one (my_app.acme.test under acme.test) it resolves. A URL Supbuddy writes is never a wildcard: in a generated env file (an app's, the Supabase API's or Studio's) another mapping is used, or for Supabase the local URL it reports, or none; the Supabase config check never proposes one as auth.site_url or studio.api_url. Nor does the app: a row (Apps, Compose, Supabase) shows a wildcard with no Copy or Open, the tray's app and Supabase entries open the plain mapping on the port (or localhost), an app shows its plain mapping when it has one, .supbuddy/mappings.md lists a wildcard with no URL, and the runtime-trust test never picks one as its target. A request under a wildcard (a.acme.test) is logged with its mapping's port as the target, an exact mapping winning over a wildcard as in Caddy; with LAN sharing on, mDNS answers each name one part under a wildcard's .local alias (a.acme.local for *.acme.test), and a mapping of a disabled project is neither answered nor attributed. The mapping and project dialogs check it before they save, and Supbuddy refuses any other domain from the app and changes nothing. MCP's create_mapping and update_mapping apply the same rule, and update_project the project's, length limits included, so the CLI's map add and project set --domain do too. A name is judged where Supbuddy puts it when it next starts, too: there a mapping of a project moves onto the project's TLD, and a project's domain onto its own TLD or the default. So a mapping created or renamed (in the app, create_mapping, update_mapping), a project created in the app, a restore from the trash (restore_mapping, restore_project, whose project and children are judged together) and a bundle import that would end over the DNS limits there are refused, naming the name and what it would become (over MCP, details.name_too_long: { name, would_become } for a mapping or a restore, which is restore_conflict); a name already over a limit that it leaves no longer is not. Two mappings on one name there are refused the same way, compared without regard to case: a mapping created or renamed onto a name another mapping has once the next start moves it (foo.acme.ab in a .test project, beside foo.acme.test), a project created, registered or restored with a TLD of its own that would pull a manual mapping onto another's name, a project edit, and restore_mapping. The refusal names both mappings and the name they would share (details.mapping_collision over MCP). A restore_project child the next start would put on a live mapping's name stays in the trash, as a child on a name already mapped does. Two mappings that already shared a name there are not refused for it. A refused restore says what fixes it: a shorter TLD; for one of a restored project's mappings, restore_project with restore_children: false too (the app's Trash panel, which restores a project with its mappings, names supbuddy project restore <id> --no-children instead); for a manual mapping the project's own TLD would pull in, renaming that mapping (as a project created in the app does). When a bundle's domain would be too long, MCP import_bundle's plan says the import would be refused before it asks about a real public suffix, beside any other reason it found to refuse the bundle (no Docker Compose, a volume that exists already). A mapping or project save that Supbuddy refuses (a domain that is already mapped, for one) says why in a notification, and the dialog keeps what you typed. A domain is already mapped without regard to case (FOO.test is foo.test), and a mapping's rename onto another mapping's name is refused as its creation is: in the app's Edit mapping, and by MCP update_mapping (invalid_args, details.mapping_collision, naming the mapping in the way). A mapping that already shared its name with another can still be edited. A mapping saved before this rule keeps working, and can be turned on, off or deleted; editing it asks for a valid domain.
  • Isolation mode: per-project. One of:
    • thin (lightweight, the default for newly registered projects): still your host Docker (no nested containers, no DinD), but Supbuddy gives each project its own port block and a unique Compose project_id, written into that project's supabase/config.toml. That's what lets several Supabase projects run at once on the shared daemon, each reached by name (api.<project>.test, studio.<project>.test). Apps bind a per-project loopback IP (127.0.0.2, 127.0.0.3, …) so every project's dev servers keep their canonical ports — each project gets its own :3000. Start dev servers with supbuddy run -- <dev command> so they bind that IP. Supbuddy owns those config.toml keys while the project is thin and restores them the moment you switch back to host.
    • host: everything shares 127.0.0.1 and the stock ports. Dev-server ports collide across projects, and only one host-mode Supabase project can run at a time (the standard supabase start constraint). Use host only when the project's Supabase stack is already running on the host independently of Supbuddy (you run supabase start yourself and don't want Supbuddy re-porting config.toml). MCP registration (register_project) detects that case and keeps such projects on host automatically; in the app's Add-project dialog, pick Host in the Environment section yourself.
  • Active vs inactive: any project can be "active" (proxied + reachable) or inactive. Inactive projects keep their state, so flipping them on is a few seconds. Run as many active projects as you want.

Project cards (Configure tab)

Each registered project appears as a card in the Configure tab. Cards have a single-row header that's always visible and a tab-based body that expands on click.

Reading left to right:

  • Expand chevron + project name: click to expand/collapse the card.
  • Status indicator: a single colored dot next to the project name aggregating the realtime state of every subsystem (Supabase services, Compose, scripts, AI sync, port conflicts, next.config warnings). Red = error, amber = warning, green = at least one service running, muted gray = idle, animated cyan spinner = transitioning. Hover for a tooltip that lists each subsystem's state.
  • Tech badges: e.g. TurboRepo, Supabase (shown when detected).

Supabase connection warning. When a project's app .env is missing the Supabase connection vars, or they've gone stale relative to the live target (e.g. after switching isolation, which republishes ports), the card shows a supabase env: not connected / supabase env: out of date pill. Click it to open Connect and push fresh values, or choose Ignore for this project. The pill checks the file Connect writes to by default, by the app it is for: a project with one app of its own is checked in that app's folder, and one that records no app in its own folder; one with several apps is not checked. An app recorded in another project's folder, outside every project, or in a project registered inside this one is skipped, and when every recorded app is, nothing is checked. When Apply can't update the file where it is (it isn't a regular file, it is a hard link, a link that leads out of the project or nowhere, Supbuddy may not read it, or a merge would change how another key reads), the pill says Supabase env: Apply can't update it with Apply's reason, and readiness lists it as a warning with no fix. Fix the file, or choose Ignore for this project (a 1Password .env FIFO is refused on purpose). A file Supbuddy may not write (read-only) still shows as not connected or out of date, and Apply says why.

  • Env mode chip: read-only Host or Thin label (matching the project's isolation mode). To switch modes, use the project's ⋯ actions menu (every project has it) or, for a project with Supabase, the Environment section at the top of its Supabase tab.
  • Issues counter: red for errors, amber for warnings. Click to open the issues popover (see below). Hidden when there are no issues.
  • Warnings chip: all project-level warnings (isolation drift, missing env vars, config issues, etc.) are consolidated into a single amber chip next to the enable toggle. Click it to see each warning item-by-item; it shows a spinner while Supbuddy re-checks the project.
  • Enable toggle (right edge): turn the project's proxy on/off without deleting it.
  • ⋯ actions menu (right edge): every project-level action: Edit project (its name, domain, TLD and Supabase path; it shows the folder but does not change it), Rescan, Re-check configs (re-runs the connection/env drift check for this project), Select folder (moves the project to another folder), Export bundle, Switch to Thin / Switch to Host… (or Migrate to Thin… for a legacy VM project), and Delete project. While an isolation switch is in progress, the switch and Delete wait for it.
  • An action the daemon refuses, or that fails, says why. Rescan from the ⋯ menu, a Supabase, Compose or script Start, Stop or Restart, the unhealthy banner's Restart buttons and the Config editor's restart show the daemon's reason (a notice, or their own error line) — they used to show nothing, and a refusal read as success. A Supabase or Compose Start, Stop or Restart, and those Restart buttons, answer only once the CLI is done; past the app's 15 seconds (a start pulling images or waiting for health) they say there is no answer yet and that the action may still be running, rather than that it failed, and the card's status line follows it to the end. If the app's connection to the daemon closes and does not come back within 15 seconds (the daemon quit or crashed), every action still waiting says there is no answer yet then, rather than at the end of its own wait (an export's hour, a repair's 10 minutes); a connection that comes back within those 15 seconds changes nothing, and a second close within them, with no reconnect between, does not start them over. A Supabase Start or Restart, or a container's Restart, that then fails stays on the card as an issue (Supabase start failed or Supabase restart failed, with the reason) until a start works, or for a container until that container restarts, or until you Dismiss it in the card's issues list; a start you cancelled is not a failure, and the issue never replaces one left by a stop that did not finish, which goes once a stop works (the card's Supabase → Stop included) or when you dismiss it. A switch to Thin that starts Supabase keeps a failed start on the card in the same way: the switch still succeeds, and a start that failed, or that you cancelled (the switch had already stopped the old stack), stays as Supabase start failed, its reason beginning "The switch to Thin did not start Supabase". A switch asked not to start Supabase (MCP's register_project, or switch_isolation without auto_start) still stops the old stack before it writes the port block: if the block then can't be written, the stack is left stopped with its config as it was, and that stays as Supabase stopped, not prepared, its reason beginning "The switch to Thin left Supabase stopped and could not prepare it". Start Supabase once the reason is fixed (a Thin start writes the block first), or switch to Thin again; either one that works clears it. A failure before the old stack was stopped touched nothing and is not recorded. Over MCP these are the project's supabaseError (supabase_error in get_supabase_status), operation start or prepare, not isolationError. The Supabase details dialog shows why the details or the env-file list could not load, and an env file it cannot read says why; an empty env file shows empty. The rescan a card runs when you expand it stays quiet.

Readiness banner

Between the header and the tabs, a card shows one bordered row per readiness finding — dependencies not installed or out of date, Supabase connection vars missing or stale, keys the project's .env.example declares that nothing sets. Each row carries the finding's detail, its evidence (project-relative paths and key names, never values), and, where Supbuddy can fix it, a button whose words come from the finding itself: Run pnpm install in a pnpm repo, Run yarn install in a yarn one. While an install runs, the banner shows a live tail of its output and a Cancel button, and the fix buttons are disabled — including when that install was started from the CLI or by an agent. If the install exits non-zero, the banner says so and keeps the output: a red row naming the exit code, the last lines of the run still under it, and a Dismiss button — it stays until you dismiss it or start another install. A cancelled install is not reported as a failure. A ready project shows no banner. See Project readiness.

When the daemon refuses a scan, a fix or a cancel, the banner shows its reason; a refused scan is never shown as a project with no findings.

Issues popover

Clicking the issues counter opens a popover listing all current errors and warnings — including readiness findings. Each issue shows a severity icon, title, optional detail, and a → open {tab} link. Clicking the link jumps to the relevant tab and closes the popover.

Body tabs (when expanded)

The body renders a flat tab strip with 6 conditional tabs. Below ~480 px, the strip collapses to a dropdown selector. (Project-level actions, like edit, rescan, re-check configs, select folder, export, and delete, are in the header's ⋯ menu, not a tab.)

Apps (default tab)

Per-app rows are domain-first: domain → :port (with hover-revealed copy/open URL buttons), then app name + tech badge, then a flex spacer pushes hover-revealed edit / delete / access (LAN / Tailscale state) actions and the per-mapping toggle to the right edge. A Map CTA appears on hover for unmapped apps. Manual mappings scoped to this project (not auto-generated) are listed below under their own subheader.

Supabase (shown when Supabase is detected)

Environment section (top): host/thin switcher. A legacy project still on the old Isolated (VM) mode shows the migration wizard here instead (see Migrating a legacy Isolated (VM) project to Thin).

Action bar: Start, Stop, Restart buttons; a first-class Connect button (cyan, opens the connection panel for .env generation / merge); and a More menu with Config editor and Details.

One Supabase operation at a time, per project. A project's Supabase start, stop and restart, its Thin switch step and rename, a migration and the cleanup when it is deleted run one after another, in the order they were asked for, and a restart is one operation from its stop to its start. Click Start while a switch to Thin is converting the config, and the start waits for the switch and then starts the converted stack; a start asked for while a legacy VM project moves to Host waits for the move and starts the Host stack. What you are waiting on with the card open answers at once instead: saving or restoring a backup in the Config editor, accepting or restoring a config.toml audit fix, the analytics toggle, supabase init and restarting a single container are refused while another Supabase operation runs for that project — Supabase is busy for this project: <operation> is in progress. Try again when it has finished. — and nothing is written. Over MCP the same tools refuse the same way (write_supabase_config, restore_supabase_backup, accept_supabase_config, restore_hosted_supabase_config, set_supabase_analytics, init_supabase, restart_supabase_container); start_supabase, stop_supabase and restart_supabase wait their turn. So does changing which config a project uses — Select folder with a different folder, a new Supabase path in Edit project, set_supabase_config_path, and update_project with isolation — which is refused while another Supabase operation runs for that project, and changes nothing (a rescan of the same folder, and an edit that keeps the Supabase path, are not). Cancel still reaches a start that is running. A container restart is also refused unless the container is this project's: its Docker Compose label must name the project_id in the project's own config.toml (a name that merely ends in it is not enough). Work asked for once a project has been deleted is refused with the project was deleted.

The connection panel: which button actually connects your app. The panel generates the project's Supabase/app-URL variables using the app's framework prefix and targets the file that framework loads (see Framework env vars: prefix and file). The Prefix dropdown opens on the prefix that table gives the app being written to — NUXT_PUBLIC_ for a Nuxt app, PUBLIC_ for Astro and SvelteKit, none for Remix or an app whose framework was not detected — and it follows the Write to app when you change it. Override it if you keep a different spelling; the dropdown offers every prefix Supbuddy knows, EXPO_PUBLIC_ included. Two buttons write, and they are not interchangeable:

  • Set env vars (then Apply & next, one file at a time, with a per-key diff) merges the values into the env file your app actually reads — .env.local for Next/Vite/SvelteKit, .env for Astro/Nuxt/Remix — backing the original up first and preserving your comments. This is the one that connects the app and clears the supabase env: warning.

How Set env vars merges. It reads the file the way your framework's loader (dotenv) does, so what it edits is what your app sees:

  • Each assignment of a Supabase key whose value differs has only its value replaced. export , the spacing around = (or :), an inline # comment and Windows line endings (CRLF) stay as they were. A line that already holds the value is left byte for byte.
  • When a key is assigned more than once, every assignment is updated, so the last one — the one your app gets — is Supbuddy's.
  • A line inside a multi-line quoted value (a private key, a certificate) is never edited, even when it looks like SUPABASE_URL=….
  • A key with no assignment, or whose last assignment can't be edited where it stands (a multi-line value, or a KEY and its = on different lines), is added at the end under # --- Supbuddy managed ---. Applying again adds nothing more.
  • The review lists the keys Apply will change; for one assigned more than once, its "before" is the last assignment that differs.
  • A value is written so that it reads back exactly: unquoted when that works, otherwise in quotes (a value holding #, spaces at either end, or a line break), and a rewritten value keeps the quotes it had. Supbuddy never writes a value holding $, because Next and Vite expand $NAME in env files, quoted or not: such a key (in practice only a hand-set JWT secret) is left out, and the review says so. Before anything is written, Supbuddy reads the result back as your loader would; if any other key would read differently, Apply stops and leaves the file as it is.

Backups and safe writes. Before Apply changes a file, Supbuddy keeps a copy of it in its own folder, not in your project, so it can't be committed: env-backups/<project id>/<time>-<random>-<path hash>__<path in the project> under Supbuddy's state folder (~/Library/Application Support/Supbuddy on macOS, ~/.config/Supbuddy on Linux, or SUPBUDDY_STATE_DIR), readable by the same people as the original. Apply's result names the copy (backupPath). The newest 10 copies of each file are kept, older ones removed as each new one is made (never one made in the last minute); a copy of exactly what the newest one holds is not made again, so a write that keeps failing after its backup (a full disk) doesn't rotate the file's history out, and a project's copies go with it when it is removed for good (deleted without keeping its data, or expired from the trash). A path too long for a file name is kept under its hash and the file's name. Copies earlier versions made (without the hash) are never pruned; they go with their project. The new content is written to a temporary file beside the target (.supbuddy-<random>.tmp) and then moved over it, so a crash or a full disk leaves either the old file or the new one, never half of one; a symlinked file stays a symlink. A file Supbuddy may not write (read-only, or not its user's to write), or one whose folder can't take the temporary file, is refused with Supbuddy can't write <file> …, so it left it as it is., as before, and nothing is backed up. A file with another hard link is refused, with it is a hard link (it has another name), so Supbuddy can't tell which project it belongs to; make it a symlink or a copy, and nothing is backed up: earlier versions wrote it in place, so both names kept showing one file, but the other name could be in another project. Two exceptions keep the old behaviour: a file owned by another user is written in place, so it keeps its owner, ACLs and extended attributes; and a file that doesn't exist yet, on a file system without hard links, is created directly, so a crash there can leave a partial new file (no content that was there is lost). A file that is a mount point the rename can't replace is written in place too, backed up first. A write in place that fails partway (a full disk) writes back what the file held and is refused, saying so; a write that fails after its backup names where the backup is. A file bound into a container on its own (docker run -v ./.env:/app/.env) keeps showing the container its old content after Apply, as after an editor's save: bind the folder instead, or restart the container. If the process dies in the instant between writing the temporary file and moving it, the temporary file stays behind until the next Apply into that folder removes it. If it dies just after a new file is published, the file keeps its temporary name as a second name beside it: Supbuddy still reads it, and the next write removes that name once the file has gone a minute without a change. The name shares the file's modification time, so that minute counts from the file's last change, not from when the name was left; a file changed within it may be a write still in progress, and the write is refused, to retry in a minute. Until then git sees it, and it holds the file's content: delete it, or let the next Apply remove it. Backups that earlier versions wrote beside the file (<file>.<time>.bak) stay in your project; you can delete them.

Files it can't read are left alone. A merge target that exists but can't be read — no read permission, a FIFO (1Password's mounted .env), a socket, or a symlink to a file that doesn't exist — is never merged as if it were empty: Apply stops with Supbuddy couldn't read <file> (<reason>), so it left it as it is. and writes nothing. Over MCP, diff_env and apply_env answer a target refused where it is (a link out of the project, a FIFO, a hard link, a read-only file) as scope_denied, as the env file tools do: it stays refused until the file changes. A merge that would change how a key reads (Supbuddy couldn't merge <file> without changing how it reads <key>) is invalid_args, as write_env_file answers the same check. A file that changed while it was read, or a read that fails for another reason (no read permission), is internal_error, to retry. The list of files to merge into shows such a file amber with the reason, and never puts it in the review. If the file changes between Supbuddy reading it and writing it, Supbuddy builds the merge again from the file as it is now, so your edit is kept; after three changes in a row it stops with <file> kept changing while Supbuddy was writing it, so it left it as it is. Try again.

  • Write .env.supbuddy writes a reference file, <app>/.env.supbuddy. A recorded app Connect skips (one in another project's folder, outside every project, or in a project registered inside this one) is not offered: with no other app, the file goes in the project's own folder, and the preview's and the write's warnings name the skipped app and where the file goes. No framework auto-loads it, so on its own it changes nothing your app can see and the drift warning stays. It is for copying values out of, or for source-ing by hand. Whenever Supbuddy moves the project's Supabase ports in config.toml, it moves them in an existing .env.supbuddy too: DATABASE_URL, and SUPABASE_URL / SUPABASE_STUDIO_URL when they name a local port rather than a mapping. That covers a switch between Host and Thin (supbuddy project add on Thin included), removing a project (its original ports go back), the move from VM, a Thin start or restart that puts the port block back, a rename of the Thin stack, pointing the project at another Supabase folder, and the config editor, write_supabase_config, a backup restore, the analytics toggle, the hosted-config restore and supabase init, each with the port block they re-apply. When that re-apply fails, the file follows the ports the config is left on. Only a file Supbuddy wrote (it starts with its # Generated by Supbuddy line) inside the project is changed, and nothing else in it: in the project root, an app folder, and any folder Supbuddy wrote it into (write_connection's target_app_path, supbuddy connect write --target), which it records in its state folder (connection-env-folders.json) when that folder is inside the project's own folder. A folder that belongs to another project registered inside this one (a monorepo app added as a project of its own) is left to that project. A file written into another folder by a version before this one is not followed until it is written again. Writing it is refused while the project's Supabase is busy (a start, a switch, a config write): Supabase is busy for this project … Try again when it has finished. Nothing is written then.
  • When the daemon refuses or fails one of the panel's actions, the panel says why. This covers Apply & next, Write .env.supbuddy, Test, the config audit's Accept, Keep and Restore, and Dismiss. A refused Apply stays on its file, so you can retry or skip it; it is not counted under "Updated". A file whose diff cannot be loaded is shown with Retry, Skip and Cancel. The unhealthy banner's Disable analytics keeps its warning, with the reason, when it was refused.
  • Env-file paths are shown relative to the project's folder in the panel and its review.

NODE_EXTRA_CA_CERTS you set yourself is kept. For a project with HTTPS URLs, Set env vars also sets NODE_EXTRA_CA_CERTS to Caddy's root certificate, so server-side Node code (middleware, server actions) trusts your .local domains.

When it may set it:

  • Supbuddy writes it only when every assignment of it is a plain, one-line NODE_EXTRA_CA_CERTS=<path>, optionally with export , whose value is empty or one of Supbuddy's own absolute paths. A relative path is never Supbuddy's.
  • That has to hold in the file being merged into and in the .env, .env.local, .env.development and .env.development.local beside it, because your dev server loads those together.
  • When it holds, Supbuddy rewrites those lines in place (keeping export ), or adds the line if there is none.

When it doesn't hold, Supbuddy leaves the key exactly as it is and tells you why. That covers:

  • a corporate or Zscaler bundle;
  • a value it can't read with certainty, such as one with a # comment, $VAR, odd quoting, a control character, or a multi-line quoted value anywhere in the file;
  • a sibling file it couldn't read.

Supbuddy only reads a sibling that is a regular file inside the project. A FIFO, such as 1Password's mounted .env, a socket, a device, or a symlink leading outside the project counts as unreadable and is never opened. Your own lines stay as they are too, even Supbuddy's older ones. When a file's last assignment is one of Supbuddy's own, the message names that line as the one the file puts in effect. When Supbuddy's line and a different value are in different files, it names both and says which one applies depends on your framework's load order. Supbuddy doesn't guess that order, because it varies with the framework and its mode.

The review shows the kept value amber, with the file and both paths. After Apply, the Done block turns amber: "Finished — Supbuddy left some values as you had them", instead of "Safe to start/restart". The readiness banner's Set env vars fix shows the same messages. Apply stays enabled for a file whose only finding is a kept value. It writes nothing there and doesn't count the file as updated.

To have Supbuddy's CA too, put your bundle and Supbuddy's root certificate in one PEM file and point NODE_EXTRA_CA_CERTS at it. A kept value is never connection drift, so it doesn't bring back the supabase env: warning.

This check is deliberately conservative. A framework that loads fewer of those files (Nuxt, or classic Remix, reads only .env) can still have the key left alone because of a sibling it never reads, and is told so.

Config editor: secret extraction. When you save a supabase/config.toml that contains a secret-bearing value inline (e.g. an SMTP password under [auth.email.smtp], an OAuth secret, or any *_key/auth_token), Supbuddy prompts before writing: it lists the detected secrets and lets you pick which gitignored env file to move them to: the project-root .env.local (the default) or, for a project whose Supabase folder is not its root, that folder's .env.local. Those are the files Supbuddy reads the secrets from and passes to a supabase start (the Supabase CLI may also load env files of its own, such as ones in the supabase folder), so an app folder's env file is no longer offered: secrets moved there left config.toml naming a value Supbuddy never passed to the start. The value is written there and replaced in config.toml with an env(SUPABASE_…) reference, so the committed config.toml no longer holds them; the file is gitignored where it is, by its own path (/.env.local), so a nested project's editor writing its enclosing project's .env.local ignores it in the enclosing folder's .gitignore. With that entry in place, before the secrets are written, Supbuddy asks git about the file where it lands, in the repository that holds it, as it asks about .env.supbuddy (see Project). If a later .gitignore line takes it back (one starting with !), or the repository already tracks it, the secrets are still moved and the editor says so under its toolbar after Save, naming the git command that shows or fixes it, until you close the warning or save again. write_supabase_config returns the same sentences as ignore_warnings, and supbuddy supabase config apply prints each as a ! line. The target is held to the project as the env view's read is: a nested project's may be its enclosing project's file, and an enclosing project's may not be a nested one's. Supbuddy injects those SUPABASE_-prefixed values back into the supabase start environment so the references resolve. (Saving a config with no inline secrets writes directly, with no prompt.)

Service rows (read-only): status dot, service name, URL. No inline actions; lifecycle is driven by the action bar.

Compose (shown when Compose services are detected)

Action bar: Start, Stop, Restart. Service rows are read-only (status dot, name, URL). Add-on services declared in supbuddy.addons.yml (see Add-on Compose services) appear here alongside the base stack and in get_compose_status over MCP.

Other (shown when non-Supabase, non-Compose services are detected)

Read-only service rows: status dot, name, URL.

Scripts (shown when scripts are detected)

Bookmarked scripts appear in a Quick Access group at the top; remaining scripts appear under Other Scripts. Per-script row: status dot, name, uptime, bookmark star, Start/Stop/Restart buttons. A search input appears when there are more than 5 scripts.

Stop kills the whole tree, not just the shell. A script runs as <manager> run <name> under a shell, so the dev server you care about is that shell's child — Supbuddy now signals the process group (SIGTERM, then SIGKILL five seconds later), so next dev/vite and anything they started go down with it. Earlier builds signalled only the tracked shell: the row went back to stopped while the server kept running and kept holding its port, and the next Start failed with EADDRINUSE against your own leftover process, which you then had to find with lsof -i :3000 and kill by hand. The same applies to Stop from supbuddy and over MCP — all three drive one supervisor.

AI Tools

Wraps the project-context-sync panel: sync mode selector (Auto / Manual / Off), detected targets list with per-target scope (global / local), advanced options, and recent activity. See Per-project AI context sync for what global vs. local means.

Project-level actions (Edit, Rescan, Re-check configs, Select folder, Export bundle, Delete) are no longer a tab. They live in the header's ⋯ actions menu.


Multiple Supabase projects (the main use case)

The reason Supbuddy exists. Stock Supabase CLI binds to fixed ports (54321 Kong, 54322 Postgres, 54323 Studio, 54324 mail). Two projects on the same machine collide; you must supabase stop one before supabase start-ing the other.

Two ways to break that constraint, picked per project in the Supabase tab → Environment section:

Switch a project to Thin. Supbuddy assigns it a free port block (in the 55000+ range), writes those ports plus a unique Compose project_id into its supabase/config.toml, and starts it with supabase start on your normal host Docker — the app does by default, MCP only with auto_start: true — with no nested containers and nothing to pull. Several projects boot side by side this way; each is reached by name (api.acme.test, studio.acme.test, mail.acme.test). Switch back to Host and Supbuddy stops just that project's stack and restores the original config.toml. It does that only through a config.toml that still names the project's managed project_id. When the file names another stack (a hand edit, a supabase init run in a terminal), or is gone, the switch to Host and the cleanup when the project is deleted stop nothing through it and leave it as it is. If the managed stack is still running then, the switch is refused and the project stays Thin; a delete leaves it running and logs why. Stop it with supabase stop --project-id <managed id> (its data is kept; for an id an earlier version made longer than 40 characters, its first 40, the id the CLI runs and the one the message names), then switch again; if Docker could not be asked, start Docker, then switch again. Meanwhile Supabase → Stop (and MCP stop_supabase) refuses for such a project, naming the same command, and disabling the project skips its Supabase stop: each acts through the config, and would stop the other stack. Either switch stops the stack before it touches its config.toml, and a stack that will not stop keeps the config it runs from: the switch to Thin leaves it unconverted, the switch to Host leaves the Thin port block in place, so the stack can still be stopped. The project card then shows Supabase stop failed with the reason; stop the stack, then switch again. While that switch to Host is unfinished and its stack still runs, the project's config.toml is the only thing that names the stack, so Supbuddy refuses any config write that would remove its project_id. That covers the editor's Save, write_supabase_config / supbuddy supabase config apply, restoring a backup or the config.hosted.toml snapshot, the analytics toggle and accepting config drift. The refusal changes nothing and says what to do: stop the stack (Supabase → Stop), or switch to Host again, which stops it and restores the config. Which recovery it offers depends on the file. The switch to Host is offered only when the file names the stack plainly. A quoted "project_id" key is told to stop the stack. A file that names it ambiguously, such as a project_id line inside a multi-line string, or text that is not valid TOML, is told what to fix first. A legacy VM project between its move to Thin and the move's finish is held the same way, and is told to finish or retry the migration. Once the stack has stopped, the write goes through. A Thin project keeps that block for as long as it is Thin: anything that creates or replaces its supabase/config.toml afterwards gets the block re-written into the new file, because the content that lands there declares the stock 54321–54324 ports that belong to whichever project is on Host. That covers creating one — supabase init from the app or init_supabase over MCP on a project that had no Supabase yet, or repointing it to another config (set_supabase_config_path, Edit project's Supabase path, Select folder), which writes the block into the new file in the same step as the change, or refuses with nothing changed — and replacing one: saving the visual config editor, supbuddy supabase config apply / write_supabase_config, restoring a config backup (supbuddy supabase restore, restore_supabase_backup) and restoring the config.hosted.toml snapshot. A backup or snapshot usually predates the switch to Thin, so restoring one verbatim would put the project back on the stock ports; the ports and project_id are re-imposed on top, and everything else in the file you restored is kept.

A Thin start or restart applies the block first. A supabase init run in a terminal, a hand edit, or anything else that leaves the CLI's stock ports in a Thin project's config.toml no longer reaches the CLI as it is. Before a start or restart checks its ports or stops anything, Supbuddy writes the managed project_id and port block into the file when it does not carry them, so the stack starts on its own ports. A key the file lacks is added: a missing field under its section, a missing section ([api], [db], [db.pooler], [studio], [analytics]) at the end, a missing top-level project_id before the first section. The mail catcher's ports go only into the mail section your file declares. Switching back to Host restores what you had; for a key that was absent it writes the stock value (for project_id, the real name of the Supabase folder, a link resolved and the case as on disk, which is the name the CLI ran it as), and the added lines stay. A switch to Thin of a config with no project_id refuses, writing nothing, when that folder can't be resolved just then, since the name to restore can't be told: try again. A project an earlier version switched to Thin may have no original project_id on record; its switch back to Host writes that real name too, and refuses the same way before stopping anything.

It refuses, changing nothing and touching no stack, when the write would not be safe. The message says which case it is:

  • No mail section. Which one the CLI reads depends on its version, [local_smtp] (CLI 2.x) or [inbucket] (earlier), so Supbuddy does not guess. Add the one your CLI reads, then start again.
  • A port Supbuddy cannot rewrite: a dotted key (api.port = …) or an inline table (api = { port = … }). Write it as a plain port = … line under its [section] header.
  • A config.toml that is not valid TOML. The CLI could not read it either: fix it.
  • A stack running under the project_id the config names. Under the project's managed id, a start cannot move a running stack: Restart it, which applies the block and restarts it. Under the project's own original id (its Host-era stack), run supabase stop in the project's Supabase folder, then start again. Its data is kept, and a switch back to Host brings it back.
  • Another stack's data under the project_id the config names: running or stopped containers, or volumes, of a stack that is not this project's. Re-identifying the config would start an empty managed stack beside it. If nothing else has a claim on that id, the refusal says how to remove that stack: run supabase stop --no-backup in the project's Supabase folder, then start again. That deletes every data volume of that stack: its database, Auth and Storage. supabase db dump --local saves only your own schemas, not the auth and storage schemas or Storage's files. Supbuddy does not move or copy that data. If another project may hold that id, a project deleted with Keep data kept it, or Supbuddy can't tell, the refusal says so and never offers that: give the config a project_id of its own instead. Nor for a config with no project_id: its stack runs under the name of the project's own Supabase folder, its real name or the one on record, so the refusal leaves it alone and says to give the config a project_id of its own. Data under either of those names is the project's own Host-era stack when its record's original is one of them, as for a project an earlier version switched to Thin through a link, and it doesn't refuse. The same holds for a config whose project_id is one of those names, its folder's real name or the one on record: it is never offered that, and its data is the project's own when the record's original is one of them too.
  • Docker not answering, or a project_id with characters a Compose project name cannot have (letters, digits, ., _ and - only, with at least one letter or digit). A config with no project_id is checked by its folder's name as the Supabase CLI runs it: a folder My App runs as My_App, and switches. A switch back to Host then writes project_id = "My_App", the same stack, so a later switch to Thin checks it too. Only a folder name the CLI keeps nothing of (such as ___) is refused, saying to set a project_id.
  • The file changed while the block was being applied. Try again.

The same checks guard every write of the block: the switch to Thin, the re-write after a config.toml is created or replaced, and a repoint. A refusal there is reported in its own words, for example as thin_supabase_block_warning over MCP.

Renaming a Thin project renames its stack. Its Compose project_id follows the name (sb-<name>-<id>), at most 40 characters: the Supabase CLI runs, labels and names the volumes of a longer project_id as its first 40, so a long name is shortened and the -<id> ending kept. A project an earlier version gave a longer id runs its stack as that id's first 40 characters. Its next start moves the project, and its config.toml, to those 40 characters — the stack that already runs, so no container or volume changes — and from then on a delete, the wipe and a rename reach that stack as for any project. It is left as it is, and the start goes on, when another project may run that stack: another project's id the CLI also runs as those 40 characters (two long names alike in their first 37 slug characters already share one stack, with one database), another project's config or Compose project naming them, a project deleted with Keep data that ran as them, a Host one included (that data is still there, and a delete of this project would then remove it; one whose Supabase config or compose file could not be read when it was deleted holds every such move back), an id Supbuddy gave a project no longer registered (its own earlier ids aside), a project whose Supabase config or compose file cannot be read, or a cloud sync session that could write the config; the log says why. Only the config's project_id line changes. A move cut short after its config was written (Supbuddy stopped before it saved the project) is finished by the next start, and meanwhile a config carrying the project's block under those 40 characters counts as its own (a config that only names them, with other ports, does not). A config naming any other id the CLI also runs as those 40 characters (another old project's, SUP-207) is refused by a start, a Restart or a block write, with nothing changed and no advice to delete that stack. Until it moves, a rename leaves that stack as it is. Supbuddy's checks of what runs under it (whether it still runs before a switch, a config write, a Restart or a retried migration from Isolated, and whose a container is), and the supabase stop --project-id … they suggest, use the id the CLI runs. The cleanup after a failed switch to Thin does not: it still looks under the longer id, so it removes nothing that start left under the first 40 characters; stop that with supabase stop --project-id and those 40 characters. In the background, after the name is saved, Supbuddy stops the stack, copies its data volumes to the new id, starts it there and removes the old volumes it copied. If that does not complete — the stack will not stop, a copy fails, the start under the new id fails, the config names another stack or is missing — the project keeps its new name and, normally, its stack the old id (the new id, with its copied data, when what the failed start created there cannot be confirmed removed or the config cannot be restored), and the card shows Supabase stack not renamed with the reason (supabaseRenamePending in get_project). The next successful Supabase start tries it again. A failed start's containers are removed by their Compose label before anything is restored, here and when a switch to Thin's own start fails, whatever the config names by then; if Docker cannot confirm they are gone, the project keeps the id they run under, and every volume. Only what the failed start added is removed; a container that was under that id before it is stopped, not removed. A rename removes only the volumes it created and the old ones it copied (each only while it is still the volume that was copied), and is refused, before copying anything, when a volume under the old id has a name that cannot follow the new id.

This is the lightest, fastest option and the right default for most setups — which is why newly registered projects default to Thin. A Thin block adds any port key your config.toml omits, except the mail catcher's in a file with no mail section (see above). Where a whole section is missing and the rest of your ports sit outside the stock 54320–54329 block, Supbuddy reports that service's port as unknown rather than substituting the stock one — on a multi-project machine the stock port is another project's service, and a mapping built from it would open the wrong stack.

Supported config.toml layout

Supbuddy reads [api], [db] (port + shadow_port), [db.pooler], [studio], [analytics], and the mail catcher. Supabase CLI 2.x renamed the mail section [inbucket] to [local_smtp]; Supbuddy reads whichever one your file declares ([local_smtp] wins if both are somehow present) and falls back to the stock 54324/54325/54326 only when it declares neither. Thin's port rewrite targets the section you already have — it never adds the other spelling, because the CLI would ignore it while the diff made the port look moved. A section header may carry a trailing comment ([api] # the API). A port written as a dotted key or inside an inline table is read by the CLI but cannot be rewritten by Thin: write it as a plain key = value line under its header. A quoted key ("port" = …) or a quoted header (["api"]) is read as the CLI reads it, and a Thin write rewrites the key as a plain port = …; an [[array]] header ends the section before it, and a line inside a multi-line string is never taken for a key.

The top-level project_id is read the way the CLI reads it, everywhere in Supbuddy: written plainly or quoted ("project_id" = "…", 'project_id' = '…'), it is the same key, and a Supbuddy write of it (a switch to Thin or back to Host, a rename) rewrites it as a plain project_id = "…" line, keeping your comment. A project_id under a table, such as [remotes.staging], and a line inside a multi-line string are not it. With none, the CLI runs the stack as the name of the folder holding supabase/, and Supbuddy names it the same way everywhere: by the folder's real name, a link resolved and the case as on disk, the one the CLI runs it as when Supbuddy starts it. Where a decision is whose a stack is, or whether it still runs (a delete's teardown, the leftover check, the switch to Thin's refusal, the check after a stop that failed), the name the project is on record under counts too, since the CLI started from a shell inside a link takes that one. A switch to Thin leaves a stack under that name, and its data, alone when another project runs it under its main name: its config's project_id, its real folder's name, or its Thin managed id, such as a project at a folder genuinely called link beside one on record through a link link. Supbuddy's own stop runs as the real folder's name and never reaches that stack, so the switch neither refuses over it nor says to stop it, unless its own stop fails, when it refuses naming the containers still running. Another project that may run the name only through a link of its own, or as an id an old record saved, is no stronger a claim than this one's, and the switch is refused as before: the stack may be this project's own, started from its link. When whether another project runs it can't be told, because a project's config can't be read, the switch is refused too while that stack runs, or holds data that is neither this project's own nor its original, but it doesn't call that stack this project's or say to stop it: it says Supbuddy runs this project's own stop from its real folder, which doesn't reach that name, and to try again once every record can be read (SUP-403). Data this project's stack wrote while started from a shell inside the link is in that stack, which the other project runs too: Supbuddy moves none of it, and a switch back to Host doesn't bring it back. The check after a stop that failed refuses the config change when either name runs, or when the folder can't be resolved just then. Where whose a stack is must be decided and that folder can't be resolved, the project is taken as one whose config can't be read: a delete's teardown holds back every stack and names it, as it does for such a config.

The analytics toggle and Accept never leave a file the CLI can't read. The analytics toggle (Supabase tab, set_supabase_analytics) sets enabled where your file keeps it: under [analytics], or as a top-level analytics.enabled key beside your other analytics.* keys. It adds an [analytics] section, with the CLI's stock port, only when the file has none. Accept on a config.toml audit fix (accept_supabase_config) writes each URL as a TOML string, escaping " and \, including the redirect URLs already in your file that it merges back in. Before writing, each one parses the edited text: it must read as your file with only those values changed. Otherwise nothing is written and the message says why, starting config.toml was not changed: (over MCP, invalid_args). The same happens when the file is not valid TOML, including a table it defines both with a [header] and with dotted keys (which the CLI refuses): fix it first. An [analytics] written as an inline table (analytics = { … }), and an [auth] or [studio] value where the file defines that table with dotted keys (auth.… = …), are set by hand. A file saved with a byte-order mark is edited, the mark kept. Comments inside a multi-line additional_redirect_urls list are not kept when Accept rewrites it.

Dev servers on Thin: every project keeps its own :3000

A Thin project also gets its own loopback IP (127.0.0.2, 127.0.0.3, …, persisted per project). That loopback covers app dev servers only — Supabase is separated by the port block above, not by the IP, so every project still needs its own Supabase port range in config.toml. Its app dev servers bind that IP instead of 127.0.0.1, so canonical ports never collide across projects — five Next.js apps in five projects can all run on :3000 at once, and Supbuddy's proxy routes each web.<project>.test to its project's IP.

Start dev servers through the launcher:

supbuddy run -- next dev          # binds -H <project loopback IP>, stays on :3000
supbuddy run -- vite              # injects --host <ip> --strictPort
supbuddy run --print -- next dev  # show what would run, without running it

supbuddy run asks the Supbuddy daemon which registered project holds the current folder and binds that project's loopback IP. If projects are nested, the deepest one wins, so a project registered inside another never borrows the outer one's IP. Only a Thin project has an IP. A Host project, a folder no project holds, or a folder two projects are registered at is an error that names the fix (for example supbuddy isolation switch <project> thin). It then makes sure the loopback alias exists (macOS; Linux needs none). If the alias is missing and cannot be added (no terminal or askpass to ask in, or sudo failed), it starts nothing and exits non-zero with the command to add it. Otherwise it injects the right bind flag for the detected framework and execs your command. It prints one concise line with the project's Caddy-proxied URL (e.g. [supbuddy] → https://web.<project>.test), the address you should actually open, taken from .supbuddy/meta.json only when that file describes the same project. For Next and Vite it also hides the dev server's own - Local:/- Network: banner (which only echoes the raw loopback IP 127.0.0.N:<port>, bypassing Supbuddy's HTTPS proxy): those two lines are filtered out of the piped output, every other line passes through untouched, and colours are preserved via FORCE_COLOR (stdin stays interactive). Other frameworks pass through with no filtering. When a project has several app mappings, it matches the one whose port equals the dev server's port (from --port/-p or the framework default), else lists them all. Make it the project's dev script ("dev": "supbuddy run -- next dev") so nobody — humans or agents — has to remember it. Never move an app to a nonstandard port because 127.0.0.1:3000 is busy; that port belongs to another project's IP space. Binding the IP does not change what Vite checks: a Vite app still needs its Supbuddy domains in server.allowedHosts — the Fix on its Apps tab, or MCP preview_vite_hosts / apply_vite_hosts (see Vite allowedHosts audit).

Supbuddy must be running. With no daemon to ask (not started, a stale daemon.json, or not answering within a few seconds), run stops and says so. Earlier versions read the IP from the nearest .supbuddy/meta.json and ran with Supbuddy closed. That file is written only by project-context sync, so it could still say Thin after a switch to Host, or belong to an outer project. To run without Supbuddy, set SUPBUDDY_LOOPBACK_IP=127.0.0.N (one of 127.0.0.2–127.0.0.254). It overrides the lookup entirely: while it is set at all, even empty, anything but such an address is refused rather than ignored. A daemon that refuses the CLI's token, or a second daemon serving a different state dir, is reported as it is. run's own flags (--print, --state-dir=, --url=, --token=) go before --; everything after -- is your command, verbatim, its own flags included.

The loopback alias is a macOS thing. macOS has only 127.0.0.1 on lo0 by default, so a Thin project's 127.0.0.N exists only while lo0 carries an alias for it. Adding one needs your administrator password, and every reboot removes it; each proxy start in the app (Start, Retry) re-adds the missing ones in its single prompt — supbuddy proxy start and MCP start_proxy do not. Linux routes all of 127.0.0.0/8 to lo already, so there Supbuddy — and supbuddy run — never touches aliases and never asks for a password for them. Whether a Thin project's alias is up is reported by get_project and list_projects as loopbackAliasUp: true or false from lo0, null when lo0 could not be read, always true on Linux, and absent for a Host project. It is read live, never stored. The missing-thin-aliases doctor check lists the aliases Thin projects lack, and doctor --fix adds them with one prompt.

Without the app. When no app is attached, the privileged steps the CLI runs itself — supbuddy run adding a missing alias, and the host bridge of supbuddy daemon — ask through sudo in your terminal. With no terminal (a server, CI), set SUPBUDDY_ASKPASS (or SUDO_ASKPASS) to an askpass helper; they run it through sudo -A. A sudoers NOPASSWD entry on its own does not help: with neither a terminal nor an askpass, they do not run sudo at all.

When to stay on Host

Keep a project on Host only when its Supabase stack runs on the host independently of Supbuddy — you run supabase start yourself on the stock ports and don't want Supbuddy rewriting config.toml. MCP registration (register_project) detects a stack like that (running containers for the project_id in the project's own config.toml — in its Supabase folder, or at its root when it has none, never another project's under a search path) and keeps the project on Host automatically; in the app's Add-project dialog, pick Host in the Environment section for such projects. Stop the stack (supabase stop) and switch to Thin whenever you're ready.

Switching in the app. Every project's ⋯ menu offers Switch to Thin (a Host project) or Switch to Host… (a Thin project; it asks first). The Supabase tab keeps its own Switch buttons. A legacy VM project's menu offers Migrate to Thin…, which opens the migration wizard. A switch shows one notification from start to end:

  • While it runs: "Switching project to Thin…", or "queued behind another switch". Once the mode is in place while Supabase starts, it says "on Thin — finishing setup…".
  • When it ends, it says how:
    • done;
    • done, with the loopback alias still to be added at the next administrator prompt;
    • already on that mode;
    • or failed, with the reason, for example a declined administrator prompt.

While a switch runs, that project's switch actions and Delete wait for it. If no result comes back (Supbuddy restarted during the switch, say), the notification says so and the card shows where the project is. Three failures also stay on the project card's issues list:

  • A failed switch, until a later switch moves the project to the other mode. A switch to the mode it is already on clears nothing.
  • A failed Supabase restart (the one after an analytics change, or an agent's restart_supabase), until a restart succeeds.
  • A resolver file that could not be written, until a later write lands or a check finds the file in place.

In the Add-project dialog, Start services after creation now applies to a Thin project too. The dialog starts from Settings' defaults (Thin and .test until Settings has loaded), and keeps what you typed when Settings arrives later.

Who on your network can reach a running stack

A running Supabase stack is reachable from your local network today, on Thin and Host alike. supabase start publishes the stack's ports (the API, the database, Studio, the mail catcher and the rest) on every network interface, and neither the Supabase CLI nor Supbuddy has a setting that changes that address. Anyone on the same Wi-Fi can open Studio, which runs SQL as postgres, connect to the database with the stock password, and read the mail catcher's invitation and recovery links, unless a firewall blocks them. Thin isolation gives a project its own loopback IP for its dev servers; it does not make the Supabase stack private.

Supbuddy reads it and warns. While a project's stack is running, Supbuddy reads the machine's listening sockets (/usr/sbin/netstat on macOS, ss on Linux; no administrator password, no network traffic) and looks at the addresses the stack's ports listen on:

  • a wildcard (*, 0.0.0.0, ::) or any address that is not loopback: other devices can reach it;
  • loopback only (127.x.x.x, ::1): this computer only;
  • no reading: could not tell, and no warning.

When one of the stack's ports listens beyond loopback, the project gets an advisory warning, for example "A program is listening on every network interface on the ports this stack uses for Studio, the database and the mail catcher: anyone on a network this computer joins can reach them, unless a firewall blocks them". It names only the services whose ports listen beyond loopback, and lists each port the same way: "A program is listening on every network interface on port 55012 (*), which this stack uses for the database". It appears in the card's issues popover and readiness banner, in supbuddy ready, and in MCP get_project_readiness, under the category network. It has no fix button and never makes a project "not ready". The readiness banner lists each exposed port with the addresses it listens on (* means every interface). A stopped stack is never read, and the card checks again when the stack starts or stops.

Ports are matched to the stack by number, which is why the warning says "a program is listening" rather than "Supabase is listening": another program on one of these ports would show the same way. The ports taken are:

  • the ones in the project's own supabase/config.toml. If it cannot be read, the answer is could not tell, never the stock ports, which may be another project's;
  • of services the running-services list shows running, so a stopped Studio is not named. Services config.toml switches off (enabled = false) are left out, and so is the pooler;
  • the mail catcher's SMTP and POP3 ports only when its section sets smtp_port / pop3_port, since the CLI publishes them only then.

MCP get_project carries the whole reading as stackReachability: each listening port's listen addresses and beyondLoopback, and reachableFromNetwork (true, false, or null with an unknownReason of config-unreadable, sockets-unreadable, nothing-listening or probe-failed). It is read live, never stored, and null only while the stack is stopped. One socket read serves every project for 2 seconds and gives up after 1.5 seconds. supbuddy project get prints it as its own block.

The macOS firewall is not consulted: its state cannot say whether Docker accepts connections from the network, so the warning says "unless a firewall blocks them" rather than guessing.

Keeping a stack local. Supbuddy cannot restrict this today: the Supabase CLI decides which addresses the stack listens on. Stop the stack while you are on a network you do not trust; stopping it closes these ports. Supbuddy will use a bind-address option if the Supabase CLI adds one.

Running them all at once

Register as many projects as you want, and all of them can be "active" (proxied) at the same time. There's no limit. A Thin project's stack restarts in seconds; a Host project needs the standard supabase start cycle.

Migrating a legacy Isolated (VM) project to Thin

If you created a project in an older version of Supbuddy that used the now-retired Isolated (VM) mode, Supbuddy detects it on launch and offers a one-way, guided migration to Thin. The migration wizard appears in the Supabase tab's Environment section for any project still flagged as VM.

The migration is data-safe: Supbuddy dumps your Postgres data, starts a fresh Thin stack, restores the dump into it, and row-count-verifies the restore before tearing down the old VM container. No data loss. After migrating, the VM is gone and there's no way to switch back (but your data is intact in the Thin stack).

Over MCP, three tools handle the migration bridge:

  • list_pending_vm_migrations (read): lists all projects still on the legacy VM mode awaiting migration.
  • migrate_vm_to_thin ( { project_id } ) (write): starts the guided data-safe migration (dump, restore, verify).
  • finish_vm_migration ( { project_id } ) (write): tears down the old VM container after migration is verified. Returns an error if called before verification passes.

A retry first removes the Thin stack an earlier attempt staged. It refuses first when the project's config.toml does not parse, because it could not put the project's own project_id and ports back into it; fix the file, then retry. It stops that stack through the file only when the file names it, so it never stops a stack the file names instead. It removes the stack's volumes only once nothing runs under its id, and forgets the stack only once its volumes are gone. If a container still runs, or a volume will not go, the retry stops there, keeps the stack's record, and names the containers to stop (docker stop) or the volumes to remove (docker volume rm) before you retry.

Custom domains & TLDs

Every mapping resolves through Supbuddy's built-in DNS server. It starts on the configured DNS port — 5353 unless you changed it — and when that port is taken (on most Macs mDNSResponder holds 5353) it takes the next free one and saves it, so it is often 5354. The resolver files and Settings → Network (DNS Server · port N) use the port it is on. By default the TLD is .test (an IETF-reserved TLD safe for local use). You can change the default in Settings → General → Default TLD to local, internal, localhost, or a TLD of your own; existing mappings on the old default are migrated to the new TLD on save (a project with its own TLD, and a manual mapping on another TLD, keep theirs). A change that would put two mappings on one name (a manual foo.local beside a foo.test, with .local as the new default) is refused, naming both, and nothing changes. A manual mapping under a project with its own TLD follows that project from the default TLD; one you saved on another TLD keeps it. A default with a dot in it, which versions before 3.11 accepted (dev.local), counts whole: a name on it moves off all of it. api.shop.dev.local is on it, so it follows a project shop with its own TLD (to api.shop.portal). A change of the default moves the projects on it, their mappings and the manual mappings on it onto the new default whole (web.dev.local becomes web.test, api.web.dev.local becomes api.web.test, and x.dev.local becomes x.test). A project's TLD edit off it does the same at once, the manual mappings under the project included (shop.dev.local to shop.portal, with x.shop.dev.local to x.shop.portal), and the project dialog shows such a project's base domain as shop on .dev.local. A name an earlier version moved keeping the first part (web.dev.test) stays as it is, and so does a name already on the TLD it would move onto: shop.dev.local with its own TLD local keeps its name at every start. A TLD is one DNS label: letters, digits and inner hyphens (not first or last), at most 63 characters. Save stays off until the one you type is valid.

A real public suffix asks first. A default TLD that is a real top-level domain on the internet — .com, .dev, .app, .io, any of the TLDs in the DNS root zone — gives every project a real internet name (myapp.com), and its resolver file sends every lookup of that name on this Mac, for every user, to Supbuddy, so the real site at that name stops working here. Typing one shows that warning in the TLD editor, and Save stays off; Use .com anyway sets it. Supbuddy itself refuses one that comes without that confirmation, whatever sent it, and changes nothing. Private suffixes never ask: .test, .local, .localhost, .internal, .lan, and any label that is not a TLD on the internet (such as .portal or .dev-local). The check is offline, against IANA's list of root-zone TLDs that ships with Supbuddy. The presets are private ones only; .dev, which used to be one, is a real TLD (run by Google, with HTTPS enforced by browsers). A public TLD set before the app asked keeps working as it is, and doctor reports it (public-default-tld) with how to move off it. MCP update_settings and the CLI can't change the default TLD.

So does a project's or a mapping's own. A project's own domain or TLD, and a mapping's domain, on a real public suffix ask the same way, unless that TLD is already in effect: your default TLD, the TLD the project or mapping is on now, or, for a mapping, its project's. A yes is for a TLD, as for the default: a project's yes covers its domain and all its mappings on that TLD (each mapping of a project lives on the project's TLD, whatever its name), and the warning says so. So a project on a .com default, a mapping of a project already on .com, and an edit that keeps a saved domain don't ask again. Supbuddy checks what a save produces: --domain=x.com --tld=test ends up as x.test and asks nothing.

  • In the app, the project dialog shows the warning under the domain, keeps Save off, and saves with Use .com anyway. The warning says what the resolver file captures, which can be more than the name (api.mycompany.com captures every name under mycompany.com), never a whole public suffix: foo.co.uk captures foo.co.uk, since co.uk is on the Public Suffix List, and a name that is a public suffix itself, such as co.uk, gets no resolver file, that those names don't resolve while Supbuddy is stopped, and that the yes covers any name on that TLD in the project, later renames and new mappings included. The mapping dialogs can only make names on your default TLD or under the project's domain, so they never need to; a mapping save Supbuddy refuses for this says where you can say yes.
  • Over MCP, register_project, update_project, create_mapping and update_mapping refuse one (invalid_args, with the warning in user_message and details.public_tld) unless you pass confirmPublicTld: true beside the other arguments, not inside patch. An agent should show the user the warning and ask first.
  • In the CLI, supbuddy project add, project set and map add take --confirm-public-tld. Only the bare flag counts: --confirm-public-tld=false is a usage error.
  • A bundle import asks too. A bundle whose domain is on a real public suffix (other than your default TLD) is imported only with a yes, before anything is written: MCP import_bundle refuses it at the plan and at the apply unless you pass confirmPublicTld: true, and a plan made with it goes stale (plan_stale) if the bundle moves onto another public TLD before the apply; supbuddy bundle import takes --confirm-public-tld; the app's import dialog shows the warning and imports with Use .com anyway, for that TLD only. As for any import, the project gets no TLD of its own: its domain moves onto your default TLD at the next restart.
  • A project or mapping saved on a public TLD before this keeps working. doctor reports it while it is enabled (public-project-tld; a disabled one has no resolver file and is reported once it is enabled again), and names on a public default TLD stay public-default-tld's.

For host resolution, Supbuddy does not use /etc/hosts for wildcards; it runs a DNS resolver. macOS's default resolver only queries port 53; Supbuddy installs a per-project resolver file under /etc/resolver/<project-domain> (e.g. /etc/resolver/myapp.local) pointing at 127.0.0.1 on that DNS port. macOS picks the longest-suffix-matching file, so per-project entries route reliably without colliding with reserved namespaces like .local (which Bonjour/mDNS owns). A file is never home.arpa itself, which your home network uses for its own names (RFC 8375: the router, printers, a NAS): a mapping nas.home.arpa gets /etc/resolver/nas.home.arpa, and home.arpa (or *.home.arpa) gets none. You'll be prompted for sudo the first time this changes.

Resolver files exist only for domains the proxy actually serves — the same set that gets a Caddy site block: enabled mappings that are either standalone or under an enabled project. A mapping that is a public suffix itself (such as co.uk), or whose resolver file would not be a plain DNS name (an underscore, a part over 63 characters), gets none, and is left out of the /etc/hosts fallback too. Such a name still resolves when another served mapping's file covers it (x.my_app.acme.test through web.acme.test's acme.test), but not under the /etc/hosts fallback, which holds plain names only. One that nothing reaches is reported: doctor (mappings-without-resolver-route), get_health (dns.resolver.no_route), and the mapping dialog, under the domain field, while you type it. Disable or delete a project and its resolver file is removed with its routes (one sudo prompt, and only when something really changed), so its domains go back to failing as "server not found" instead of resolving into a TLS handshake error from a proxy that has nothing to serve. Enabling it again writes the file back; so does restarting the proxy.

Stopping keeps the DNS configuration. Stopping, restarting or quitting Supbuddy — the app's Stop, supbuddy proxy stop, supbuddy stop, a reboot — leaves its DNS configuration in place: the /etc/resolver files, the /etc/hosts fallback block (below), and on Linux Supbuddy's systemd-resolved link and its unit, or its drop-in. A stop never asks for your password. While Supbuddy is stopped its domains stop working — they fail to resolve, or resolve and then fail to connect — which is all they could do with nothing serving them, and the next start picks them up again. supbuddy reset --tier=deep (or full) is what removes the configuration.

  • A domain on the real internet. Any TLD is accepted for a mapping or a project's own domain or TLD — a real public suffix asks first (above) — so a mapping can sit under a domain that exists publicly, and its resolver file covers the mapping's parent, unless that parent is a public suffix on the Public Suffix List (co.uk, github.io): then it covers the mapping's own name (foo.co.uk), and a mapping that is a public suffix itself gets none. A standalone mapping api.mycompany.com keeps its own domain across restarts and default-TLD changes, and sends every name under mycompany.com to Supbuddy on this machine; while Supbuddy runs it answers for api.mycompany.com and the names under it, and passes the rest, such as www.mycompany.com, to your normal DNS. A project whose domain is mycompany.com claims every name under it — www.mycompany.com included — for as long as Supbuddy runs. While Supbuddy is stopped — quit, supbuddy stop, the app's Stop, a reboot — the names that file covers don't resolve on this machine at all; only names listed in the /etc/hosts fallback block (on a Mac that needs one) still resolve, to this machine, and fail to connect. Start Supbuddy again, or run supbuddy reset --tier=deep to remove its DNS configuration. (supbuddy proxy stop is different: it stops only the proxy, so the DNS server keeps answering as above, and the mapped names resolve to this machine and fail to connect.) For anything you also need from the internet, use a reserved TLD such as .test.
  • On Linux Supbuddy routes its domains through systemd-resolved, in one of two ways, by systemd's version.
    • systemd 257 or later: a link of its own. A network link named supbuddy0, which carries Supbuddy's DNS server, its domains as routing-only domains, and nothing else: it is not a default route, so no other name reaches Supbuddy, and systemd-resolved's own fallback servers keep working while Supbuddy is stopped. A unit, /etc/systemd/system/supbuddy-dns.service, makes the link again at every boot and every start of systemd-resolved, and never starts systemd-resolved itself.
    • systemd 256 or earlier, or a machine without resolvectl or ip: the drop-in, /etc/systemd/resolved.conf.d/supbuddy.conf, as before. Through 256, systemd-resolved stops using its fallback servers as soon as any link has DNS servers, so a link there would be worse. The drop-in lists Supbuddy's DNS server as a global server, so systemd-resolved also offers it names Supbuddy doesn't manage — alongside your network's own servers, taking the first good answer, so those names keep resolving while Supbuddy is stopped. The exception is a machine with no DNS server on any network link, which relies on systemd-resolved's built-in fallback servers: Supbuddy's entry switches that fallback off, so nothing resolves while Supbuddy is stopped (quit, supbuddy stop, a reboot — supbuddy proxy stop leaves its DNS server answering).
    • Either way it follows the port the DNS server is on: a start that finds it naming another port rewrites it. A systemd upgraded to 257 moves Supbuddy from the drop-in to the link at the next start, and a downgrade moves it back. When the last managed domain goes, Supbuddy removes what it set up (one password prompt, even with the proxy stopped).
    • Without systemd-resolved — it is not running, or the machine does not run systemd — Supbuddy cannot route its domains, and says so where you would look: the project's card, get_health, get_proxy_status and get_dns_status (resolverUnavailable), the MCP tools that start the proxy or change a mapping, and supbuddy doctor. It asks for no password and offers no Retry, since neither could help: once systemd-resolved runs, restart the proxy. If something that is not Supbuddy's sits where its unit, drop-in or link would go — a file at /etc/systemd/system/supbuddy-dns.service it did not write, a symlink there, a supbuddy0 it did not make — Supbuddy leaves it alone and tells you, the same way, to remove or rename it. On the drop-in, the same goes for systemd-resolved's own configuration where it would keep the drop-in from working: other global DNS servers in /etc/systemd/resolved.conf or another drop-in (systemd-resolved asks one server at a time, so it could ask one of those for Supbuddy's domains instead), a later drop-in that empties DNS= or Domains=, a nameserver= or domain= on the kernel command line (which replaces every configured one), a configuration file Supbuddy cannot read, or other global domains that, counted with Supbuddy's suffixes, come to more than systemd-resolved holds (256 through systemd 257 and 258's first release candidate, 1024 from 258; past that it drops the rest with only a log line). Supbuddy names the file and writes nothing.
    • The route works only where this machine resolves through systemd-resolved: /etc/resolv.conf naming its stub (127.0.0.53), or the hosts: line of /etc/nsswitch.conf naming resolve. Supbuddy does not change how the machine resolves; a machine that asks another resolver (dnsmasq, a router) directly bypasses the route, and doctor says that is the likely cause.
    • When a step does not land — a password prompt declined or not answered, no terminal to ask in — Supbuddy says what is not in place in Linux's terms, wherever you would look (get_project, the MCP tools that change a mapping or a project or restart the proxy, supbuddy doctor, the proxy's status), and how to set it up again: run supbuddy proxy restart and approve its sudo prompt in the terminal running supbuddy daemon (with no terminal, set SUPBUDDY_ASKPASS to an askpass helper; the desktop app is macOS-only). A prompt that was not answered in time may still be open: answer or dismiss it first. When Supbuddy could not read systemd-resolved afterwards, it says so instead of guessing what is in place; resolvectl status shows what systemd-resolved has.
    • To remove it by hand: sudo systemctl disable --now supbuddy-dns.service, then delete the unit and run sudo systemctl daemon-reload; or delete the drop-in and run sudo systemctl restart systemd-resolved. supbuddy reset --tier=deep removes both, whichever was in use.
    • How root runs on Linux. Every privileged step runs as sudo -H /bin/sh -c, which sets a PATH of system folders first, and names every program by its absolute path, so a folder of yours early on your PATH cannot put its own sudo, cp or systemctl in their place. (It was sudo bash -c, with your PATH.)
      • Which sudo. The first of /usr/bin/sudo, /bin/sudo, /run/wrappers/bin/sudo (NixOS) and /usr/local/bin/sudo that is a program owned by root, in folders owned by root, none of them writable by group or others. A sudo on your PATH is never used. With none of these, the step fails, names the paths it tried, and asks nothing.
      • Root reads nothing from a folder you can write, where another program running as you could swap a file while the password prompt waits. Before it reads or stages anything in them, root also checks that the folders it stages in are its own: not a symlink, owned by root, and writable by neither group nor others. Those are /usr/local, /usr/local/share and /usr/local/share/ca-certificates for the CA, and /etc for /etc/hosts. After a chown -R $USER /usr/local, CA Install and Remove refuse, name the folder, and change nothing.
      • The CA certificate travels in the command. Install reads the root once; it must be at most 64 KiB and exactly one certificate that parses, or Install refuses before asking. Root writes those bytes into a staging file, checks them, renames them into place and rebuilds the store. Two stores are supported. Debian and Ubuntu: /usr/local/share/ca-certificates/caddy-root.crt, staged beside it, then update-ca-certificates. Fedora: /etc/pki/ca-trust/source/anchors/caddy-root.crt, staged in /etc/pki/ca-trust (p11-kit trusts every file in the anchors folder, so nothing is staged there), then update-ca-trust extract; root checks /etc, /etc/pki, /etc/pki/ca-trust, /etc/pki/ca-trust/source and the anchors folder are its own first. Remove takes the CA out of whichever of the two holds it, in one prompt. Before asking anything — Supbuddy's own confirmation included — it checks what root would: the store's programs are there, and its folders are root's. On any other system (Arch, openSUSE, Alpine), or where root would refuse, Install and Remove say why and ask nothing; with no store, the answer carries the steps to do it by hand (needsManual), and the CA's status reads as unknown rather than not installed.
      • A removal whose rebuild fails puts the CA file back. Remove moves the CA file aside, under a name the rebuild skips, rebuilds the store, and only then deletes it. On Debian and Ubuntu the copy stays in the CA's own folder as .supbuddy-ca-removing.*, which update-ca-certificates skips because it takes only *.crt files; on Fedora it goes to /etc/pki/ca-trust, which p11-kit never reads. If the rebuild fails, root puts the file back and says so ("… failed, so caddy-root.crt was put back; the store may still trust the CA: remove it again"): the store may still trust the CA (a rebuild can fail part-way), and the next Remove finds the file and asks again. A removal stopped while the store rebuilds (a Ctrl-C, a closed terminal or a dropped SSH session; with Java installed, Debian's rebuild takes tens of seconds) puts it back the same way, says "the removal was stopped", and stops. A removal stopped just after the store was rebuilt without the CA says that ("the removal was stopped after … rebuilt the store without caddy-root.crt, so it is removed from this store"); in a removal from both stores, a stop after the first store adds that the other store was not started, and to remove it again. One killed outright leaves the copy; until the next Remove, the CA's status says the removal has not finished (supbuddy ca status, MCP get_ca_status: removalUnfinished, with the trust unknown) rather than "not installed", and supbuddy doctor warns, whether or not Caddy's root can be read. With both stores on one machine, each is judged on its own CA file, so a removal one store did not finish is said even while the other trusts the CA, and supbuddy doctor warns then too (SUP-353). Remove takes the CA from both stores, and Install puts it back in one only, the store Supbuddy installs to, so the warning says to remove it again, then install it. It names every file Remove takes: the copies, and each caddy-root.crt still there, which Remove takes by its name. The next Remove finds it, asks, puts it back and finishes the removal. If root cannot put the file back, it names the copy and the sudo mv -T that moves it back. One CA change runs at a time: an Install or a Remove asked for while another is running (from MCP, the CLI, the doctor or a reset) waits for it to end, then looks again, so a second Remove after a good one answers "nothing to remove" without asking. A change whose password prompt was not answered within 180 s may still run once it is (the prompt stays in the terminal running supbuddy daemon, and a store's rebuild can take its time): until the daemon has its answer, every other CA change (Install, Remove, the doctor's repair, a reset's CA step) is refused at once, asking nothing, with "An earlier change to the local CA has not finished after 180 s" and how to end it (answer or cancel the prompt; Ctrl-C there ends it too, and so does stopping the daemon, which sends the sudo it started SIGTERM, passed on to root's command, and waits up to 3 s for it to end); the change that was held says the same, not that its prompt timed out; supbuddy doctor reports it as such, rather than advising Install or Remove again. The daemon runs every administrator command on Linux itself, even when an app is attached and holds its host bridge, so that answer always reaches it: an app's answer that came after the relay stopped waiting was dropped, and the hold then lasted until the daemon restarted. A reset's CA step is planned on Linux whether or not a root is found when the reset starts, and plans, removes and counts what is left in one turn, so a CA install made meanwhile either runs first and is removed, or waits for the reset. A reset counts one root per store, whether its file is in place or a copy. On Fedora, the staging folder and the anchors folder must be one file system, for a removal as for an install. Until this release a failed rebuild left the file gone while the store could still trust the CA, and a second Remove found nothing to remove; if that happened before you updated, rebuild the store by hand with sudo update-ca-certificates --fresh (Debian, Ubuntu) or sudo update-ca-trust extract (Fedora).
      • The legacy /etc/hosts cleanup (a # Supbuddy - Start block from early versions, removed when the daemon starts and by a reset) strips the block from root's own read of /etc/hosts. If the file changed between Supbuddy reading it and you approving, or is no longer a regular file (a FIFO, a device, a folder), the step exits 76 and changes nothing; the next daemon start or reset plans it again from the current file. Where /etc/hosts is a mount point (Docker, Podman and dev containers bind-mount it), root writes its checked copy over the file in place instead of renaming it.
      • BusyBox systems (Alpine) have no GNU stat at /usr/bin/stat, and their mv has no -Z. CA Install and Remove say so before anything is asked, with the steps to do it by hand; the legacy cleanup refuses at root's own check and changes nothing. The old copy worked there.
      • A step is one argument, and Linux caps one argument at 128 KiB (MAX_ARG_STRLEN, counting the PATH=…; export PATH; before the step and the terminating NUL). A longer one is refused before anyone is asked, and the message names the limit; it used to fail as sudo started, with only "could not run sudo: spawn E2BIG". Supbuddy routes at most 256 domain suffixes on Linux, as on macOS, though systemd 258 and later (from its second release candidate) would hold up to 1024. With more, the DNS step is refused before anything is asked, saying to disable or remove some projects or mappings (a supbuddy proxy restart would only refuse again), and what is set up already stays as it is. A name that does not resolve then, and supbuddy doctor, say the same: for a suffix with no route, never to restart the proxy or run doctor --fix, which offers no repair past the bound; with systemd-resolved stopped, or something in its way, after what fixes that.
      • Port forwarding (pf) is macOS's. On Linux, supbuddy pf enable|disable and MCP set_port_forwarding answer that before anyone is asked (supbuddy pf exits 1), and reload_port_forwarding asks for no password; none changes anything.

When macOS won't load /etc/resolver: the /etc/hosts fallback

On a small number of Macs the /etc/resolver mechanism is simply inert. The files are present and correct, Supbuddy's DNS server answers every managed name on its port, and scutil --dns still lists only the system's own resolvers — zero of Supbuddy's. Measured on macOS 26 with a responder that answers every query: a custom TLD failed, a custom TLD with a domain directive failed, and the real IANA TLD .dev failed too. /etc/hosts worked. This is not a TLD problem and renaming your domains will not fix it.

Supbuddy detects that state and works around it by maintaining a managed block in /etc/hosts.

  • How it engages. After the proxy starts and the resolver files have been written and reloaded, Supbuddy resolves a name that only the resolver path can answer. If the files are in sync and that name still doesn't resolve — confirmed, not on a single miss — it writes the block. Since 3.7.8 that probe runs per suffix rather than sampling one domain, and it allows a longer budget on .local suffixes, where macOS makes a negative answer wait out the multicast window (measured at ~5 s) and the old 2.5 s budget turned a real "no" into "don't know". Nothing branches on your macOS version; it is the observed condition, so it is also correct for a machine locked down by a configuration profile or MDM.
  • What it costs. The condition can only be seen after the privileged setup has run, so the very first time it is detected you get one extra password prompt. Supbuddy then remembers the machine fact, and every later proxy start folds the hosts write into the same prompt as the resolver write. Steady state: one prompt, exactly as before. A declined prompt is not retried for 10 minutes, so it can never become a password loop.
  • What it covers — and what it doesn't. /etc/hosts has no wildcards. The block carries the exact names Supbuddy knows about: every enabled mapping that has a resolver file, plus every enabled project's base domain, each pointing at 127.0.0.1 and ::1 (the same answers the DNS server gives). A brand-new subdomain that has no mapping will not resolve until you add one — the one behaviour difference you will notice. Everything else, including HTTPS and per-project TLDs, is unchanged.
  • How to see it. The block is delimited by # Supbuddy DNS fallback - Start / # Supbuddy DNS fallback - End — run grep -A20 'Supbuddy DNS fallback' /etc/hosts. get_health reports it as dns.resolver.hosts_fallback: true, and the "domain doesn't resolve" banner says so in words. Your original file is copied once to /etc/hosts.supbuddy-backup before the first edit.
  • How to get out of it. It retires itself: as soon as a proxy start finds the resolver path answering again, Supbuddy removes the block and forgets the machine fact — once it can read /etc/hosts and see the block gone; one it cannot read keeps the fallback on until it can. A block an earlier version left behind with the fallback off (its release ran while /etc/hosts was unreadable) is never removed this way: supbuddy doctor reports it (stale-hosts-fallback), and you delete it by hand. Stopping Supbuddy keeps it, like the resolver files; supbuddy reset --tier=deep removes it. You can also delete the block by hand — Supbuddy rewrites it on the next start only if the fault is still there.

Note that this block is not the old # Supbuddy - Start block from the pre-DNS-server era. That one is legacy, is deleted on every launch, and has nothing to do with this.

Per-project TLD

By default every project's domain uses the global TLD (Settings → Default TLD, e.g. .test). A single project can opt into its own TLD — set the suffix in the project dialog, pass tld to the register_project / update_project MCP tools, or use the CLI: supbuddy project add <path> --tld=portal when registering, or supbuddy project set <project> --tld=portal on an existing one (--tld= with an empty value clears the override). That project's base domain and all its subdomains then live on the override TLD (e.g. cueplusplus.portal, web.cueplusplus.portal) while every other project stays on the global default. The override is durable across restarts and is unaffected when you change the global TLD. In the project dialog, setting the suffix back to the global default (or emptying it) clears the override; saving without touching it keeps the override, even one that matches today's default. Prefer .test or a vanity label like .portal; avoid .local (it collides with macOS mDNS/Bonjour). A real public suffix such as .com asks first: Use .com anyway in the dialog, confirmPublicTld: true over MCP, --confirm-public-tld in the CLI (see Custom domains & TLDs).

LAN sharing

When LAN sharing is enabled (Settings → Network), Supbuddy binds Caddy's sites to 0.0.0.0, adds .local aliases for them and runs an mDNS responder so other machines on your local network can reach your dev servers via <hostname>.local. Useful for testing on your phone or another laptop without setting up Tailscale. With it off, the names are not advertised and get no .local aliases, and Caddy listens on this machine only: on 127.0.0.1 and ::1 (where the machine has it), at its high ports (8080/8443). Another machine on the LAN or a tailnet that connects to this one's address with a mapped name is refused. Containers still reach mapped names through host.docker.internal: Docker Desktop on a Mac forwards it to this machine's loopback, and on Linux Caddy also listens on the address of Docker's default bridge (docker0, usually 172.17.0.1), where host.docker.internal points by default — for a container on a Compose network too, and whether or not a container is on that bridge. On Linux that bridge address is the exception to "this machine only": a machine on the same network segment that routes 172.17.0.0/16 through this one can reach it. A renamed bridge, a custom host-gateway-ip, rootless Docker, and Podman (host.containers.internal) reach neither docker0 nor this machine's loopback: those need LAN sharing on. A running Supabase stack's own ports are a separate matter, open to the LAN whatever this setting says: see Who on your network can reach a running stack.

Changing it — in Settings, or with MCP update_settings ({ "patch": { "lanSharing": true } }) — restarts Caddy if it is running, so the new sites take effect, and starts or stops the mDNS responder to match. The restart waits for any proxy start, stop or restart already under way, so it never brings back a proxy you just stopped; turning sharing off stops the responder even while the proxy is stopped (supbuddy proxy stop leaves it running). update_settings answers with what it did (lan_sharing: Caddy restarted, down or failed, the responder requested, stopped or unchanged, and applied: { lanSharing }, the value it applied — when two changes arrive close together, the last one, and both callers are told so), and refuses a value of the wrong type ("lanSharing": "false" is not false). supbuddy settings set --json '{"lanSharing":true}' waits up to 10 minutes for that answer, since the change can queue behind an open admin prompt.

With port forwarding on, it also updates the 80/443 redirects that let other devices reach your sites on the standard ports: on, the rules for each of your network interfaces are added; off, they are removed. This asks for your administrator password once, and only when the rules on disk differ from what the setting needs. It runs after the Caddy restart, and the change itself doesn't wait for your answer: Settings applies at once, and update_settings returns once Caddy and the mDNS responder are done. What does wait, while that prompt is open, is the proxy's next step — a Stop, a Start or another LAN-sharing change takes its turn after it, as it would after supbuddy proxy restart's prompt. If it doesn't complete (you dismiss the prompt, or pf rejects the rules), the Retry banner shows, and Retry — or the next proxy start — applies it. MCP's get_proxy_status and get_health report it too (needsPrivilegedRepair: true), even though 443 still answers on this Mac: a check through loopback can't see the rules for the network interfaces. With the app open this used to do nothing at all: the request reached the app without a command to run, and the app refused it.

Who may start that password prompt. The app's own toggle, the CLI, and an MCP client holding the system scope update the rules as above. An MCP client with config alone can still change the setting, and Caddy and the mDNS responder follow at once; but before the rules are updated, Supbuddy asks you to confirm in its own dialog (Update the port-forwarding rules (pfctl) for the LAN sharing change this client made), and only when the rules on disk need changing. Without a yes — declined, unanswered, or with nothing open to show it — no password is asked, and the change becomes a Retry item (the LAN-sharing port-forwarding update was not approved, with the approval code: approval_declined, approval_timed_out or approval_unavailable). The banner says An MCP client changed LAN sharing, and updating the port-forwarding rules for it was declined. Retry, or a proxy start you press, applies it; switching LAN sharing back in the app clears it. A later LAN change made in the app replaces that question. Like any declined prompt, the item waits for you: until then the app's automatic start (at login, or when the app reconnects with the proxy stopped) doesn't run, so no password prompt appears that nobody asked for.

A change made while port forwarding is being enabled, or while the proxy starts, is applied after them: the rules they install are compared with the settings as they are then, and updated once more when they differ.

.local TLD + LAN sharing: macOS reserves the .local namespace for Bonjour/mDNS (RFC 6762), and macOS's TCP stack short-circuits self-connections to your own LAN IP via the loopback path without consulting pf, so the obvious "redirect lo0 → my LAN IP" trick can't fix it. Supbuddy's mDNS responder works around this by ignoring queries that originate from this machine, letting the OS resolver fall through to /etc/resolver/<project-domain> (which routes to 127.0.0.1 where Caddy listens). Other LAN devices still get answered with the LAN IP and reach you normally. The net result: .local works correctly both on this machine and on other LAN devices, with no manual configuration. If you previously worked around this by switching to .test, you can switch back.

If studio.<project>.local (or similar) doesn't load: open the Configure tab. A red banner will tell you whether it's a DNS, port-forwarding, or mDNS-race issue, with the specific recovery action.

Tailscale

Your tailnet's devices can't resolve your dev domains through Supbuddy yet, and Supbuddy pushes no split-DNS routes. Tailscale split DNS sends a tailnet device's lookups for a routed name to port 53 on this Mac's Tailscale IP. Supbuddy's DNS server listens only on 127.0.0.1, at its own port, and answers with loopback addresses, so nothing there answers a tailnet device. Earlier versions pushed a route anyway when an API key was set: the whole TLD for a mapping on a private TLD (.test), the mapping's own name on a public one (web.myapp.com). Each made your tailnet's devices that use Tailscale DNS lose the name, and for a public name the real site. A listener the tailnet can reach is planned work.

  • With an API key, Supbuddy removes its own old routes. When the proxy starts (once Tailscale is connected) and at every stop, it reads your tailnet's split DNS and removes a route only when it is for a name Supbuddy maps (a mapping's private TLD, a public mapping's own name, or the whole public TLD an older version pushed for one; disabled mappings count) and points exactly at a Tailscale IP this Mac has had while the daemon ran. A route pointing anywhere else, even to this Mac's IP together with another nameserver, is left. If reading your tailnet's split DNS fails, nothing is removed and the error says why. A removal sends the API's documented null. Tailscale's API has no conditional write, so a route someone changes in the moment between the read and the removal isn't seen.
  • Stops (the app's Stop, supbuddy proxy stop, quitting the daemon, supbuddy reset --tier=deep|full) wait at most a few seconds for the removal: past that they report it as still going (splitDnsPending). If the Tailscale API refuses or cannot be reached, the stop still happens and says so: Settings → Tailscale shows the error, the stop answers splitDnsError, and supbuddy proxy stop exits 1.
  • Removing the key first removes the routes with it, then forgets it. If the removal fails, the key is still removed, and the error says to remove the routes in the Tailscale admin console. supbuddy tailscale remove-key (and set-key, when the key could not be saved) exits 1.
  • What Supbuddy cannot remove. A route an earlier version pushed for a name you have since renamed or deleted can't be told from your administrator's route to this Mac, so it is left: remove it in the Tailscale admin console.
  • What does work over Tailscale, with LAN sharing on. With LAN sharing on, Caddy listens on its own ports (8080, 8443) on every interface, the Tailscale one included, so a tailnet device that points a mapped name at this Mac's Tailscale IP itself (an /etc/hosts line, or curl --resolve) reaches the app at https://<name>:8443, once it trusts Supbuddy's local CA. With LAN sharing off, Caddy listens on this Mac only, and a tailnet device is refused. Port 443 is redirected only on this Mac and, with LAN sharing on, on its physical network interfaces, not on the Tailscale one.
  • MCP get_tailscale_status still answers splitDnsActive (always false) and splitDnsKept (always empty).

Monorepo support

Supbuddy auto-detects these monorepo layouts when scanning a project root:

  • Turborepo (presence of turbo.json)
  • pnpm workspaces (pnpm-workspace.yaml)
  • npm/yarn workspaces (workspaces field in root package.json)
  • Common folder layouts: apps/*, packages/*, services/*, sites/*

Apps are found only inside the project's folder. A workspace entry that leads out of it (../other/apps/*), or a workspace or usual folder of the project (packages) that is a symlink to one outside it, is skipped, and the scan names it: MCP scan_project returns it in workspacesOutside, register_project (and supbuddy project add) in workspaces_outside with a note, and the daemon's log says so. An app folder that is itself a symlink is not read either, as before. An app outside the folder used to be recorded, and Connect read and wrote its env files there. Register such an app as a project of its own.

Each detected app gets its own subdomain. Supabase is searched for in the project root and these subdirectories: apps/*, packages/*, services/*, sites/*, db/, db/*, database/, database/*, packages/backend, packages/db, packages/database. You can change the list in Settings → General → Supabase search paths, one path per line; a blank line is the project root. It is saved when you leave the field. Each path must stay inside the project: no absolute path and no .. segment (a folder named ..db is fine). The list holds at most 100 paths. A path saved before this rule that leaves the project is skipped by the scan. A running stack is looked for under the project_id its config names, by the label only the Supabase CLI writes, then under an older template's supabase_<project_id> or supabase_<project folder> as Docker Compose names them, so the project folder's own Docker Compose stack, which Compose labels with the folder's name, is not taken for its Supabase services. An id the CLI shortens to 40 characters or changes (its characters other than letters, digits, _, . and -) is looked for as written too, by the same label, which is how an older CLI ran it. With none in the config, it is looked for under the name the Supabase CLI runs it as: the name of the folder holding supabase/ (db for apps/db/supabase), with each run of characters other than letters, digits, _, . and - made a _, a leading _, . or - dropped, and cut to 40 characters, so My App runs as My_App, by the label only the CLI writes, so a plain Docker Compose project of that name is not taken for it; then under an older template's supabase_<folder>, as Docker Compose names it (supabase_myapp). A folder registered under another spelling than its real path, such as a link to it or, where the disk ignores case, my app for My App, is looked for under its real name first, which is the one the CLI runs it as, then under the name on record. A stack's start or stop refreshes its project's card at once, even when the scan found its config under one of these paths: Supbuddy remembers where the last scan of the project's folder found it, until a scan finds it gone, for the 256 folders scanned most recently. It forgets when Supbuddy restarts, until it next scans that project; until then such an event refreshes the card only through the project's root config.

A project's Supabase folder. A project with a Supabase path (set in Edit project, or with set_supabase_config_path) has its Supabase in <project folder>/<Supabase path>, and everything Supbuddy does with that Supabase happens there: Start, Stop and Restart (from the app, MCP and the CLI, and when the project is enabled or disabled), supabase init, the connection details (supabase status), the Config editor and its backups, the analytics toggle, the config.toml audit and its config.hosted.toml snapshot, matching its containers, and the cleanup when the project is deleted. Its scan looks there only: a Supabase folder with no config.toml shows no Supabase, even when another app's config sits under one of the search paths above, which are for a project without a Supabase path. A start passes the SUPABASE_* values from the project folder's .env.local (where the Config editor's secret extraction writes them), overridden by any in the Supabase folder's own .env.local. The Supabase CLI reads .env* files itself, from the supabase folder and the folder holding it, and takes a SUPABASE_PROJECT_ID there over the project_id in config.toml, while every check Supbuddy makes of whose a stack is reads config.toml. So every Supabase command Supbuddy runs in a project's folder (start, Stop, Restart, the switches to and from Thin, a rename, a delete's stop, the doctor's wipe, the connection details' supabase status, and a legacy VM project's move to Host) is pinned to the stack config.toml names, whenever Supbuddy can read it: its project_id, or with none its Supabase folder's real name. A SUPABASE_PROJECT_ID in the project's .env.local, in supabase/.env, in another .env* file the CLI reads, or in Supbuddy's own environment then doesn't change the stack, and the start's note says so, unless it names that same stack. Only the commands Supbuddy runs are pinned: your own supabase commands in that folder still read a SUPABASE_PROJECT_ID from the .env* files the CLI loads there and act on the stack it names, and the note says that too. To make them agree, remove the variable, or set that name as project_id in config.toml; the note offers the second way only on Host, and only when no other project has a claim on that stack. Two checkouts whose config.toml sets the same committed project_id, and which kept their stacks apart with the variable, now share one stack: one checkout's start can join the other's running stack, and its Stop stops the other's. If a stack is still running under the variable's name (by the Supabase CLI's own label on its containers) and no other project has a claim on it, the note names that stack: Supbuddy doesn't stop it, since it can't tell it is this project's. Stop it once by hand with supabase stop --project-id <name> (its data is kept in its volumes); or, on Host, to keep running that stack and its data as this project's, set that name as project_id in config.toml. The start isn't refused for it, so a restart, a switch to Thin or a rename, which stop the project's own stack first, never leave it down for that. Where that stack holds the start's ports, the port check refuses the start, or a Restart before it stops anything, and says the same in place of its usual advice. A stack under that name that another project's config names is said to be theirs and left alone; one Docker couldn't be asked about is said too. A config.toml whose project_id is an env() reference, env(SUPABASE_PROJECT_ID) or any other variable, names no stack Supbuddy's checks can read, since the Supabase CLI fills it in from that variable. So a start, a restart, Stop, a delete's stop and supabase status refuse it before anything runs, a Thin project's block write included: write the id into config.toml. A Stop or a delete's stop whose stack can't be named (Supbuddy can't read the config, or the Supabase folder can't be resolved just then) refuses too, when a SUPABASE_PROJECT_ID could take over: one in Supbuddy's own environment, or in a .env* file the CLI reads there, or such a file Supbuddy can't read, or a SUPABASE_ENV or SUPABASE_WORKDIR in Supbuddy's environment, which make the CLI read other files or run in another folder; it says to stop the stack by hand with supabase stop --project-id <id>. With no such variable anywhere the stop runs as the CLI reads the config, as it did before, as a start and supabase status do, and the log says so; a config linked from outside the project's folder is the usual case (SUP-394). A Restart refuses such a stop before it stops anything, so the project's card never shows a stop that didn't run. A project with no config.toml of its own has no stack of its own, so its Stop, disabling it and deleting it run no supabase stop, and the log says why. Run there, the Supabase CLI would walk up to a parent folder's supabase/config.toml and stop that project's stack, or stop the one a .env* file names. A legacy VM project's move to Host is refused before it stops or copies anything when a .env* file in its folder names a stack other than config.toml's, or one of those files is there but can't be read as the CLI reads it, since the VM's own stop would act on the stack the variable names: make them agree first.

Registering a project records the folder its scan found a Supabase config in as its Supabase path. That applies to register_project over MCP, supbuddy project add, and the app's Add Project with the Supabase path left on Autodetect, which shows "found in apps/db" once the folder's preview has run. A config at the project root, found first, means no Supabase path. A found folder the ownership rules refuse is not recorded, and the project is registered without one: inside another registered project's folder (a monorepo registered around a sub-project with its own Supabase), outside the project's folder through a symlink, or a path with ... Over MCP the result says why in supabase_path_note, and the app shows it. Edit project and set_supabase_config_path still set or change it, and a rescan or Select Folder never adopts one. Backups and the hosted snapshot live beside the config they are copies of (<Supabase folder>/supabase/.config-backups/ and <Supabase folder>/supabase/config.hosted.toml). A restore — the Config editor's, or restore_supabase_backup — takes only one of the project's own backups: a config.toml.backup-* file directly in that folder, given by its path or its name. Anything else (another file, a symlink, a path outside the folder) is refused before it is read (invalid_args over MCP), and nothing is written. Ones that earlier versions saved for a project with a Supabase path are in <project folder>/supabase/: they were copies of the root's config, not the project's, and are no longer listed. A legacy VM project ran its Supabase from the project root, so when it is moved to Host with a config there, the move points the project at that config: its Supabase path is cleared.

Detected app frameworks

Supbuddy picks an app's framework from evidence, not table position. It collects every known framework dependency in the package's package.json and takes the one whose dev/start script actually runs it — a package that merely depends on next for types is not a Next app, and a package whose scripts run none of them is not listed as an app at all. When two candidates both match, a fixed order breaks the tie, and that order puts meta-frameworks before the bundlers they sit on: SvelteKit and Remix-on-Vite both list vite as a direct devDependency, so a "dev": "vite dev" script resolves to SvelteKit rather than handing the app VITE_ variables it never reads.

Port detection then takes the first of: an explicit -p/--port in the dev/start script, a PORT= prefix in that script, a per-framework config file (vite.config.* / svelte.config.* for Vite and SvelteKit, astro.config.*, nuxt.config.*), then — for a meta-framework whose dev server is Vite — vite.config.*, and finally the framework default below.

Framework dependencyDetected asDefault port
nextnext3000
vitevite5173
@sveltejs/kitsveltekit5173
astroastro4321
nuxt, nuxt3nuxt3000
@remix-run/dev, @remix-run/serveremix5173 when vite is a direct dependency (a remix vite:dev app binds Vite's port), otherwise 3000
@angular/corenode4200
@nestjs/corenode3000
express, fastify, koa, hono, @hono/node-server, elysia, polka, tinyhttpnodenone (must be explicit in dev script)

SvelteKit, Astro, Nuxt and Remix are detected as themselves. Earlier versions reported SvelteKit and Remix as vite and let Astro and Nuxt fall through to node; the label is what decides the env-var prefix and the env file in the next section, so those apps were being handed variables they could not read. SvelteKit and Remix-on-Vite still get Vite's port and Vite's server.allowedHosts audit, because those follow the dev server rather than the label.

Framework env vars: prefix and file

An app only sees an environment variable if it is spelled with that framework's public prefix and written into the file that framework loads. Supbuddy keeps one table for both, and it drives the Connect panel, the connection-drift warning, and apply_env:

Detected asPublic prefixEnv file
nextNEXT_PUBLIC_.env.local
viteVITE_.env.local
sveltekitPUBLIC_.env.local
astroPUBLIC_.env
nuxtNUXT_PUBLIC_.env
remixnone.env
react, node, unknown, or undetectednone.env.local

Remix having no prefix is the right answer rather than a gap: Remix hands values to the client through its loaders (the window.ENV pattern), not through a build-time prefix.

This table is also what the Connect panel's Prefix dropdown starts from, so the panel and the drift warning cannot disagree about your app: picking a prefix by hand is an override, not the default.

The Env file column is what Supbuddy creates when the app has no env file yet. When one already exists it is preferred over creating another: the framework's own file wins if present, otherwise any env target already in that folder — and an existing .env.local counts as a target for every framework, so an Astro or Nuxt app that already keeps one is not moved to .env. Files that look like backups (.bak, dated snapshots) or non-local overrides (.env.production, .env.local.live) are never write targets.

Two values are deliberately never prefixed, whatever the framework: DATABASE_URL and the Supabase service-role key. Both are server-only and must not reach a client bundle.

Supbuddy also mirrors what your file already spells. If SUPABASE_URL, SUPABASE_ANON_KEY or SUPABASE_STUDIO_URL is present both bare and prefixed (including EXPO_PUBLIC_, which the scanner never emits on its own), both spellings are updated, so neither goes stale.

Server Actions allowedOrigins audit

For Next.js apps, Supbuddy reads your next.config.{ts,mts,js,mjs,cjs} and extracts the hosts in experimental.serverActions.allowedOrigins. If a mapped subdomain is missing from that list, the project's warnings chip flags next.config: N origins missing; Server Action POSTs through Supbuddy mappings would 403 otherwise. Open the Apps tab (the chip's "open apps" jump) where the affected app shows the warning with a Fix button.

The Fix button opens a dialog with a paste-ready snippet and an Apply… button: click it to see a unified diff of the change Supbuddy will make to your next.config, then Confirm & write to apply it. Supbuddy handles the four common config shapes (existing allowedOrigins array, existing serverActions block without it, existing experimental block without serverActions, or no experimental at all). The edit is strictly additive: existing array entries are kept verbatim, including spreads (...devHosts), identifiers and comments, and only the missing origins are appended.

If allowedOrigins (or serverActions, or experimental) is set to something other than a plain array/object literal — an identifier, a function call, a ternary, [...] as string[] — Supbuddy refuses to patch rather than guess, and the dialog says so along with the exact origins to add. This is deliberate: a wrong rewrite would produce a duplicate key (TypeScript TS1117) that breaks your build long after the fact, so the fallback is the copyable snippet. Use it and edit by hand.

After write, Supbuddy rescans the project so the warning disappears immediately. Restart your dev server for the change to take effect; Next.js does not hot-reload next.config. Over MCP the same audit is exposed as preview_next_origins / apply_next_origins; both return ok: false with an explanation in the refusal case, and apply_next_origins never writes a file it cannot verify.

Next.js cross-origin dev requests (allowedDevOrigins)

Supbuddy proxies your dev server but passes the browser's real Origin header through (it no longer rewrites Origin to the upstream address). That's required so Server Actions and other origin checks see the actual page origin — but it means Next.js 15.3+ and 16 dev servers, which validate cross-origin dev requests against allowedDevOrigins (defaulting to localhost), now treat a request arriving on a Supbuddy domain (or a Thin project's 127.0.0.N loopback IP) as cross-origin and can reject it. Add your Supbuddy domain to allowedDevOrigins in next.config:

// next.config.js
module.exports = {
  allowedDevOrigins: ['web.myproject.test'],
}

Restart the dev server afterward; Next.js does not hot-reload next.config. This is separate from experimental.serverActions.allowedOrigins (the Server Actions CSRF list above) — 15.3+/16 may need both.

Vite allowedHosts audit

For Vite apps, Supbuddy reads your vite.config.{ts,mts,cts,js,mjs,cjs} and extracts server.allowedHosts. If a mapped host isn't covered, the warnings chip flags vite: N hosts blocked; Vite's dev server otherwise rejects proxied requests for unknown hosts with Blocked request. This host ("…") is not allowed. (403). A .your-project.test entry counts as covering every subdomain, so an existing wildcard suffix doesn't trigger a false warning.

Like the Next.js audit, the affected app's Fix button on the Apps tab opens a dialog with a paste-ready snippet and an Apply… button that previews a unified diff and writes server.allowedHosts into your vite.config (handling an existing allowedHosts array, an existing server block without it, or no server block at all; allowedHosts: true is left untouched). The edit is strictly additive — existing entries, spreads and comments are kept verbatim and only missing hosts are appended — and, exactly as with the Next.js audit, Supbuddy refuses to patch when allowedHosts or server is set to anything other than a plain array/object literal, pointing you at the snippet instead of risking a duplicate-key build break. After write, Supbuddy rescans so the warning clears. Restart your dev server for the change to take effect; Vite does not hot-reload vite.config.

Project readiness (can it run?)

Registering a project gets it a domain, a certificate and a scripts list. None of that makes it run. Two things stop it, and readiness is the one check that covers both:

  • Dependencies aren't installed, or the lockfile has moved on since the last install. Before this check the way you found out was clicking Start on a dev script and reading its exit 127 several steps downstream of the cause.
  • Environment variables are missing or stale — Supbuddy's own Supabase/app-URL values aren't in the file that app's framework actually loads, or keys the project's own .env.example declares aren't set anywhere.

Every finding carries a severity (error / warning / info), a category (deps / env / toolchain / network), evidence, and — when Supbuddy can genuinely fix it — a fix descriptor: the name of a real tool plus the arguments to call it with. The project card's button, supbuddy ready --fix and an agent's MCP call all render that same descriptor, so the three cannot drift and all three run the right package manager for this project. A finding with no fix is advisory on purpose: either Supbuddy has no value to supply (a third-party secret — it will name STRIPE_SECRET_KEY, it will never invent one), or it refuses to guess (nothing identifies a package manager, or that manager isn't installed, in which case an install would only exit 127).

Evidence carries names and verdicts, never values. A readiness report reaches the MCP audit log, CLI stdout and the UI at once, so a finding names the key and the file — project-relative — and stops there. No secret, no home directory, no KEY=value. The one network finding's evidence is the ports and addresses it measured (see Who on your network can reach a running stack).

Supbuddy never installs anything on its own. Readiness reports; a person or an agent decides.

Variables your code reads that nothing sets

Readiness also reads your source — process.env.KEY, process.env['KEY'], import.meta.env.KEY, Deno.env.get('KEY') — and names the keys that no env file sets and no example file declares. It looks project-wide, so a monorepo that keeps one .env at the root and loads it with dotenv-cli isn't reported wholesale.

This is the one check that infers rather than compares, so it is fenced in on every side:

  • Severity is always info. It can never make a project "not ready", and it is kept out of the card's issues counter — it appears in the readiness banner, toned down, and nowhere that counts problems.
  • There is no fix. Supbuddy has no value for RESEND_API_KEY and will not invent one.
  • Every key carries the first file:line that reads it, so a false positive is dismissible on sight instead of being a claim about your repo you'd have to go audit. The matched line itself is never quoted: one line of source can carry a credential (process.env.DATABASE_URL ?? 'postgres://user:pw@host/db').
  • The finding says in its own words that it is inferred and can be wrong. A key behind a flag you never enable, one your CI supplies, one inside a code sample — from the outside all three look exactly like a variable you forgot.

Where it doesn't look: anything your .gitignore excludes, plus node_modules, dist, build, .next, .nuxt, .svelte-kit, coverage and .git — and your tests and build configs (*.test.*, *.spec.*, __tests__/, test/, tests/, *.config.*), because a variable only a test or a bundler reads isn't something you have to set to run the app. Comments are not code: a key that only appears in a comment is not reported, so prose explaining process.env.SOMETHING doesn't become a finding about a variable that doesn't exist.

What it never reports: NODE_ENV, PORT, CI, HOME, PATH, TZ, npm_*, VERCEL_*, XDG_*, NEXT_RUNTIME, Vite's own MODE / DEV / PROD / SSR / BASE_URL, and the names your OS or terminal supplies — APPDATA, LOCALAPPDATA, FORCE_COLOR, NO_COLOR, COLORTERM, TERM, SHELL, EDITOR, SUDO_ASKPASS. The platform's variables, not yours. (GH_TOKEN is not on that list: a project that reads it may genuinely need you to provide it.)

A scan that hits its limits reports nothing at all. The walk is capped at 2000 files for the whole project and 1 MiB per file; exceeding either yields no referenced-variable findings rather than the subset it managed to read. A truncated list under that heading reads exactly like a complete one — you'd set the three keys it named and trust the silence about the rest.

Install roots: one per lockfile, not one per app

The unit of install is the directory that owns a lockfile. In a pnpm/yarn/npm workspace that is one directory — the repo root — and a single install covers every app and every shared package in it, so a monorepo with five apps has one install root ("", the project root). An app becomes its own install root only when it owns its own lockfile; then it gets a second root and its own install.

Supbuddy picks the package manager by strict precedence, first match wins:

#SignalResult
1packageManager field in that directory's package.jsonits name (and version)
2pnpm-lock.yamlpnpm
3bun.lockb or bun.lockbun
4yarn.lockyarn
5package-lock.json or npm-shrinkwrap.jsonnpm
6none of the aboveundetermined — never a silent npm

Case 6 is a real answer, not a gap: running npm install in what is actually a pnpm repo drops a stray package-lock.json into your working tree, which then gets committed and mis-trains every detector that reads it afterwards. So a root with no signal gets no install command and no install button — the finding says so in words instead.

Whether an install has happened is read from the manager's own receipt, never from the presence of node_modules:

ManagerReceipt
pnpmnode_modules/.modules.yaml
npmnode_modules/.package-lock.json
yarn (node-modules linker)node_modules/.yarn-state.yml (Yarn 1 falls back to node_modules/.yarn-integrity)
yarn (PnP).yarn/install-state.gz
bunnode_modules/.bun-tag, else node_modules itself

A receipt older than the lockfile is stale (a warning: the project runs, it just no longer matches the repo). No receipt is not installed. A receipt Supbuddy cannot read is unknown, which produces no finding at all — receipt filenames drift between manager versions, and a reinstall button in front of a user whose project is fine is worse than saying nothing. Yarn PnP projects have no node_modules and are correctly installed; they are read from .yarn/install-state.gz, so they are never reported as broken.

What packageManager on a project now means

Project.packageManager — the value supbuddy project ls prints and get_project / list_projects return — comes from that one detector now, which changes two things:

  • It can read bun.
  • It is absent for a project where nothing identifies a manager. Older builds always printed npm there, because the old detector's fallback was a guess rather than an observation. A project with no lockfile and no packageManager field therefore now shows no package-manager chip at all instead of a confident wrong one.

Running a script uses that same answer. Starting or restarting a script — from the Scripts tab, from supbuddy, or over MCP — resolves the manager from the project's recorded value, falling back to what the project root shows. If nothing identifies one, all three refuse and spawn nothing, naming the cause ( no packageManager field, no lockfile ) and the two ways out: add the field, or install once so a lockfile exists, then rescan the project. Earlier builds quietly ran npm run <script> in that case, so one repo could be described as npm by the Scripts tab and as undetermined by supbuddy ready at the same time.

Pushing to the cloud uses it too. The dev command Supbuddy hands each app in a cloud box comes from that same answer — the app's own manager when it owns a lockfile, otherwise the workspace root's, which is what installs every member of a pnpm or yarn monorepo. An app for which nothing identifies a manager is reported as not running in the cloud, with the reason, rather than started under a guessed npm run dev: the wrong manager resolves a different dependency tree, and npm would drop a stray package-lock.json into a workspace that syncs straight back to your machine. The box's own dependency install reads the same lockfile names in the same order, so a repo locked by bun.lock (the only lockfile bun 1.2 and later writes) or by npm-shrinkwrap.json is installed like any other instead of being skipped and left to fail on its first app start.

Installing is a job, not a call

A cold install on a monorepo outlives every timeout on the path between you and the worker, so starting one returns immediately with a job ({ id, state: "running", argv, rootPath }) and the output arrives as a stream. Completion is a state transition you can watch or poll; cancellation is a first-class operation.

  • At most one install per install directory. A second request for a directory that is already installing hands back the same job rather than starting a duplicate — two package managers writing one node_modules is a corrupted store, not a slow install. The directory is the one on disk, however it is reached: after Select Folder moves a project from a monorepo's root to one of its apps, that app's install is still the one already running there. Different directories — two roots of one project, or a project's old and new folders — are independent and run at the same time.
  • A cancelled install is reported as cancelled, never success, even if the child happened to exit 0: it may have been halfway through writing the store. Treat the dependencies as not installed and run it again.
  • Deleting a project stops the installs still running for it, so nothing keeps writing into a folder you just told Supbuddy to forget.
  • And its dev servers. Deleting a project — from the app, from supbuddy, or via delete_project over MCP — stops every script it had running, for the same reason plus one more: once the project is gone there is no row left to press Stop on, so a survivor holds its port against whatever you register next with nothing in the UI able to reach it. Deleting with keep data still stops them; that option preserves the project's data, not a process writing into it.
  • Before its folder is released. Deleting a project, its trash time running out, and moving it to another folder with Select Folder all stop its installs, its dev scripts (including one already stopping or mid-restart), its context sync, the Docker Compose start, stop or restart and add-on seed Supbuddy is running for it there (a seed's compose run container too, stopped by the name Supbuddy gave it), and its cloud sync session for that folder — confirmed: a process counts as stopped when it has exited — before that folder can be registered again. Until then, registering the folder is refused as "still being released", naming what it is waiting for, or what did not stop and how to stop it by hand (Supbuddy tries again every minute). Only the folder being left is affected: a moved project's work in its new folder keeps running. A Compose start or seed asked for while the project is leaving is refused, and so is one still pending for a project whose folder another project has taken since; a seed that finishes after the project moved does not mark the new folder as seeded. A rescan the Docker watcher began before the move, or before the project's Supabase folder, the Supabase search paths, its isolation or its managed stack changed, writes nothing when it ends: the project is rescanned once more as it is then, and that rescan's apps, services and mappings are the ones written (SUP-381). Of two watcher rescans of one project, the older one, ending last, writes nothing either. The Docker Compose containers Supbuddy's own start brought up there are stopped too, by the ids it recorded: each Compose start Supbuddy runs (the card's Start and Restart, start_compose_services and restart_compose_services, an add-on seed's start, a bundle import's own start) records, with the project and the folder, the containers running after it that were not running before it, and the record is kept across restarts. A bundle import's is recorded for the project it registers, in the same step, when Docker answers its listing right after the up (one it doesn't records nothing, and the import still succeeds). Only those are stopped, by full id, never by name, label or Compose project, and each is confirmed stopped. Any other container there keeps running: one you started yourself (also one Supbuddy's start found already running), and one Supbuddy started before it began recording them (an import's start, before this version). Before it stops a recorded container, the release reads the folder Compose labelled it with (com.docker.compose.project.working_dir). One whose stack runs in another folder is left running, and its record is forgotten: from 3.14.0 to 3.16.0, a start in a nested folder with no Compose file of its own, such as mono/apps/web, started the enclosing folder's stack and recorded its containers as the nested project's. The same folder spelled another way (through a link, or in another case on a volume that ignores case) is the record's, and a container with no such label is stopped as before. While that folder can't be read (a network share that stopped answering), nothing is stopped yet: the folder stays held, saying so, and Supbuddy tries again every minute. A container Supbuddy's start brought up keeps its id when you stop and start it again yourself (docker compose stop then start, or docker restart), so it is still on the record and the release stops it. Supbuddy's own Stop of the whole project forgets the record, so a container you start again by hand after that is yours. While Docker can't be asked, the folder stays held, with "start Docker" in the refusal, and Supbuddy tries again every minute. The delete's reply says which: in the app, Supbuddy stops the N Docker Compose containers it started for <name>. Others in its folder may still be running…, or, for a project with Compose services and none recorded (one started before this version), <name>'s Docker Compose services may still be running…; over MCP (delete_project, and the CLI's project rm) the same in compose_note, said for the trash, whose expiry stops them. A recorded container left running for another folder's stack is named in it with that folder (One Docker Compose container Supbuddy recorded starting for <name> belongs to the stack in <folder>, so Supbuddy doesn't stop it…), as Docker labels it when the delete asks; if Docker or those folders don't answer within 5 seconds the reply leaves that out, and the release still reads the label before it stops anything. The system wipe (system_wipe, and supbuddy reset --tier=soft|deep, which run in the daemon) holds every project's folder the same way, from the moment it resets the registry until that work has stopped; the wipe itself does not wait for it. --tier=full runs after the daemon has exited, so none of that work is left to hold. A write Supbuddy is making there for a request is waited for too ("its file writes"): applying the Next.js or Vite allowed-hosts patch, write_env_file, Set env vars / apply_env, write_connection, and writing an MCP client's project config with its backup. Each such request — copy_env_var and scaffold_addons too — is checked against the projects as they were when it began: if, by the time it writes, the folder's project has left, moved, or another project has taken the folder, nothing is written and the request is refused (over MCP, scope_denied). A write through a link from one project's folder into another's is refused, except a nested project's file that links to its enclosing project's. A write that does not finish (a FIFO, a network folder that stopped answering) is named in the refusal. Keep data leaves the project's Supabase runtime as it is, but its references to the machine-wide agent-context files (such as ~/.claude/skills/supbuddy/SKILL.md) are released either way; that release is best-effort, and a file it cannot release does not hold the folder.

On the project card

An unready project shows a readiness banner above the card's tabs: one bordered row per finding, toned by severity, with the finding's detail and its evidence underneath. Where the finding has a fix, the row carries a button whose words come from the descriptor — a yarn project reads Run yarn install, a bun project Run bun install — and hovering an install button shows the literal command it will run. An env finding's button runs the same apply_env merge described under MCP tool surface: it writes into the file the framework loads, backing the original up first.

While an install runs, the banner shows a live tail of its output (the same ANSI rendering as the Scripts tab) and a Cancel button, and every fix button on that project is disabled — including when the install was started from the CLI or by an agent, since all three surfaces drive the same job. Readiness findings also feed the header's issues counter and its popover, with the same → open {tab} jump as every other issue.

A failed install is stated, not swallowed. An install that exits non-zero does not throw anywhere — the job simply reaches failed — so the banner would otherwise just re-render the same "dependencies are not installed" row with the output gone, which reads as a button that did nothing. Instead the banner shows Install failed (exit code N) and keeps the tail of that run underneath it, so the lines that explain the failure are still on screen when you need them. It persists until you Dismiss it or start another install, and it says only what happened and how it ended — Supbuddy does not guess at a cause. A run killed by a signal or one that never started has no exit code to name and carries the runner's own error text instead. An install you cancelled is never shown as a failure.

A ready project shows no banner. The card's status dot already carries the positive case.

Which Node runs your project's commands

Supbuddy runs your install and your dev scripts through your package manager, and until 3.7.8 it did not choose which Node that manager ran on — it built a PATH and let the shell resolve whatever came first. On a packaged app that inherits launchd's PATH rather than your shell's, /usr/local/bin sat ahead of every version-manager directory, so a stray /usr/local/bin/node could win over every version you actually use. One reported case: a repo pinning 22.23.2 in .nvmrc, with 22.23.2, 24.19.0 and 26.7.0 all installed and all satisfying its engines range, had pnpm install refused by ERR_PNPM_UNSUPPORTED_ENGINE because Supbuddy ran it on an unrelated 22.15.1.

Supbuddy now reads the project's own request and runs the command with it. The request is taken from, in order, .nvmrc, then .node-version, then package.json's engines.node — searched from the directory the command runs in upward to the project root, so a monorepo's root pin covers its packages while a package's own pin still overrides it. Installed versions are found from nvm, fnm, asdf, mise, volta and n; when more than one satisfies the request, the highest wins. Full engines ranges are honoured, including >=22 <25 and ^22.22.2 || ^24.15.0 || >=26.0.0; an unconstrained range — *, x, >=0 — counts as no request at all.

A request is a floor to clear, not an instruction to upgrade. If the Node that would have run anyway already satisfies the range, Supbuddy changes nothing. This matters because engines.node: ">=18" is boilerplate in a large share of repos: read as a request and answered with the highest installed version, it would quietly move such a project off the version you selected with nvm use — and say nothing, because nothing failed. The pin is honoured when it is not already satisfied, which is the case that was actually broken. This applies to every command Supbuddy spawns for a project — installs, supbuddy run, and dev scripts started from the app — not just installs.

Aliases are not guessed. lts/iron, lts/*, node and stable cannot be resolved without asking the network which release is current, so Supbuddy reports them and leaves the PATH alone rather than picking something plausible. Pin a concrete version if you want it selected.

It never installs a runtime for you. When nothing installed satisfies the request, the project card raises a toolchain finding that names both versions — "This project asks for Node 22.23.2 (.nvmrc); Supbuddy would run v22.15.1" — with no fix button, because installing Node is your version manager's job, not Supbuddy's. Note the consequence: a project whose pinned Node isn't installed now reports as not ready, where previously it reported ready and then failed at install time. That is the intended trade — pnpm refuses outright in that state — but it is a new way for a card to go red.

A project that pins nothing is unaffected, byte for byte: the PATH it gets is exactly the one it got before. One related fix does apply everywhere, pinned or not — if a version manager already has a version active in the PATH Supbuddy inherited, that version now keeps its place instead of being demoted below the inactive ones.

Changing .nvmrc takes effect on the next command with no restart. Installing a new Node version is also picked up on the next command; the PATH is rebuilt per spawn rather than cached.

One line in doctor

supbuddy doctor (and the app's System health panel) carries a single aggregate warning — projects-not-ready — when registered projects wouldn't run: "3 project(s) are not ready to run", with the project names as evidence and nothing else. That is deliberate. Per-project detail belongs on the card and in supbuddy ready, which can name the install root, the key and the file; a machine with twenty projects must still get a report about the machine. The line is advisory: doctor stages no install and offers no repair for it — it exists to send you to the surface that can explain it. A project whose folder has been deleted is skipped rather than reported forever on the strength of a leftover record, and a project Supbuddy could not read is listed as (could not be scanned) rather than quietly counted as healthy.

MCP setup (AI agents)

Supbuddy ships a built-in MCP server on http://127.0.0.1:9877/mcp with static Bearer-token auth. Five clients have one-click install, and Continue installs into a project from that project's setup link (below); any other MCP-compatible tool can be configured manually with the same URL + token.

Open Settings → MCP → Add client, pick the client kind, and Supbuddy generates a token, edits the client's config file, and backs up the original (<file>.supbuddy-backup next to it). The client's label takes up to 200 characters, as it does over MCP (create_mcp_client, install_mcp_config). If the install can't complete it surfaces an error toast rather than stalling. The same client-management surface (Settings → MCP → Clients: install, edit scopes, set-primary, rotate token, revoke) drives each client from the app.

Auto-install paths

ClientConfig fileTransport
Claude Code~/.claude.json (user) or <project>/.mcp.json (project)HTTP
Claude Desktop~/Library/Application Support/Claude/claude_desktop_config.jsonstdio shim via npx -y @supbuddy/mcp@latest
Cursor~/.cursor/mcp.json (user) or <project>/.cursor/mcp.json (project)HTTP
Codex CLI, its IDE extension and the ChatGPT desktop app (one shared file)$CODEX_HOME/config.toml, default ~/.codex/config.toml: an [mcp_servers.supbuddy] table with url and http_headersHTTP
Windsurf~/.codeium/windsurf/mcp_config.jsonHTTP
Continue (project only, from the project's setup link, MCP or the CLI)<project>/.continue/mcpServers/mcp.jsonstdio shim via npx -y @supbuddy/mcp@latest

A call through the stdio shim is answered within 55 seconds. The shim (@supbuddy/mcp, which Claude Desktop and every stdio config Supbuddy writes run) gives up on a call after 60 seconds and tells the agent "Request timed out", and the agent's own MCP client gives up at 60 seconds by default too. A mapping or project change can take longer: it answers after Caddy's reload and the OS resolver re-apply, which can wait minutes for an administrator password. So a call the shim sent that is still running at 55 seconds is answered with the error code still_running (details: { tool, after_ms }): it was not stopped and goes on, and is audited once it ends. Don't call it again; once it has ended, read what it did with list_mappings, get_project or get_proxy_status. This holds whatever the shim's SUPBUDDY_TIMEOUT_MS; a shim set below 60 seconds still answers "Request timed out" at its own limit. Clients that talk HTTP (Claude Code, Cursor, Codex, Windsurf, the CLI) wait for the call's own answer, as before.

A project config keeps its token out of git. Before a token is written into a project's .mcp.json, .cursor/mcp.json or .continue/mcpServers/mcp.json, the file is ignored by a line in the repository's .gitignore (/.mcp.json*, which also covers its backup and staging names, and any copy of it made beside it, such as an editor's .mcp.json~ or a .bak, which holds the token too), and git is asked. Three lines after it let a template through: !/.mcp.json.template, !/.mcp.json.example and !/.mcp.json.sample, so a file that shares the config's shape without a token can be committed. A /.mcp.json* line an earlier install wrote is kept, and gets those three lines after it at the next install. The same lines go into the repository's own excludes first, .git/info/exclude (for a linked worktree, its main repository's; for a submodule, the one git names: in its superproject's .git/modules when the submodule's git folder is there, as git submodule makes it now, or in the submodule's own .git folder when it isn't), which no stash, branch switch or commit takes away. So git stash -- .gitignore, or a branch without the lines, doesn't leave the file one git add -A from a commit. An install made by 3.16 to 3.19 wrote the lines into the .gitignore only: the doctor's project-mcp-token-excludes finds such a file, and its fix adds them to the excludes, unless a ! line takes the file back (SUP-410). A .gitignore line that takes the file back (one starting with !) outranks those excludes, so git is asked before the .gitignore is touched, and a name a .gitignore there takes back is refused. So is a ! line naming the file (!/.mcp.json, !.mcp.json, either with a *) in the .gitignore Supbuddy writes to, even with Supbuddy's own line from an earlier install after it, which hides it from git: a stash of that line would bring it back. So is a ! line in any other form there that takes the file, its backup or a staging copy back, such as !*.json in a .gitignore that lists what to keep (SUP-410). That .gitignore is read by git's own rules, with letter case told apart and not, and with Supbuddy's own lines set aside unless the last commit has them too; the refusal names the fewest ! lines whose removal leaves the file and its copies ignored. If the file isn't meant to be shared, remove that ! line, or narrow it so it matches none of the token file, its backup and their staging copies, commit that, and install again. A ! line in a .gitignore deeper in the folder, or one that a later commit or another branch brings, isn't seen. A repository whose git doesn't say where its excludes are is refused (not_ignored_by_git), and an excludes file that is a link, or in an info folder that leads out of the git folder, stops the install, as a .gitignore Supbuddy can't read or write safely does. A file git tracks, in any letter case, is refused, and a team's shared .mcp.json stays exactly as it is, its .gitignore too: nothing that reads it changes, and no token is written. If it isn't meant to be shared, untrack it (git rm --cached), commit that, and install again. A file in the folder of a submodule that isn't checked out is refused too, such as an empty .cursor that git tracks as a submodule, or a project's own folder after git submodule deinit: the token would be in another repository's path, which this one's .gitignore doesn't reach. A submodule that is checked out is its own repository, and the file goes there, ignored by that repository's .gitignore, as in any other. A later ! line that takes the file back, or a repository git doesn't answer for within 5 seconds, is refused too (not_ignored_by_git, with git's words, in the app's toast, in install_mcp_config's invalid_args, whose just-made client is removed, and in the CLI). For Claude Code and Cursor every such refusal names the way out: install the client for your user (Install for Claude Code in the app, --scope user, or target: "user"), which leaves the file alone. A user install doesn't touch a supbuddy entry already in that file, or its token, so the refusal says when there is one: remove it, and revoke its client (supbuddy mcp ls, then supbuddy mcp revoke <client_id>). Claude Code reads a project's entry before a user's. Outside any repository the file is written as usual. A config there that isn't a JSON object, or whose mcpServers isn't an object, is left as it is (unsupported_config). A user config keeps its token out of a dotfiles repository. A user install writes your own config (~/.claude.json, ~/.cursor/mcp.json, Claude Desktop's, Windsurf's, or Codex's config.toml), and where that file lands in a git work tree, git is asked first. That is a home folder that is a repository, or a folder linked into one, such as a stowed ~/.cursor, or a config.toml that links to a dotfiles repository's file. A file git tracks, in any letter case, or whose backup it tracks, is refused and left exactly as it is (not_ignored_by_git): untrack it (git rm --cached), commit that, and install again. A file git doesn't ignore is refused too, since a git add -A there would commit the token: ignore it, its backup and their staging names (<name>.tmp.*, <backup>.data.*), which one line such as /.claude.json* in that repository's .gitignore or .git/info/exclude does, and install again. The refusal names that line, anchored to the top of the repository git names. Supbuddy writes no ignore line there, as that repository isn't a project's. A git that doesn't answer, where a .git is at or above the folder, is refused as well, naming that .git: fix git there, or remove it if it is no repository, or paste the config into the file yourself (supbuddy mcp add <agent> --print prints it). Outside any repository the file is written as before, and git isn't asked. A bare dotfiles repository that git finds only through --git-dir or GIT_DIR (git --git-dir=$HOME/.cfg --work-tree=$HOME) has no .git to find, so Supbuddy can't ask about it: keep these files out of it yourself.

A project config goes only into a registered project. The project files (.mcp.json, .cursor/mcp.json) hold the client's token, so the app writes them only at a registered project's folder, and, as over MCP, only when the file is held to that project too: a .mcp.json or .cursor there that links into another project, out of every project or to nothing is refused before anything is written (the toast names the file). Over MCP, install_mcp_config with target: "project" (and so supbuddy mcp add <agent> --write --scope project, which sends --project's folder or your shell's) writes into a registered project's folder or a folder inside it, a nested project's as that project's. A folder outside every registered project is refused (scope_denied), and so is a link from one project's folder into another's or out of every project: register the project first, or install for the user. The file itself is held the same way: a .mcp.json, or a .cursor folder, that is a link into another project, out of every project or to nothing is refused, naming the file. No project_root at all is refused too (invalid_args). Each of these refusals comes before a client is minted. The CLI words them in its own terms and names the way out: supbuddy project add <folder>, --scope user, or --print to paste the config yourself; a --project with no absolute folder on record is refused before install_mcp_config is called.

Codex, Windsurf and Claude Desktop install for the user only. They have no project config, so a project install of one of them is refused rather than writing the user's file. install_mcp_config with target: "project" answers invalid_args ("has no project config; it installs for the user only"), before a client is minted. supbuddy mcp add <agent> --write --scope project (or --project, or --scope project with the interactive picker) is refused by the CLI before it calls install_mcp_config, naming --scope user; the picker asks for a scope only for Claude Code and Cursor. The app's Add client opened for a project (the supbuddy://mcp/setup?project=… link in a project's .supbuddy/mcp.md) installs them for your user and says so in its toast, as its Install for … button does.

Continue installs for a project only. Continue reads Supbuddy's entry from .continue/mcpServers/mcp.json at the top of your workspace (its ~/.continue/config.json is deprecated) and uses MCP servers in agent mode. Add client opened for a project (the supbuddy://mcp/setup?project=…&kind=continue link in .supbuddy/mcp.md, written when Supbuddy finds Continue) writes it there after Generate token, merging into a mcp.json that is already there (its other servers kept, a .supbuddy-backup beside it), and so do install_mcp_config with target: "project" and supbuddy mcp add continue --write --scope project (or --project). The file holds the client's token, so first Supbuddy adds /.continue/mcpServers/mcp.json* (the file, its backup and their staging names, and any copy of it), with ! lines after it for its .template, .example and .sample, to the .gitignore of the repository it lands in, as it ignores .env.supbuddy: lines of its own, outside the context sync's block, which syncing, turning the sync off and a reset leave in place. Not in a .gitignore inside .continue/mcpServers/: Continue reads that one and would skip the file. A file git already tracks is refused before that line, and so is a repository git doesn't answer for, so the .gitignore is left as it is. After the line, git is asked about the file, its backup and their staging names: where it says one is not ignored (a later ! line takes it back) or is tracked, nothing is written, and the install says why, with the git command that shows or fixes it. A git that does not answer, in a folder with a .git at or above it, refuses the install too. A user-level install is refused (invalid_args from install_mcp_config, project_config_only from the app; the CLI refuses --scope user for it before asking the daemon): Continue's user-level config is YAML (config.yaml), which Supbuddy doesn't write, and Add client shows no user-level install for it.

Agents Supbuddy writes no config for — Zed, VS Code (Copilot Chat), Cline, JetBrains AI, Goose and Custom — get their snippet and where it goes, to paste yourself. Add client opened for a project does the same after Generate token, with a notice naming the file, and asks for no install.

Codex: what Install checks. After writing the file, Supbuddy re-reads it, then asks Codex itself how it reads the entry (codex mcp get supbuddy --json, with the same CODEX_HOME).

  • Installed means Codex reports the server enabled, over HTTP, at the right URL, and sending exactly the Authorization header Supbuddy wrote.
  • Written, not confirmed means Codex couldn't be run, didn't answer in time, or gave an answer Supbuddy couldn't interpret.
  • An error names what Codex reads differently.
  • Written by an older daemon (the app or CLI is newer than the daemon that wrote the entry) is never shown as installed: update Supbuddy, then install again.

supbuddy mcp add codex --write prints the same: ✓, !, or ✗ with exit 1. Codex's output contains the token, so it is never logged or shown. The edit replaces only Supbuddy's [mcp_servers.supbuddy] tables, and the rest of the file must read back exactly as before, or nothing is written. A file that isn't TOML Supbuddy's parser can read is refused rather than guessed at, and so is a supbuddy entry written another way (a dotted or inline entry under [mcp_servers]). A symlinked config.toml (a dotfiles setup) is written through to its target.

If Codex or the ChatGPT desktop app shows no Supbuddy tools, and Codex's log says invalid_token or "Auth required", the entry probably uses headers. Codex ignores that key and reads http_headers. Supbuddy itself wrote headers up to 3.8.2. Either fix works:

  • the System Doctor check codex-mcp-header-key ("Codex can't authenticate to Supbuddy") renames just that key, via Settings → General → System health → Fix or supbuddy doctor --fix;
  • reinstalling from Settings → MCP rewrites the entry.

MCP tool surface

The MCP server has full read and write access:

  • Read tools (list_mappings, list_projects, get_health, get_compose_status, list_pending_vm_migrations, etc.), with env values and request bodies included.

  • get_client_capabilities and request_scope_elevation (scope discovery + user-approved grant).

  • read_env_file, tail_request_logs, watch_audit_log.

  • Write tools: create_mapping, delete_mapping (soft-delete), register_project, update_project, set_supabase_config_path, set_project_folder, start_proxy, start_supabase, stop_supabase, restart_supabase, switch_isolation, migrate_vm_to_thin, finish_vm_migration, start_compose, stop_compose, restart_compose, scaffold_addons, seed_addons, write_env_file, copy_env_var, write_supabase_config.

  • What a mapping or project change did not finish is on its reply. While the proxy runs, create_mapping, update_mapping, enable_mapping, disable_mapping, delete_mapping, restore_mapping, delete_project and restore_project reload Caddy and re-apply the OS resolver files before they answer. The change itself is made either way, and a step that did not land is a warning beside it, beginning with what was done (The mapping was saved, The project was deleted, The project was restored, …): caddy_reload_warning when Caddy did not reload, so it may still serve the configuration from before the change (supbuddy proxy restart applies it). When the new configuration is invalid (caddy validate refused it), it says instead that Caddy kept its previous one and that the change is to be undone or fixed: a restart would build the same configuration and leave Caddy stopped. A reload that did not answer within 15 seconds says Caddy may or may not have applied the change. A proxy that stopped or restarted during the reload gets no warning, since its next start serves the change, and resolver_warning when a resolver file could not be written. The resolver files are re-applied even when the reload failed. The project tools that reload Caddy — register_project, update_project (a change to enabled, domain or tld), enable_project and disable_project, which the CLI's project add|set|enable|disable call — carry caddy_reload_warning the same way, beginning The project was registered, saved, enabled or disabled. Their resolver outcome is said as before: resolver_note on register_project, resolver_warning or tld_resolver_warning on update_project. A change made while the proxy is starting waits for the start, up to 20 seconds, then reloads Caddy itself and says how that went, as above. A start still running after 20 seconds gets caddy_reload_warning saying so, that whether Caddy serves the change is not confirmed (the start's own reload may have read the store before it), and that a new name may not resolve yet, as its resolver file is not written then: once the proxy is up, supbuddy proxy restart applies both. A project change that could not reload Caddy (an enable of an enabled project) does not wait.

  • Compose service names: start_compose, stop_compose and restart_compose take services names in Compose's own set — letters, digits, ., _ and - — and not starting with -. Any other name is refused before Compose runs. The names reach docker compose after --, so none is read as an option.

  • Scripts tools (list_scripts, start_script, stop_script, restart_script, bookmark_script, tail_script_logs); see Scripts MCP tools below.

  • Project readiness (see Project readiness above): get_project_readiness ( { project } , scope read) reports whether each install root's dependencies are installed, whether the app's env vars are present and current, and whether a running Supabase stack listens beyond loopback. While an install for the project is running, the deps finding it will fix is left out of findings and listed in hiddenByInstall ([{ id, category, severity }], [] when nothing was hidden); ok counts it either way. It writes nothing, and the only process it runs is one netstat (macOS) or ss (Linux) read of the listening sockets while the project's stack is running, shared by every project for 2 seconds, so it is safe to poll. Every actionable finding carries a fix — { tool, args, label, command } naming a real tool call — which you pass straight to that tool: install_dependencies for a missing or stale install, apply_env for connection-env drift. Do not compose your own remedy and do not run a package-manager command directly; the descriptor already carries the right manager for that project. install_dependencies ( { project, root? } , scope projects) is destructive, so under the default client it returns a plan naming the exact argv and cwd; applying it starts a job and returns immediately with an InstallJob, never a finished install. Follow it with tail_install_log ( { job_id } , scope read), which replays what the job already printed and then streams to completion, or stop it with cancel_install ( { job_id } , scope projects). A second install_dependencies for a root that is already installing returns the same job rather than starting a duplicate. It refuses, having spawned nothing, when no lockfile or packageManager field identifies a manager and when that manager's binary isn't on Supbuddy's PATH.

  • Extended Supabase tools: init_supabase, validate_supabase_config, list_supabase_backups, restore_supabase_backup, cancel_supabase_start, restart_supabase_container, get_supabase_analytics, set_supabase_analytics. restart_supabase_container restarts one container of the project's own stack, and answers a refusal as one, before anything restarts: invalid_args for a name that is no Supabase container's, a container that doesn't exist, a project still Isolated (VM), or Supabase work already running for the project (details.supabase_busy); plan_not_found for a project being deleted; scope_denied when the container isn't shown to be this project's (a Compose label naming another stack, a config that names no project_id or that Supbuddy won't read, as a link out of the project or a FIFO). A docker restart that failed, a Docker that isn't answering, or a read of the config or a resolve of the project's folder that failed for a resource error (EIO, EMFILE) stays an internal_error, to try again.

  • Bundle (export/import a project's full config): export_bundle (out_path is an absolute folder; see A bundle export asks where to save below; background: true runs it as a job), get_bundle_export_status, import_bundle (background: true runs it as a job), get_bundle_import_status, cancel_bundle_import, validate_bundle.

  • Supbuddy Cloud (opt-in, per-project): cloud_sign_in, push_to_cloud, get_cloud_status, preview_cloud_env, cloud_teardown, plus live sync (cloud_sync_start, cloud_sync_status, cloud_sync_stop) — push a project (with its Supabase schema + data) to a hosted cloud stack and control it. The cloud link ({ projectId, stackId, pushedAt, url }) also appears on get_project / list_projects, so any client sees which projects are in the cloud. get_cloud_status also returns a box summary — what the stack's box last reported doing, as a phase plus a per-unit state list, with report_at so the caller can age it. It is deliberately structural: the box's free-text detail is NOT included, because that text is written by whatever runs inside the box and this value reaches an agent's context. Absent (null) when the stack has never reported or runs an image with no reporter.

    preview_cloud_env answers what a project's env would MEAN in a cloud box, before anything is pushed. Values are classified, never uniformly substituted — a blanket rewrite silently repoints a project at a different backend, and a blanket copy points a cloud box at a database on somebody's laptop. Each variable comes back as local (127.0.0.1, a .local host, a LAN address — meaningless inside a box), remote (correct as-is in both places), secret, or plain, each with a reason in plain words, plus needs_attention — the count of local ones, the only number that implies an action. It is read-only and changes nothing. Secret values are never returned — not masked, not truncated, omitted: a masked secret is still a decision to send it somewhere, and a preview has no use for the value. Its optional files (by default .env, .env.local and .env.development) are names of files in the project's folder. A name that is absolute, has a . or .. part, or ends in or doubles a separator is refused (invalid_args); so is one that resolves outside the folder, through a symlink that leads out or points nowhere (scope_denied). Only a regular file is read: a FIFO (1Password's .env), a socket or a device refuses the preview with the reason (invalid_args), rather than being skipped as if it were missing. So does a project whose folder is gone, instead of coming back as an empty preview. The app's Cloud preview reads its three files the same way, and the push dialog says why when it can't make the preview (it names the file); the push does not depend on it.

  • Connection / env-target workflow: preview_connection, get_env_targets, diff_env, apply_env, write_connection, test_connection, dismiss_connection_drift. apply_env is the one that connects an app: it merges into the file the framework loads (.env.local for Next/Vite/SvelteKit, .env for Astro/Nuxt/Remix — see Framework env vars), backs it up first, and clears the connection-drift warning. write_connection writes a reference <app>/.env.supbuddy that no framework auto-loads; it never satisfies the app and never clears that warning. Both compute the same values with the app's framework prefix. .env.supbuddy writes each value as Apply does, unquoted when that reads back and otherwise in a quote that holds it, so dotenv reads x # y or padded back as given. A value no line can hold (one with $, which Next and Vite expand), or one Supbuddy's own reader (read_env_file) would read differently, is left out and named in warnings; preview_connection returns the file's text as envBody, which the Connect dialog shows and copies. The env target folders these tools read are held to the project too: an app recorded in another project's folder, or outside every project (a record an earlier version made, kept until the next rescan), is listed in unreadable with the reason, and none of its files is read. So is one in the folder of a project registered inside this one, whose reason says to ask through that project: a rescan records it again. A path these tools take (file_path, target_app_path) must be where the project project_id names may act, both as it is named and by its real path when the call arrives: the project's own folder, or the folder of a registered project that contains it. Only a folder on record as an absolute path lets a path through: a path for a project an older Supbuddy registered with a relative folder is refused (choose its folder again with Select Folder in the app, or supbuddy project set-folder / MCP set_project_folder), and its relative folder keeps out what is under it but lets nothing through for any other project's call. The same holds wherever Supbuddy takes a path as inside a registered project (SUP-281): the path tools called without project_id (read_env_file, write_env_file, copy_env_var, the Next.js and Vite config fixes), the app's checks of a folder or file it is sent, the folders Supbuddy's env readers and writers hold a file to, and the app's MCP auto-install. get_env_files answers scope_denied for such a project and lists nothing (a project with no folder on record lists nothing, as before). Where a folder on record as relative would have held the path, each refusal says to choose that project's folder again: with Select Folder in the app, or supbuddy project set-folder <project> <folder> (MCP set_project_folder), which runs the same path. A request that acts in such a project's own folder is refused the same way, before anything is read, written or run there (SUP-314): Supabase Start, Stop and Restart (from the app and over MCP), init_supabase, get_supabase_details, the analytics toggle, restart_supabase_container, reading or writing its config.toml (read_supabase_config, write_supabase_config, detect_supabase_config_secrets, set_supabase_config_path, the config editor), Compose's start, stop and restart, starting or restarting a script, scaffold_addons and seed_addons, the readiness check and its installs, an isolation switch (switch_isolation), a legacy VM project's move to Thin (migrate_vm_to_thin), Connect with no target named (preview_connection, write_connection, test_connection, get_env_targets and the app's Connect panel), the cloud env preview, the push dialog's repository detection, a cloud push and starting cloud sync. MCP answers invalid_args. A cleanup of isolation leftovers still runs, by its containers, and skips its rescan of the folder; the Connect pill's drift check has nothing to tell for such a project. Stopping a script is still allowed: it names no folder. Select Folder repairs such a project whatever config sits where the relative folder resolves, which it neither reads nor changes; a Thin project chosen onto a folder whose config already carries its whole port block is recorded there, and nothing is written. Nor does anything Supbuddy runs by itself act there: the Supabase start and stop behind the enable toggle and a switch are refused, a delete's and the reset's host supabase stop is skipped and logged (the delete goes on), a Thin one's delete says its config was not read or restored, with what to set back, Compose's readers and the bundle export refuse it before reading a file, the context sync skips it, .env.supbuddy's port follow leaves it alone, the doctor lists it as could not be scanned and its token and duplicate-name checks read nothing there, and the Docker watcher ignores it. Its cloud sync sessions are not adopted after a restart, but they are held, not forgotten: its Thin block stays refused, and a delete of it ends only once a check of its stack's sessions at that folder has stopped them (run cloud_sync_stop with its id to check again). A project's folder is its path (a record from the first MCP registrations, which wrote rootPath alone, keeps that as its folder): a rootPath beside a path that an older Select Folder left on the old folder grants nothing, and is set to the project's folder when the daemon starts. On a volume that folds names (macOS's APFS by default), a path spelled in another case or Unicode form than the project's registered folder (work/app for Work/app) is that folder, as the disk says, and is held to it the same way; on one that keeps them apart it is another folder. A nested project's file is that project's: its enclosing project's call for it is refused (ask through the nested project), and so is a link from the enclosing project into it. write_connection with no target_app_path, and the app's Write .env.supbuddy, hold the app folder they derive from the project's apps to the same rule, so an app recorded outside the project's folder (before Supbuddy refused one), or in a registered project's folder that neither is the project's nor contains it, is not written into (scope_denied over MCP); a nested project's app in its enclosing project's folder is written, as a named target there is. A nested project's .env.supbuddy that lands in its enclosing project's folder (named there, or its own file linked to the enclosing project's) gets its ignore entry in that folder's .gitignore. A nested project's call for its enclosing project's file is taken, and so is its own file linking to the enclosing project's (the monorepo layout). Another project's file, a relative path, a path with a . or .. part or a trailing or doubled separator, or one through a symlink that leads out or points nowhere is refused with scope_denied, naming the tool and the field, before anything is read or written. The app's Connect panel and the readiness card's apply_env fix are held by the same rule, so an enclosing project no longer writes a nested project's env file from the app either: open the nested project for it. read_env_file, write_env_file, copy_env_var and the Next.js and Vite config fixes take an optional project_id: pass the project you are working on, and each path is held to it by the same rule; without one they take a path inside any registered project, as before.

preview_connection, diff_env and apply_env also return conflicts: values Supbuddy left alone rather than replaced. Today that means a NODE_EXTRA_CA_CERTS it didn't write, or can't read with certainty, in the target or in the .env, .env.local, .env.development or .env.development.local beside it.

  • Each entry has key, filePath (the file holding it), targetPath, reason (foreign, unrecognised or unreadable), foreignValue, 1-based lines, supbuddyValue, supbuddyLineInEffect and a one-line message.
  • supbuddyLineInEffect is { filePath, line, value } only within one file: when that file's last assignment is Supbuddy's own, so it is the value the file puts in effect. It is never set across files; a Supbuddy line in another file is named in message. Otherwise it is null.
  • apply_env decides from the files as they are, so it needs no diff_env first. It returns { filePath, bytes, changed, conflicts, warnings, backupPath? }: changed is false when there was nothing to write, warnings are the review's (a cloud URL replaced, a key left out), and backupPath is where the original was copied.
  • A conflict is not an error and never connection drift. Show its message; don't overwrite the value.
  • The CLI prints each one as a ! <message> line, with control characters escaped, after supbuddy connect preview|diff|apply and supbuddy ready --fix. --json keeps the array (on the applied entry for ready --fix).
  • Host & network tools: bundled-runtime trust (get_trust_status, install_trust, remove_trust, detect_trust_tools, test_trust), Tailscale (get_tailscale_status, set_tailscale_key, remove_tailscale_key, test_tailscale), DNS (get_dns_status), CA (get_ca_status, install_ca, uninstall_ca — see below), and port-forwarding (get_port_forwarding_status, set_port_forwarding, reload_port_forwarding). Two port-forwarding fields mean different things and are reported separately: enabled is what you asked for, enforced is whether the 443 → 8443 redirect is actually live — probed, not remembered. enforced is null whenever the probe would be meaningless — the proxy is stopped, or nothing is listening on the HTTPS port — and null means unknown, never a fault: it raises no finding, no degraded flag and no password prompt. get_proxy_status and get_health both carry the same distinction as portForwardingEnabled and portForwardingEnforced, and report networkingDegraded: true when the two disagree, because a redirect that is switched on and not working is an outage rather than a setting. The live probe is decisive in both directions: it overrides a stored flag that claims health, and it also clears one left behind by an abandoned repair once the redirect is confirmed working. reload_port_forwarding re-applies the rules with a sudo prompt and returns ok only once a fresh probe confirms 443 answers — a successful pfctl and a working redirect are not the same claim. set_port_forwarding deliberately returns no ok field at all: the elevation runs on the host and resolves after the tool has already replied, so it reports requested plus confirmed: false and points you at get_port_forwarding_status. It can still fail afterwards — a declined prompt, a timeout, or a ruleset that fails validation — and a success token there would be a guess, not an observation.
  • tail_service_logs: streams a Compose/add-on service's container logs over SSE (like tail_request_logs but for container stdout/stderr).
  • watch_supabase: streams a project's live Supabase start/stop/restart progress over SSE: operation status, image-pull/service snapshots, and (for VM projects) raw log lines. Backs supbuddy supabase start --follow.
  • Local HTTPS CA (system trust, what browsers use): get_ca_status (scope read) returns { installed, certPath, expiresAt, trustUnknown? }. It never changes the system; it may record what it learned (the last root this Mac was seen trusting). On macOS installed: true means the current root is in the System or login keychain and security verify-cert passes. certPath: null means there is no readable root: Caddy hasn't minted one yet, or the status couldn't be read — start the proxy first; if it stays null while the proxy runs, run doctor, which names the root's path and why it can't be read. Don't call install_ca, which has nothing to install. The status says which it is: noRoot is { path, cause: "not-minted" } before Caddy has written a root, or { path, cause: "unreadable", error }. A certPath with expiresAt: null is a root that couldn't be read: install_ca refuses it, and doctor's ca-not-trusted finding says how to recover (Caddy keeps a root that exists, so move its folder aside, then restart the proxy). trustUnknown: true means the trust store couldn't be read, so installed: false is unknown, not absent. On Linux, removalUnfinished ({ copies, anchors? }, with trustUnknown) means a CA removal was stopped (or is still running) before a store was rebuilt without it: its CA file is not in place, but that store may still trust it, and copies are the files the removal moved aside. anchors are the CA files still there, each caddy-root.crt in a store that has one, which uninstall_ca takes as well, by their name. With both stores on one machine, it can come beside installed: true, without trustUnknown: the store read trusts the root, and the other store's removal did not finish (SUP-353); uninstall_ca takes the CA from both, so call install_ca after it to keep trusting it. Call uninstall_ca again to finish it, then install_ca if you want to keep trusting it: Install writes only the store Supbuddy installs to, which may not be the one whose removal did not finish (SUP-353). It can come with no readable root (certPath: null with noRoot, or expiresAt: null): uninstall_ca needs no root, and there is nothing to install then. On macOS, rootChanged ({ currentRootSha256, lastTrustedRootSha256, lastTrustedAt? }; lastTrustedAt is absent when its saved time was not kept) with remediation ({ requires: "screen-session", steps }) means the root is not the one this Mac trusted before: Caddy made a new one, and trusting it needs someone at the Mac's screen. It is never set on a first install or with trustUnknown. install_ca (scope system, confirm-gated) runs the same installer as Settings → General → CA Certificate → Install and the ca-not-trusted doctor fix. It waits for macOS's dialogs before it answers, which can take minutes. One install runs at a time: a call made during another joins it. If your call times out, check get_ca_status instead of calling it again. It returns { success, message?, error?, needsManual?, elevationKind?, trustDialog? }; on needsManual: true, error says why and message holds the steps to finish by hand — show them verbatim. trustDialog (unavailable or timeout) says the macOS 15+ login-keychain dialog reached nobody: macOS could not show it (as from SSH), or nobody answered. When the root changed and the admin prompt or that dialog reached nobody, the result also carries remediation, the screen-session steps. A doctor finding can carry the same remediation. If HTTPS for a Supbuddy domain is untrusted, call install_ca, or ask the user to click Install there; never run security add-trusted-cert or sudo yourself. get_trust_status is bundled-runtime trust (NODE_EXTRA_CA_CERTS for tools with their own JS runtime), not the system CA.
  • System doctor: doctor (scope read) runs the health & drift scan and returns a report of findings (each with a checkId, severity, evidence, and whether it's fixable). It never repairs or changes the system; it may record what it learned about the CA (the last root this Mac was seen trusting). doctor_fix ( { check_ids: [...] } ) applies the opt-in repairs for those checks; it's system-scoped and confirm-gated (a modal, exactly like uninstall_ca), so a read-scoped client can't trigger a fix and an agent can't silently run a destructive repair. Each entry in its applied list is { label, ok, error?, elevationKind?, manualSteps? }; manualSteps, when present, is what the user must do by hand to finish that repair (the CA install on macOS 15+ when its dialog was dismissed) — show it verbatim. elevationKind is set only when the repair's admin password prompt is what failed, and says which way: refused, unavailable (no prompt could be shown), timeout or detached (the prompt may still be open), or failed (the privileged command failed: it ran and did not succeed, could not be started, or could not be sent to the host that runs it). A failure with no elevationKind was not a password prompt. Backs supbuddy doctor / doctor --fix (see System doctor). forget_failed_import ( { token, preview?: true } , scope system) frees the folder a failed bundle import keeps, removing nothing: use it only when what the import left can never be proven gone, so doctor_fix with failed-import-leftovers cannot finish (see System doctor). With preview: true it answers { token, name, root, may_remain } — what may still be left, and where — and changes and asks nothing; without it, a person must approve a confirmation that says the same. doctor_fix never forgets a record. forget_sync_check ( { project_id, preview?: true } , scope system) forgets the cloud sync checks owed for a deleted project, and those its delete waits on, stopping and removing nothing: use it only when the file synchroniser will never answer and you know that sync is gone (see Live sync). Its answer lists them as checks and waits, and a release waiting on one tries again at once and ends that wait. With preview: true it answers { project_id, checks: [{ stack_id, folder, session_name }], waits: [{ stack_id, folder, session_name, reason, holds }], says } and changes and asks nothing; without it, a person must approve a confirmation that says the same. doctor_fix never does this. confirm_folder_quiet ( { id, preview?: true } , scope system) frees a folder Supbuddy holds because it stopped before its work there was confirmed stopped (see A folder belongs to one project), once the user says nothing of it runs there any more: it stops nothing. With preview: true it answers { id, name, root, kind, since, held_since, says } and changes and asks nothing; without it, a person must approve a confirmation that says the same.
  • System reset: system_wipe ( { tier: "soft" | "deep" } , scope system) runs the tiered reset described under System reset. It is gated twice: it always returns a plan first — even for auto_apply clients — whose side_effects are the literal manifest the wipe will execute, and the subsequent apply still blocks on a user confirmation modal. The applied result's applied entries carry the same optional elevationKind as doctor_fix's. tier: "full" is rejected: it deletes the credentials the caller is authenticating with, and its final steps (uninstalling the service, removing the app-data directory) can't run inside the daemon — run supbuddy reset --tier=full in a terminal instead.
  • Multiple MCP clients can connect simultaneously. The same MCP-HTTP surface backs the headless CLI (see Command-line interface below).

Scopes: discovery & self-service elevation

Each MCP client holds a set of scopes (read, log_tail, mappings, projects, services, config, system, apply) chosen when it's added. A tool call that needs a scope the client lacks fails with scope_denied, whose payload now carries a user_message and details.remediation pointing at the fix.

  • get_client_capabilities ( { tool? } ) returns the calling client's granted_scopes and available_scopes. Pass a tool name to get { required_scope, required_feature, can_call, reason? } so an agent can pre-flight a call instead of probing by hitting scope_denied.
  • request_scope_elevation ( { scopes: [...] } ) asks the user to grant the named scopes. Supbuddy shows a blocking approval dialog; on approval the scopes are added to the client. Already-granted scopes short-circuit without a prompt.

You can also review and edit any client's scopes from the GUI: Settings → MCP → Clients lists each client's granted scopes inline and exposes a Scopes button that opens the same scope editor used when adding a client.

Registering a project via MCP

register_project takes a root_path (required, and absolute: a relative one is refused, since the daemon's working directory is not the caller's), an optional label, auto_scan (default true), an optional isolation ('thin' or 'host'), and confirmPublicTld: true when a tld that is a real public suffix other than your default TLD was confirmed by the user (see Custom domains & TLDs). It registers the project the same way the GUI's "Add project" flow does:

  • Derives a base domain as <slug>.<defaultTld> from the label (or the folder name), e.g. staffhub.test. A slug over 63 characters, the most a DNS name allows between dots, is shortened to 63: its first 54 characters, - and 8 characters of a hash of the whole slug, so two long folders that start alike still get different domains. The project's name stays the label as given. The Add Project dialog suggests the same shortened domain. Registering a folder whose domain another project already has (two folders with the same name) answers domain_taken_warning, naming that project. A tld is one DNS label of at most 63 characters.
  • Records both the project path and rootPath so the project is visible to the proxy, scans, and file tools alike.
  • Scans the folder (unless auto_scan: false) for apps, services, scripts, and package manager.
  • Creates per-app subdomain mappings from the discovered apps (e.g. site.staffhub.test → :3400) and derives the host service subdomains (api., studio., …). Caddy reloads once the isolation switch is done. Each derived subdomain is shortened the same way to fit the DNS limits (63 characters between dots, 253 in all) under the project's domain; a mapping is not made when nothing fits (a domain of 252 characters or more), and an auto mapping already over the limits goes at the next refresh. The project and the names it derives are judged where Supbuddy puts them when it next starts, on the default TLD as it is when the registration is written (it may have changed during the scan): a name over the DNS limits there refuses the registration (invalid_args, details.name_too_long; registered again, its names are derived on the new default), and a derived mapping another mapping would share a name with there is not made, as one on a name already mapped is not; a refresh of the project's service mappings (its Thin switch, a Supabase start, stop or init, a rescan) leaves it out too. Each name left out this way is logged, with the mapping in its way: <name> is not mapped: when Supbuddy next starts it would be <name>, and so would <other mapping> (…), or, for a name another mapping already has, <name> is not mapped: <other mapping> (…) has that name. With a tld of its own, a manual mapping on the default under its stem that it would pull onto its TLD (see Per-project TLD) is judged too: over the limits, or onto another mapping's name (details.mapping_collision), it refuses the registration. The app's Add Project dialog suggests the same names for a folder's apps, by the same rule (a second app of one name gets -2), and fits them again when you change the base domain; a subdomain you typed there is kept as typed. When none fits under the base domain, the dialog says so, rather than that the folder has no apps. A rescan follows an app's new port to its mapping: the one app mapping with the app's name (as the apps before the scan named it, or its whole name) that is still on the port the previous scan found for it. A mapping whose port you set by hand, or that another app's name moved onto, is left as it is. A mapping that registration or the app's Add Project dialog made for an app records that app (its package name and folder, app on the mapping) and is found by it instead: two apps whose names collapse to one (web, web-2) are followed through a reorder, and no other app's name takes it. A mapping made before this, a manual one and a service's have no record and keep the rule above. A record is kept only as the scan writes it: one that names no app of the project's scan, or is not a name and an absolute folder, is not kept, and the mapping keeps the rule above. A Compose service whose name makes no domain name (.web, -web) gets no mapping, and two services whose names differ only in case get two names (web, WEB-2).
  • Defaults to thin isolation: the project gets its own loopback IP so its dev servers keep canonical ports (:3000) with no cross-project collisions — run them with supbuddy run -- <dev command>. Registration prepares the project's Supabase port block but does not start Supabase.

A project lands on host in exactly three cases:

  1. You passed isolation: 'host', or Settings → Default isolation is host. (isolation: 'thin' forces thin and skips the detection below.)
  2. The project's Supabase stack is already running on the host outside Supbuddy — switching would rewrite its config.toml ports and orphan that stack, so registration keeps it on host. A config with no project_id is looked for under the real name of the folder holding supabase/ (a link resolved, the case as on disk), the id the Supabase CLI runs it as. The response carries requires_user_action: run supabase stop in the project's Supabase folder first, then the retry. Its cause names the project_id of the stack it found running.
  3. Thin was attempted and failed: the administrator prompt for the project's 127.0.0.N loopback alias was declined, no loopback IP was free (127.0.0.2–254 all taken), or the switch failed for another reason. The project is left on host with isolationError set, and the response carries requires_user_action with the cause and the exact retry (switch_isolation { project_id, target_mode: 'thin' }). A switch refused because another project runs the stack its config names carries no retry: it would be refused again while that stack runs (see A switch to Thin is refused while another project runs the stack its config names).

Cases 2 and 3 are fallbacks, not deliberate outcomes: retry with switch_isolation { target_mode: 'thin' } and then apply the plan that stages (see Plan / apply for destructive tools). Case 1 carries no requires_user_action: Host is what was asked for.

requires_user_action is { reason, cause, retry?, command? }. It is present whenever registration ends on host as a fallback, or Thin with the project's loopback alias not confirmed on lo0, and absent otherwise. retry is the tool call to make (switch_isolation); command is a terminal command (supbuddy run -- <dev command>) for the alias case, which has no project-scoped retry. It is built from the project's record as registration leaves it, with the alias state read fresh from lo0, not from what the switch reported. So an alias that landed after a slow prompt asks for nothing, and one that cannot be read asks for the fix, with the cause "could not be checked". When someone else asks for an isolation while the registration runs (a switch_isolation, or update_project { patch: { isolation } }), that request wins. After a Host request there is no Thin retry or alias command, and registration does not switch at all if the request came before its own switch. After a Thin request, the response says that switch is in progress, or quotes its error with the retry. A Thin project with no loopback IP gets the switch retry, which assigns one. Registering a folder that is already registered returns the project as it is, with the alias action when it is Thin with its alias down. A project deleted while it was being registered returns its last record, a note saying so, and no __reversible_via.

When the alias prompt cannot complete, the project stays Thin (macOS). If no app is attached to show the prompt (and there is no terminal to ask in), the prompt goes unanswered, or the alias command fails, the project is registered Thin and isolation_note says the alias is not on lo0 yet, so its dev servers cannot bind until it is. requires_user_action carries the deferral's kind and error as its cause, supbuddy run -- <dev command> as its command, and names doctor_fix { check_ids: ["missing-thin-aliases"] } as the MCP route. It is added at the app's next administrator prompt — automatically once an app attaches, when no prompt was ever shown; otherwise the next time the app starts the proxy, or when you press Retry — or by supbuddy run in a terminal, or supbuddy doctor --fix (missing-thin-aliases). supbuddy proxy start and MCP start_proxy do not add it: they start Caddy and the DNS server without the privileged setup. Wait for loopbackAliasUp: true in get_project.

Whenever the alias prompt did not succeed, registration asks for no second password: the project's resolver file is left for the same next prompt, resolver_note says so, and its domains resolve once that prompt has written it.

The response includes an isolation_note explaining which mode was chosen and why — agents should read it instead of assuming.

Switching isolation over MCP

switch_isolation ( { project_id, target_mode: 'host' | 'thin', auto_start? } ) moves an existing project between host and thin mode. It is a destructive tool, so unless the client has auto-apply it stages a plan rather than switching — call apply with the plan_id to execute it (see Plan / apply for destructive tools). Execution then runs in the background and returns { started: true }. Poll get_project until switchInFlight clears, then read isolation (and loopbackIp and loopbackAliasUp for thin) and isolationError: the mode is committed before the switch is over (it then prepares or starts Supabase and may defer the alias), so reaching the target isolation alone does not mean it finished. Switches run one at a time, and each decides what it does only once its turn comes, so a call is never answered from a state another switch was about to change. When another switch still holds the queue — an open alias prompt can hold it for minutes — the call returns { started: true, queued: true } and runs next. To-thin, for a project with a Supabase config, asks its running stack to stop, writes the per-project port block and project_id into supabase/config.toml, and starts Supabase only with auto_start: true — MCP's default is false, and Thin now honours it. To-host, for a stack Supbuddy manages, asks it to stop and restores the original config.toml. A legacy VM project's move to host migrates it: it copies the VM's data unless skip_data is set (best effort, into the host's volumes), stops — without removing — its container, and starts Supabase on the host whenever its root holds a Supabase project; auto_start does not apply there. The project then stays on host across restarts, and the stopped container keeps its data until the project is deleted (see Legacy VM projects below). A staged plan describes the project as it was when staged: applied after the project's mode, the switch ahead of it, its managed stack or its folder changed, it is refused as plan_stale — preview again. A declined alias prompt fails the switch (isolationError says so); one that could not be shown, went unanswered or failed leaves the project Thin with loopbackAliasUp: false, and the alias is added at the next administrator prompt.

What get_project shows about switches. Two fields cover this:

  • switchInFlight ({ targetMode }) is set while any switch for the project is queued or running, whoever asked for it. It is read live and never stored.
  • lastSwitch records how the last switch the desktop app asked for ended: { ok, noOp?, pending?, aliasDeferred?, error?, at }.

Reaching the target isolation does not mean a switch has finished. The switch commits the mode early, then prepares Supabase (starting it only with auto_start: true) and may defer the alias. While switchInFlight is set, delete_project (and the app's Delete) is refused, so a project is never deleted in the middle of its switch.

Legacy VM projects. A switch to Host migrates the project: it starts the VM's container first if it is stopped, so its data can be read. It keeps the VM's container, stopped, with its data, and the project stays on Host across restarts. A move that does not complete leaves the project on VM, its container and data as they were — even for a project renamed since its container was made — so you can switch again or migrate it to Thin; only when its container no longer exists does it land on Host (a data volume left without its container then stays with the project, removed when the project is deleted). The Supabase tab's Clean up leftovers… lists that container, so you can remove it once you no longer need the copy; deleting the project removes it and its data volume. To get to Thin, use migrate_vm_to_thin, which keeps its data; a switch to Thin is refused and points there. The two migrations never run at the same time on one project.

Getting a lost alias back. On a project that is already Thin but whose alias is down (or whose lo0 cannot be read), switch_isolation { target_mode: 'thin' } no longer answers no-op. It returns { started: true, pending: 'loopback_alias' } at once and records the alias for Supbuddy's repair. Unless an earlier prompt for it may still be open — one that timed out, or whose app went away — an attached app adds it with one prompt straight away while the proxy is running; otherwise it is added the next time the app starts the proxy, or on Retry. Poll for loopbackAliasUp: true, or run supbuddy run in a terminal, which adds it directly.

A project can also be patched with update_project: its patch accepts name, enabled, domain, tld and isolation (it intentionally does not accept path/rootPath). A new domain takes the project's mappings with it, as Edit project in the app does: each mapping of the project on the old domain or under it is renamed onto the new one (web.acme.test → web.other.test), and onto the new TLD too when tld changes in the same patch (--domain=other.portal --tld=portal in the CLI's project set ends on web.other.portal). A manual mapping, one that belongs to no project, is not renamed with it, though a TLD change still moves the manual mappings under the project's new domain onto the new TLD. Names are matched without regard to case; the part of a mapping's name before the project's domain keeps its case. An edit that would make two mappings share a name they did not share before (compared without regard to case) is refused before anything changes, and the refusal names the mapping in the way; two mappings that already shared one are left as they are. That holds where Supbuddy puts the names when it next starts too: a domain sent without a TLD moves onto the project's TLD then, with the mappings under it. So is an edit that would write a name over the DNS limits (63 characters between dots, 253 in all): a domain put on a long TLD, or a mapping moved under a long new domain or onto a long TLD. The refusal names it (details.name_too_long: { name, would_become } over MCP; Edit project in the app answers Project not changed). A domain sent without a TLD is judged on the project's TLD too, where Supbuddy puts it when it next starts (the refusal says so), and so is a manual mapping that the next start moves because of the edit. A mapping neither the edit nor the next start moves is not checked, and a name already over a limit that the edit leaves no longer is not refused. A rename needs a resolver file for the new name: if that step fails (a declined password prompt), the reply carries resolver_warning (tld_resolver_warning when the domain moved onto another TLD). The reverse update_project returns (__reversible_via) restores the project's fields and moves its own mappings back. What it cannot put back is named in reverse_leaves: mappings, each manual mapping the TLD step moved that the reverse cannot put back ({ id, domain, was }; move it back with update_mapping): one under the project's new name, which the reverse leaves on the new TLD, or one that was on another TLD than the project's (y.acme.com under acme.test), which the reverse puts on the project's old TLD; and isolation, the mode before a flip to host (thin, or a legacy vm), which a reverse never carries (back to Thin is switch_isolation; a legacy VM project has no way back). A flip to host alone has no reverse (null). update_mapping's reverse is the keys the call changed, at their values before (https, which is not stored, reverses to true when the mapping had none). A domain or tld that moves the project onto a real public suffix not already in effect needs confirmPublicTld: true beside id and patch. Note that patching isolation only flips the flag; use switch_isolation to actually provision/tear down the port assignment. The flip is refused (invalid_args) while an isolation switch is in progress for the project — the switch would overwrite it — and while another Supabase operation runs for it (details.supabase_busy names it).

Legacy VM migration over MCP

For projects still on the retired Isolated (VM) mode, three tools handle the one-way migration to Thin:

  • list_pending_vm_migrations (read): lists all projects still on the legacy VM mode, with their current vmState and migration readiness.
  • migrate_vm_to_thin ( { project_id } ) (write): starts the guided data-safe migration. It dumps Postgres data from the VM, starts a fresh Thin stack, restores the dump, and row-count-verifies before signalling completion. Returns { started: true }; poll get_project (migrationState) for progress.
  • finish_vm_migration ( { project_id } ) (write): tears down the old VM container after verification passes. Errors if called before the verify step completes.

Repointing a project's Supabase config

set_supabase_config_path ( { project_id, supabase_path } ) switches which supabase/config.toml a project uses, for monorepos that carry more than one (e.g. a repo-root config and an app-level one). supabase_path is the project-relative directory containing the supabase/ folder ("." for the repo root, e.g. "apps/getnightowls"). It persists the path, re-derives supabaseProjectId from the new config, and re-scans services. For a Thin project it also writes that project's port block into the newly pointed config, in the same step as the change (reported under thin_supabase_block), since the file it points at declares the stock ports; if the block cannot be written, nothing changes. It takes the project's turn: refused while another Supabase operation runs for the project (invalid_args, details.supabase_busy), and refused (invalid_args) when the project's current config is still converted for Thin — switch the project to Host first (that stops its stack and restores the config), change the path, then switch back — when that config cannot be read, when the new config already names the project's managed project_id (left converted by an earlier change: set its project_id and ports back by hand), or when the project changed while the tool ran. A project deleted meanwhile answers plan_not_found. The app's Edit project (a new Supabase path) and Select folder (a new folder) follow the same rules. A Supabase path picked in Edit project is relative to the project's folder when it was picked: if the project moved to another folder since (the CLI or MCP can move it while the dialog is open), saving it is refused, its Supabase path <path> was picked in <old folder>, and the project's folder is now <new folder>: pick the Supabase path again, and nothing in that edit is saved. The previous stack's Docker volume is left intact (not deleted), so the switch is reversible; the response reports it under orphaned_previous_stack. The path must be relative with no .. (an absolute path or ../x is refused with scope_denied), and the config it names must be the project's own: not inside another registered project's folder nested in this one (or reached through a symlink), and not outside the project's folder.

set_project_folder ( { project_id, folder } ) chooses a project's folder again: it is the app's Select Folder, run through the same checks, the same ownership rules and the same move. In the CLI it is supbuddy project set-folder <project> <folder>, with <folder> resolved against your working folder. folder must be an absolute path to an existing folder, never the filesystem root, by any spelling (invalid_args otherwise, as register_project holds a root); the same folder again is a rescan. Use it for a project whose folder is on record as a relative path (a record from before 3.8.0, which every request refuses until its folder is chosen again), for a legacy record with no folder of its own (only a rootPath), or to move a project. A folder that is another project's is refused, scope_denied; so is one another project names by its rootPath alone. For a Thin project, its port block is written into the new folder's supabase/config.toml in the same step, when there is one; refused, invalid_args, while Supabase work runs for the project, or when that config already names the project's managed project_id. The old folder's config, for a project whose folder was on record as relative, is never read or written. Supbuddy's own work for the project in the old folder (dev servers, installs, Compose, seeds, cloud sync) is stopped, and the old folder freed once it has, as for any move. It is a destructive tool: without auto_apply it stages a plan, after the same checks, so a call that would be refused is refused at once. Its preview says what the apply will do, and offers no reversal. The plan goes plan_stale if the project's folder, Supabase path or mode changes, or the folder named resolves elsewhere, before it is applied. Nothing repairs a record unless you ask: registering the folder again returns the project as it is.

A folder belongs to one project. Supbuddy refuses to give a folder, or a project's Supabase config, a second owner. Registering a folder (register_project, the app's Add Project and Select Folder, bundle import) is refused, naming the owner, when the folder is already another project's — a live one, one in the trash (restore it, or empty it from the trash), or one still being released after a delete, a trash expiry or a move to another folder (the message names what it is waiting for; try again when that has finished). Folders are compared as the file system sees them: a trailing slash, .. or a symlink to the folder is the same folder, and so are names that differ only by letter case. Moving a project with Select Folder to a folder whose name differs from its current one only by letter case or Unicode normalization, and which is a different folder (on a case-sensitive volume), is refused, with the advice to rename one of the two folders; on a volume where the two names are one folder, it is no move at all. So is a move between two paths that name the same folder one way and different folders the other way (through a .. after a symlink): choose the folder by a path with no .. in it. Registering a project's own folder again over MCP returns that project. A folder a legacy record names by its rootPath alone (it has no folder of its own) is that record's: Select Folder, Add Project, set_project_folder, register_project, supbuddy project add and a bundle import refuse it for any other project, live or in the trash. Registering or importing there names the record and how to give it the folder (invalid_args, with details.root_path_owner, holding the set_project_folder call that does it, or restore_project for a record in the trash; for import_bundle, at its plan too): supbuddy project set-folder <id> <folder>. Nothing gives such a record its folder unless someone asks. A sub-project inside a monorepo is fine; what is refused is a folder that would take over another project's supabase/ (its config.toml, backups or config.hosted.toml) — for example a sub-project registered at the folder a monorepo project's Supabase lives in. The same rule applies when a project's Supabase path changes (set_supabase_config_path, the app's Edit Project, whose Supabase path must also be relative with no ..) and to restore_project, which refuses a project whose folder was registered again since. A deleted project's folder stays reserved until its cleanup has finished — across a restart too: a delete (or a trash expiry) is saved as pending, with the project as last committed, before anything is torn down, until its cleanup has finished, and a daemon stopped in the middle of one finishes it at its next start, holding the folder meanwhile. That includes the project's cloud sync session for the folder: the next start finds it under the project's sync name, at that folder only, and stops it before the folder is freed. A delete answers once that is saved; if the save fails, or is not confirmed within 30 seconds, it says <name> was deleted, but Supbuddy could not save that, or confirm it was saved, the runtime cleanup (stack, config block, volumes, containers) and the folder wait until a save lands (tried again every minute) — the folder's dev scripts and installs are stopped and the project's agent-context references released either way — and a stop before then brings the project back, unless a save already under way or waiting had finished: then the cleanup runs at the next start. A cleanup resumed at the next start that needs Docker waits for it, up to five minutes; still down, the folder is freed and the cleanup kept for the start after. A folder a release was leaving when Supbuddy stopped, before the work Supbuddy ran there for the project (its dev servers, installs, Compose starts and seeds) was confirmed stopped — a delete, a trash expiry, a move with Select Folder, or the system wipe — is held at the next start until you confirm nothing of it runs there any more: registering it, or moving a project onto it, is refused with what to do, doctor lists it at once (folders-still-releasing, as a warning), a moved project's card shows Its old folder is still held, and supbuddy doctor --confirm-quiet=<id> (MCP confirm_folder_quiet) shows the folder and why, asks, and frees it. In the app, Confirm quiet… does the same: in the card's issues list beside Its old folder is still held, and under the folders-still-releasing finding in System health for every such folder (a deleted or expired project's, or the wipe's, is on no card). It shows the folder and what its hold says, and only It is quiet: release the folder releases it; System health then scans again. If the app stops waiting for the answer, it says the folder may not have been freed: check System health, which scans again too. A folder can be held a second way too (a resumed delete's cleanup or its sync check), which System health still lists after. Nothing is stopped for you: a process group number can be reused, so one recorded before the stop could be another program's by then. A delete's folder counts as being released until its runtime cleanup has finished too (a Host stack's supabase stop, often 10–30 seconds), so quitting or updating the app during that cleanup leaves the folder held at the next start: confirm it there with supbuddy doctor --confirm-quiet=<id> or MCP confirm_folder_quiet, once nothing of the project runs in it. A cleanup waiting for a project's folder that isn't answering lasts as long as any project's folder doesn't answer, so quitting or updating the app meanwhile holds the deleted project's folder at the next start the same way, and the delete resumed there waits again, as the start resumes it only once every project's folder answers. A folder a registered project has since is not held. Registering a subfolder of a held folder as a project is allowed, and that project's own writes there pass; the rest of the held folder stays held. state.json is written through a temporary file renamed over it, so a crash mid-save leaves the previous file. A pending delete that overlaps a project registered or restored since (the same id, folder, Supabase config, a hard link to it included, or VM container, a config that can't be read, or a stack the other only holds the volumes of) is dropped instead of finished, and what it left is what Doctor lists. A Thin project's block it leaves in its config is said in the daemon log, with the values to set back, and doctor's note lists it, as for any restore given up, on the terms below: not when a project of that id is registered or in the trash again, whose block it is then, nor when the config carries another project's block. One that shares only a stack with such a project — a stack that project runs as Thin, or that its own config names — is finished as the delete itself ran beside it: what that project uses is left to it, and the rest of the cleanup runs (a delete with keep data that overlaps anything is still dropped). So does a Thin project's loopback IP while the project is in the trash or still being deleted: a switch to Thin never hands it to another project. A project restored with restore_project whose IP another project took before this rule (an earlier version did not keep it) is restored on a fresh IP if it is Thin, its app mappings pointed there, its alias added as for any Thin project whose alias is down; a Host project drops the IP it kept for reuse; with no IP free, the restore is refused. Projects that already shared a folder before this check are left as they are; a change that adds a conflict is refused, one that leaves theirs as it was is not.

A folder whose Supabase config names another project's stack is taken, and you are told. Folders and config files have one owner; a project_id doesn't have to. Two checkouts of one repository sharing a project_id are a real setup, so choosing or registering such a folder goes ahead (Select Folder, Add Project, set_project_folder, supbuddy project set-folder, register_project, supbuddy project add), and the reply says which other project and which stack: a warning in the app, a ! line in the CLI, and over MCP shared_stack_warning with shared_stack ({ config, project_id, runs_as, shared_with: [{ id, name, state, relation }], unreadable? }). A set_project_folder plan says it too before you approve, and goes stale when what it said changes. A Supabase path whose config names such a stack goes ahead and is said the same way, in the reply: Edit Project's, set_supabase_config_path and supbuddy project set-supabase-path. It counts live projects, those in the trash and those being deleted, and compares ids as the Supabase CLI runs them, so an id over 40 characters is compared by its first 40. What it says depends on what the other project runs now (relation). runs: both projects act on one stack and its data, so a Supabase stop for either stops it; a switch to Thin, which stops what the config names first, is refused while that stack runs (below). original: a Thin project on an id of its own keeps this one as its original, so a stop here doesn't reach it, but a project on this id starts on any data left under it, and if that project switches back to Host, both act on one stack. data: the id is on its record, so Docker may hold its data under it. A Compose project of that name is not this stack, and isn't named. A Thin project that takes such a folder runs under an id of its own, and keeps that id as its original; a switch back to Host puts it back in the config, so give the config another project_id after that switch if it isn't meant to be shared. Add Project, whose default is Thin, says this before its switch, including that the switch is refused while the other project's stack is running, and the project is then added on Host. A default register_project while that stack runs stays on Host, says not to stop it, names who it is or may be, and offers no ready-made retry, since a switch to Thin stops what the config names first. A Thin move is refused while a stack runs under that id, and, for a project that has been Thin before, when Docker holds anything under it. A refusal offers supabase stop --no-backup only when nothing else has a claim on that id: no project runs it, keeps it, has it on record or names it as a Compose project, no pending release's record does, no Keep data delete kept it, and nothing that would say so is unreadable. Otherwise it says who, or that it can't be told, and to give this config its own project_id. A config Supbuddy can't read is said as one whose stack can't be told, not refused for that (a move's own read of the new config still refuses it). Another project whose files can't be read is listed in shared_stack.unreadable alone.

A switch to Thin is refused while another project runs the stack its config names. A switch to Thin stops the stack the project's config names first, so it can convert the config under it, and that stop would stop the other project's stack too. So the app's switch and its Add Project, switch_isolation, supbuddy isolation switch, and register_project or supbuddy project add with Thin are refused while that stack is running, before anything changes: no loopback IP, no administrator prompt, and the project stays on Host. A project already Thin whose config still names that stack keeps its config as it is. The refusal names the other project and says how on: stop that stack first (supabase stop --project-id <id> keeps its data, and stops it for them too), or give this config a project_id of its own, then switch again; or keep the project on Host. Add Project still adds the project, on Host. Over MCP the refusal answers scope_denied. When the stack is a running bundle import's, the way on is to wait for it to finish; a failed import's leftovers are cleared by supbuddy doctor --fix --only=failed-import-leftovers. If another project begins running that stack after the switch's own check, the Supabase step itself refuses: the project is Thin with its config as it was and nothing stopped, and its Supabase error says why (a preparation, or a start with auto_start). It counts a project that runs that stack now, as a delete's own stop counts it: live, in the trash, being deleted, or on record by its rootPath alone. Another project whose config can't be read, a bundle import running as that stack, or a check that fails refuses it too, since whose the stack is can't be told. A project that only keeps that id as its original, or has it on record, runs another stack, and doesn't refuse it; nor does a Keep data delete, as a stop keeps every volume. With that stack stopped, the switch goes ahead. A legacy VM project's move to Thin is refused the same way, and so is its retry while anything else has a claim on the stale Thin stack it would remove, since that removes the stack's volumes. A switch_isolation plan names the other project, and goes stale when that changes.

A delete that leaves two mappings on one name says so. A project with a TLD of its own moves the manual mappings under its domain onto that TLD at each start; once it is deleted they stay where they are, and one may have another mapping's name there. The delete goes ahead and its answer names both mappings and the name they would share at the next start: a warning in the app, mapping_collision_warning from delete_project over MCP (and in the result of a staged plan applied from the Activity panel), which supbuddy project rm prints. The doctor's duplicate-names reports it until one is renamed or removed.

What a delete removes is what the project has when its cleanup starts. An operation already running for a project when it is deleted — a rename after a name change, a legacy VM project's move to Thin, a Thin block written into a new config — finishes first, and what it set up is recorded on the deleted project, so the cleanup removes the stack that is really there (a rename's new stack and its data volumes, not the old ones). The cleanup removes every stack the project has: a legacy VM project part-way through its move to Thin loses its VM container and the Thin stack the move set up; a Host project that was once Thin loses the Thin stack's data volumes (its config.toml, already restored, is left alone); a VM container is removed by the name it really has. The same holds for the trash: a project moved to the trash while such an operation runs is restored as that operation left it, and its port block stays reserved — never handed to another project — until it is restored, or emptied and cleaned up.

A folder that isn't answering stops a delete, a doctor run's checks that read folders, a reset, a restore, a registration, a folder choice, a Supabase path change or a bundle import before it starts. Each of these reads every project's folder in one step, which a stalled network mount would block for as long as it stalled, and all of Supbuddy with it. So each asks every registered, trashed and still-releasing project's folder first, off to the side, and if one hasn't answered within 5 seconds it refuses, naming the folder: try again once it answers. Supbuddy doesn't suggest unmounting or remounting a folder that isn't answering, anywhere: reconnecting it is the way out. Unmounted, a folder that holds a Supabase config makes the config look gone, and what was refused would then go on without it: a delete of its project would leave its Thin block in it and remove its data volumes, and another project's delete would stop a Supabase stack the two share. Which folders hold one can't be told without reading them, a project whose supabase/ is a link into the folder included. If you know your mount holds none, you can still unmount it yourself: a folder that is gone counts as answering. A doctor run then still runs the checks that read no folder, steps-waiting-for-folders and folders-still-releasing, and lists every other check as not run, with that reason. Deleting that project doesn't help: the delete asks its folder too. A legacy record's absolute rootPath, when it has no path, is asked too, as its config there is read. An expired project in the trash waits for the next hourly sweep. supbuddy reset --tier=full asks again after you confirm, before it touches the service; a folder that stops answering in the seconds after that still stops the reset before any step runs, but the service is uninstalled and the daemon stopped by then, and the command says how to get them back. Asked from the CLI's own process, the command can sit after refusing, as its exit waits on the same folder: press Ctrl-C. A daemon with a thread waiting on such a folder may not exit on a stop either; kill -9 ends it. Registering a project, choosing a project's folder, setting its Supabase path and importing a bundle do the same, in the app, MCP and the CLI: they keep projects apart by reading every project's folder in one step, so while one isn't answering they refuse with the same words, changing nothing. This is the default, chosen because freezing all of Supbuddy is worse; it can change if the owner decides otherwise. Over MCP, a tool refused because a folder isn't answering answers invalid_args, with the folders in details.folders_not_answering and the same words: try again once they answer. That includes a path that stops with the reason (below), system_wipe, and a staged plan applied meanwhile, whose recorded error says the same; doctor and doctor_fix still answer with a report whose errors say it. A stall that begins during one of these steps still blocks until the mount answers. Checking a path against the projects no longer reads a folder that isn't answering: in the app, opening a project's Supabase details, config, backups or env files, or acting on its Compose stack, and in MCP, every tool given a path. Each asks every project's folder first, off to the side, waiting at most those 5 seconds the first time, then decides without the one that didn't answer: a path inside it stops with the reason, to try again, and every other path is decided as before. At its start, Supbuddy resumes a delete a stop interrupted only once every project's folder answers; until then the delete stays on record, and is tried again every minute. So does its check of the cloud sync sessions that outlived it: until then, a cloud-linked project's Thin block isn't written to its config, and the refusal says why. With no such delete, that check waits by itself while a cloud-linked project's folder, or the folder of a deleted project whose check is still owed, isn't answering, asked every minute, as it reads every one of them. Either way, no Thin block is written meanwhile in a cloud-linked project's folder, a deleted one's still being deleted, or an owed check's, and a cloud-linked project whose folder hadn't answered keeps its own block held once it does, until it is checked. Stopping the live sync of a project whose folder isn't answering refuses with the reason, to try again once it answers. Stopping the live sync of a project whose folder answers checks it at once, as the refusal says, and frees its block for the rest of the wait. A check already under way asks again after each of its own steps (each stop of a session, and the listing after them): a folder that stopped answering meanwhile, the project's or one a session listed there is at, is read no more, nothing more is stopped there, and the check stays undone where it began, so its Thin block stays held until a later check (SUP-406). So do a check that waited its turn behind another for that project, the look for a session that reaches another folder, and the stop of a project's tracked session, a release's included, which then keeps the release and tries again (SUP-419). At the start, Supbuddy asks each folder a stop left held, as it was recorded, with every project's, and holds it without reading one that isn't answering. Starting, stopping or restarting Supabase, switching a project to or from Thin, and writing a project's files, such as an env file, .gitignore or config.toml, no longer read another project's folder that way: they ask it off to the side, wait at most those 5 seconds for each folder that stops answering, and only the first time, and go on. So does reading or writing a project's env file, and a start's update of the ports in its .env.supbuddy files. A scan of another project, and the Docker watcher, wait at most those 5 seconds on such a folder. A write into a folder that isn't answering stops with the reason before it touches the folder, to try again once it answers. If a folder stops answering once a start is under way, an old Thin project whose id that start would shorten keeps it for that start. A project that has answered since Supbuddy started is still kept out of the projects around it by where it last was. One that hasn't is left out if it is named elsewhere: if it was registered through a link from outside and its folder is really inside another project's, that project can read and write any file in it until it answers, as Supbuddy doesn't keep where each project's folder really is from one start to the next. One that hasn't, named inside another project's folder, stops that project's config, env files and file writes until it answers, with the reason, and a start of that project then leaves the ports in its .env.supbuddy files as they were: write them again with Connect once it answers. A delete's restore of a Thin project's config waits while any project's folder isn't answering, and tries again by itself. So does a delete's switch of a Thin project's config back, when a folder that may be a project inside it isn't answering: it is tried again once every project's folder answers, asked every minute, the project's data volumes are kept until it has gone through, and the daemon log says so. For the delete's own cleanup, so does the refusal of anything asked of the deleted project's folder meanwhile, which says to try again once it answers; a step left for a later delete holds no folder while it waits. The steps other deletes left for later wait with it, as running them reads every project's folder. So does checking those steps again at the end of a release, or of one of them, while any project's folder isn't answering: it is asked every minute, and runs once every folder answers. A release that ends while a project's folder isn't answering asks every folder first, and every path it reads of the deleted project, waiting at most those 5 seconds; when steps are left for later it asks both again before its last step, so about 10 seconds in all. While the deleted project's own folder, its Supabase config, or its Compose files and .env don't answer, a link out of its folder among them, the release waits, its folder still held, asks again every minute, and ends once they answer: only then does it record what the delete used, and a delete with Keep data what it kept. steps-waiting-for-folders lists it meanwhile. It reads nothing of another project's folder that doesn't answer: it keeps that folder out by where it last answered, and an older delete that can't be read meanwhile keeps a Keep data delete's record, which a later release clears. A link into another project's folder that doesn't answer isn't read either. supbuddy doctor and the app's System health list each step that waits this way (steps-waiting-for-folders): an interrupted delete, the end of a delete whose own folder doesn't answer, the Compose containers a stopped release left, each step left for later, and the check of the cloud sync sessions that outlived the last stop, with the folder it waits for and since when, and for that check, whose Thin blocks it holds. Each line says to reconnect the folder. Restarting Supbuddy is no way out: an interrupted delete waits again at the next start, and a step left for later is dropped for good, its work undone. Switching a project again to finish a Thin step that didn't land, and a legacy VM project's move to Thin, stop with the reason in that case, before they change anything: try again once that folder answers.

A delete leaves what another project still uses. Two projects can share one Supabase stack, config or database. A pair stored before Supbuddy refused such pairs can share a folder or a config: one project's Supabase path is the other's folder, or the two configs are one file. And two projects whose configs name the same project_id share its stack whenever they were registered — two worktrees of one repository, say: nothing refuses that pair. The project_id is the one the Supabase CLI runs: it drops a leading _, . or - and keeps the first 40 characters, so -acme and acme are one stack, and so are two Thin projects an earlier version set up whose long names gave managed ids alike in their first 40 characters. Deleting one of them — or its trash expiry — leaves the shared stack, config and data to the other, as long as that one is still registered or in the trash. A legacy record whose folder is its absolute rootPath (it has no path) counts by the config at that folder, as the shared-stack warning reads it, and by the ids on its record: it is only read, and nothing runs there; a relative rootPath is no folder; only the ids on its record count. When the two share only the stack, each with a config of its own, the deleted project's own config gets its project_id and ports back without the stop (the switch to Host's restore would stop the stack the other uses): as the last part of its delete, once the work in its folder has stopped, while the folder is still held, and at the next start if the daemon stopped first. It waits while a cloud sync may write that config, or while an earlier delete over the same config or folder is still under way. It writes nothing once the config no longer names the managed project_id, whatever else is in the way (a port edited since, or a mail section the config never had, still counts as the block, and is restored), and gives up when a project registered since uses that config, a delete with keep data used it, another project owns the folder, the config or its folder can't be read or written (a folder that is gone has nothing left to restore), or its original project_id was the managed one and its ports are neither the block's nor the originals' (whether it still carries the block can't be told); so it does when the other project's config can't be read either. Then the block stays, and the daemon log says so, naming the project_id and ports a switch back to Host would restore: set that config's back to them by hand before you use its folder again, unless a project deleted with its data kept used that config or its stack, or may have: the block is then what points that folder at the data it kept, so the line says to leave it unless you no longer need that data. doctor's note lists the block as below, except where the config or its folder couldn't be read or written. A later delete of the other removes what its own cleanup reaches; what only the earlier project's cleanup would have reached (for example an earlier Thin project's data volumes, when the later one is Host) is left, and doctor reports it. When the two share one config file, the earlier project's Thin block stays in it for good, even after the other is deleted too, since writing the originals back would point the other project at another stack, and its data with it. The earlier delete says so in the daemon log, naming the config, the block's project_id and ports, and the original project_id and ports to set back by hand. Once no registered project, nor one in the trash, uses that config, doctor's orphan-supabase-volumes lists it as a note, with the same how-to and no fix; set the values back yourself before that folder is used again. It isn't listed while a delete over that config is under way, or is pending after a restart with its cleanup still owed, whether that delete is the same project's or another's: that cleanup still reads the config, to stop the stack it names or to restore a block. When a project deleted with its data kept used that config or its stack, the note says to leave the block instead, since it is what points that folder at the data that delete kept. With the registry empty (after a reset), the note says whether a project still uses that config can't be told. When both are deleted together, the later delete does the teardown, and what only the earlier one would have reached — its Thin block in the config they shared, its data volumes — is removed once the later delete has finished, if no registered or trashed project uses it by then, and the restore only while the config still carries that project's block. A restart before that leaves them: doctor lists the volumes, and the block stays in the config, which doctor's note lists too once the config carries that block, as the waiting restore was recorded when it began to wait. A restore that waited and is then given up (a project registered or put in the trash since uses that config or that stack, another project, an import or a project moving out holds the folder, or a delete with keep data used it), or that a keep data delete stops before it waits at all, is never run later: the daemon log says the config keeps the block and why, with the values to set back, and doctor's note lists it, on the terms above. When that config can't be read then, the log says so, and what to set back if it does keep the block; the note comes once the config can be read and carries it. A restart gives such a restore up with no line of its own in the daemon log, but the waiting restore was recorded when it began to wait, so doctor's note lists the block on the terms above. A later delete with keep data keeps those too: no earlier delete removes what it kept, across a restart as well. A project registered or put in the trash since, using what such a waiting step would reach, cancels it for good. So does any other owner of the earlier project's folder, by the rules under A folder belongs to one project, even one that uses none of what the step would reach: a project there, registered or in the trash, whether registered since or sharing that folder all along (a pair stored before Supbuddy refused such pairs); a project whose Supabase files are in that folder, or whose folder holds the earlier project's; a bundle import into it, or what a failed one left; a project moving out of it. A waiting step never runs in a folder another project owns: what it would have removed is left, and doctor lists the volumes. While such a step runs, the earlier project's folder is held again: registering it is refused as still being released, naming the step, and doctor lists the folder if the step does not finish. The step is kept in memory only, so a restart drops it for good and frees the folder. A legacy Isolated (VM) project runs its Supabase stack inside its own container, and its delete never stops a stack on this machine. So when a Host project and a VM project that share a config are both deleted, the Host project's delete stops its stack, unless the VM project's delete keeps its data. While the VM project is still registered or in the trash, that stack is left to it, as to any project that shares it: after a move to Host that did not finish, the stack may be running here for the VM project, and so may the one its folder's own config names. The Thin stack a VM project's migration wizard staged counts as its own as well. A delete with keep data removes none of the project's data, as before; its own VM container and kept container go with any delete that is not keep data.

A bundle export asks where to save, and says when it fails. Export bundle (the project's ⋯ actions menu) opens the system folder picker, and the bundle is written into the folder you choose as a folder named <project name>.supbuddy. In that name, /, \, % and control characters are percent-encoded (client / site becomes client %2F site.supbuddy), so the bundle is always one folder directly inside the one you chose, Docker's writes included: the images and volume archives are written with each name and path passed to docker as its own argument, never through a shell, and the folder mounted with --mount, so a $( ), a quote, a : or a , in the project's name or the folder's path is only part of a name. A name whose folder would be longer than one file name may be (255 bytes) keeps the longest start that fits and a short hash of the whole name (<start>-<8 hex>.supbuddy). Re-exporting over the project's own earlier bundle folder writes into it, but what the export writes at its top — images/, volumes/, db-dumps/, compose.yml, .env, vm.yaml, manifest.json — must not be a link, nor a file where a folder goes or the reverse: the export is refused, naming it, before anything is written; an image archive that is a link is replaced, not written through. compose.yml, .env, vm.yaml and manifest.json are each written to a temporary file and renamed into place, so a link put at one of those names while the export runs is replaced too, never written through. Only the project's own earlier export is written over: the manifest records the project it was exported from (sourceProjectId), and an export into a folder that holds a bundle another project exported (two projects of one name, or of names your disk treats as one, such as Shop and shop on macOS) is refused, with nothing written. So is a bundle that records no project, which is every bundle made before this version, since whose it is cannot be told: the first re-export over one says so, and you move or delete it, or export into another folder. A folder of that name with no manifest.json (an export that did not finish) is written into, so a failed export can be retried. The bundle keeps the project's real name, which is what an import names the project by.

What a bundle carries, and says it carried. Each of the project's volumes that exists, archived under the name Compose gave it — <project>_<key>, or the name: the compose file sets — which the export asks Compose for, the way Supbuddy runs the project (its compose files and its pinned project name). And a pg_dumpall of each running Postgres server, streamed to its file whatever its size, as the image's own superuser (POSTGRES_USER, else postgres), on the port the container sets (PGPORT). Every running service of the project's Compose stack is asked with pg_isready, so a pgvector, PostGIS or TimescaleDB image is dumped as well. Volumes are listed with every Compose profile active, so a volume only a profile's service uses is carried too, and a volume Compose made for the project that no service uses now is named, not left out silently. Two keys Compose gives one name are one volume, archived once, and a volume is judged under all its keys: one key that declares it external, or with a driver or driver options, keeps it out for every key. Not carried, and said: an external volume; a volume declared with a driver or driver options, whose data stays where its driver keeps it; a volume not created yet; a database whose container is not running; a service in which no Postgres server answers (PostgREST, postgres-meta, a backup sidecar), with what pg_isready said; a volume of the project that no service of its compose files uses now; and the project's images when docker compose config --images fails to list them (none is saved then; a slim export saves none anyway). As before, bind-mounted folders are not carried either. The compose file carried is the base file Docker Compose uses in the folder, the first of compose.yaml, compose.yml, docker-compose.yml and docker-compose.yaml; if Supbuddy can't read that one, the export is refused. An override file (compose.override.yml and the rest) and Supbuddy's own supbuddy.addons.yml are not carried, so an import runs without what they change, and the export names each one the project runs with among what it does not carry. Their images are saved, though: the images are listed twice, from the base file alone, which is what an import runs, and from every compose file the project runs with, as its volumes are, and the bundle saves both. Each image is saved once, to an archive of its own in images/, named after the image with / and : as -; two images that would share that name, such as registry/app:1 and registry-app:1, or names apart only in letter case, each get a short hash of the full name in theirs, a longer one if those still match, and a name too long for a file name is cut and gets its hash (SUP-412). The success notice lists what the bundle carries — each volume's archive size, or that the volume was empty, and each dump's size — then what it does not. A volume archive is a file copy, not a database backup: tar copies the volume's files while its service may be running, so a database kept in one may not start from it after an import; when the bundle carries a database dump, that dump is the consistent copy. The notice, the import's preview and its notes say so. A volume that a running container had mounted when its archive began says so in the notice, naming the container (running_with over MCP), so you know which archives a service may have written to meanwhile: stop that service and export again for a copy taken with it stopped, or rely on the dump. It is a snapshot: a container started while the archive ran is not named. The export never pauses or stops a service, and the names are not written into the bundle. A dump that fails, or that writes nothing for 10 minutes, fails the export with its reason, and one cut short is ended in the container too. The dump runs pg_dumpall --verbose, so a dump reading a large catalog, which writes no SQL until it has read it all, is kept alive by its progress lines; the reason a failed dump gives is its first marked error line (pg_dump: error:), past the progress; with none, its first line that is not progress (which is how PostgreSQL 11 and older, whose errors carry no mark, say what failed); or else its last line. Verbose mode also writes the dump's start and end times, and a -- TOC entry and -- Dependencies: comment above every object, into the dump: harmless to a restore, but two exports of an unchanged database no longer have the same dump file or checksum. pg_dump prints nothing while it waits on a table lock, or while it locks table after table, so before Supbuddy stops a dump that has been silent for 10 minutes it asks the dump's server (pg_stat_activity, by the dump's own application name): while one of the dump's sessions is waiting in one of pg_dump's LOCK TABLEs, each bounded by the dump's --lock-wait-timeout=60s, or has begun a statement in the last 10 minutes, the dump is given another 10 minutes, and asked about again when they pass. Any other silence stops it, with the same reason: one statement running on for longer than that (a very long catalog query, however hard the server is working on it), a lock wait anywhere else (which has no such bound), a look that fails (PostgreSQL older than 9.6 cannot answer it) or that does not answer within 15 s. So a dump is never stopped for silence before 10 minutes. One that does nothing more is stopped at most 20 minutes 30 seconds after the later of its last output and the last statement it began (twice the limit and twice the look), and at most 10 minutes 15 seconds if it began nothing after its last output. Its failure can come up to 90 s after that, while its sessions are ended. A table lock still waited on at 60 s fails the dump with Postgres's own reason: that is the dump's failure, not a stop for silence. A dump whose file takes no more of it for 10 minutes once the dump has ended (a network share dropped, a disk ejected), or whose Docker command does not exit 10 minutes after its output ended, is stopped too, with no look at the server. An image's or a volume's archive has limits of its own, with no look either: it is stopped once it has written nothing for 120 s or has run 4 hours in all, not after 5 minutes however steadily it wrote. Its 120 s start at its first byte, and it has an hour before that: on Docker's older image store (overlay2 and the other graph drivers), docker save copies the whole image into a temporary folder before it writes anything, and a volume's archive may pull alpine first. The archives are what they were, streamed from Docker instead of written by it. A Docker or Compose read the export makes that does not answer is stopped: 60 s for each docker compose config, 30 s for a volume or container read. The export then fails naming what did not answer, and its folder is free for the next export; when it is the image list, the export goes on without images and says so (a slim export carries none anyway). Docker Compose's own version check is given 30 s too: past them the export fails, and the check is stopped with what it started (see "Docker Compose did not answer within 30 s"). A dump that keeps writing is never cut short for its size, up to 4 hours in all. A re-export over an earlier bundle folder removes the archives and dumps of the earlier export that it does not carry. The volume archives and the dumps are written readable by you only (0600): a database's files hold its roles' password hashes. Bundles exported before this version most likely carry no data: each volume archive was read from a volume named exactly after its compose key, which is the project's own only when the compose file names it so (a name: equal to the key, or such an external volume); otherwise it was a new, empty volume, which the export also left behind. And they most likely have no database dump: the earlier export made one only when the database had a role named root; such a dump was never checksummed, and the import leaves it in the bundle, unread. Re-export them. Bundles need Docker Compose v2 or later.

Cancelling the picker exports nothing. While it runs, the dialog shows the export's progress. A failure stays in the dialog with its reason; a success closes it, with a notice naming the bundle. Closing the dialog does not stop the export, and its outcome still arrives as a notice. While one export writes a bundle folder, a second export into the same folder is refused until the first has finished; two names your disk may take for one, such as Shop and shop, count as the same folder. If the folder picker itself fails, the dialog says so. The daemon answers as soon as the export has started, and announces its end; the app waits for that end however long the export takes, up to 6 hours. If the app's connection to the daemon drops before it hears the end, or the 6 hours pass, it says the export may still be running and where the bundle will be. If the daemon's answer that the export started is lost on the way (the app's connection to the daemon closed as the export went out) and the app has heard none of the export's progress either, it says there is no answer yet when that answer times out, rather than waiting up to 6 hours for an export that may never have started. A daemon of the previous version answers only at the end, and the app waits up to an hour for that answer, as before. An earlier export of the same project in that folder is written over; another project's bundle of that name, a bundle that records no project, and a file or a symlink of that name there are refused, with nothing written. So is a project whose domain a bundle cannot be imported with: the import judges it as every project's domain is judged (letters, digits and inner hyphens, at most 63 characters between dots), so a domain saved by an older version with an underscore, or a part over 63 characters, is refused before anything is written, naming the domain and the rule. Give the project another domain first (Edit project, update_project, supbuddy project set --domain). If the dialog answers Unrecognized key(s) in object: 'requestId', the app is talking to a daemon older than itself. The app restarts an older daemon when it launches, so this is usually its own previous daemon, left running when that restart did not take: quit and reopen the app (for a daemon you started with the CLI, supbuddy stop, then start it again). If a CLI daemon runs as a service (supbuddy service install), update the CLI too (npx supbuddy@latest): the app and the CLI ship together, each release of one with its matching release of the other. An import restores each volume with --mount too, so a bundle kept in a folder with a : in its name imports. Over MCP, export_bundle's out_path is the folder and must be absolute (a relative one is refused: it would be resolved against the daemon's working directory, not yours), and the result's bundle_path names the bundle; volumes (key, name, size_bytes, empty), db_dumps (service, file, size_bytes) and not_carried say what it carried and what not, and summary says the same as lines, which the CLI prints. In the CLI, supbuddy bundle export <project> [--out <folder>] writes into the current folder, or into --out, resolved against your shell's folder when it is relative. Over MCP, export_bundle's answer comes at 11 minutes at the latest: an export still running then goes on, the answer says it may be, and how it ended, with its reason if it failed, goes to the daemon's log under the reference the answer names. A dump that has gone silent can fail after that. A long export runs as a job. Pass background: true to export_bundle: the call (or the plan's apply, in its result) answers at once with its export_id and state: "running", nothing written yet. MCP get_bundle_export_status { export_id } (scope read) says how it is going: percent, message and updated_at, the last progress, which stands still through one long step (a dump or a volume's archive can take hours) as well as when Docker is not answering. It ends succeeded, with what export_bundle returns, or failed, with the reason in error, however long after the start that is. With no id it lists every export known. An export job can't be stopped, as an export can't. A finished job is forgotten after 50 later ones, and every job at a restart: an id not known is invalid_args, and the daemon's log still has how it ended. The CLI's bundle export runs as a job: it says the id, then waits on the status, printing each new progress line to stderr, and ends as an export did (exit 0 with what the bundle carries, or 1 with the reason it failed; with --json, a failed job's id, state and reason are on stdout too). --timeout=MS is how long to wait for it, and ends the waiting, never the export: the wait names the id and exits 2, as it does when it loses the daemon, and Ctrl-C ends the waiting too. supbuddy bundle export-status [<id>] says how one is going. With a daemon older than the CLI, bundle export asks for the whole export, as before, and waits up to 12 minutes for its answer, or until --timeout. That log is logs/daemon.log beside state.json for the app and a detached or launchd daemon, the journal for the Linux service (journalctl --user -u supbuddy-daemon), and the terminal for a foreground daemon, which keeps it in that file too. A daemon started with --quiet keeps none. Run without --out from inside the project's own folder, it is refused: the bundle holds the project's database, which would land in its working copy; pass --out. supbuddy bundle import <path> --project-path <dest> and bundle validate <path> resolve a relative path against your shell's folder too.

A bundle import writes only into an empty or new folder, and rolls back what it did. import_bundle (MCP; supbuddy bundle import <path> --project-path <dest> [--confirm-public-tld] in the CLI) imports a bundle made by this version's export — format version 3, which checksums the compose file, the .env and the database dump along with the images and volumes, and names each volume by its compose key — or by the export before it (format 2); an older bundle is refused, saying to re-export it, and an earlier Supbuddy refuses a format-3 bundle. The target folder must be absolute, and an empty folder or one that does not exist yet. The volumes it restores into must not exist yet (the MCP plan's preview already says the import would be refused when one does, or when an external volume it needs is missing, unless the volumes can only be named once its files are written), and neither may a Compose project of the import's name (its containers, networks or volumes) — the name Supbuddy uses for that folder afterwards: the compose file's name:, else the .env's COMPOSE_PROJECT_NAME, else the folder's name. A malformed bundle, one with a file that points outside it, a checksum mismatch or another architecture is refused too, each before anything is written; so is one whose project domain is not a domain name, or would be over the DNS limits on your default TLD, where it moves at the next restart. Only the bundle's own files are checked: its compose file is run as given, so what it references outside the bundle (an env_file, an include, a build context …) is read by Compose unchecked — import bundles from people whose Compose you would run. Each volume archive is restored into the volume Compose uses for it in the imported project (<project>_<key>, or its name:), which the import asks Compose for, on the bundle's own compose file and .env, before anything is written. A compose file that reaches outside the bundle by a relative path (an env_file: ../shared.env) is also read before anything is written, as from the folder you import into, where its paths will lead: a volume it would restore into that exists, or an external one that is missing, refuses the import then. Where its archives go is still decided right after its files are written, since up reads those outside files as they are then (a volume that exists by that time fails the import, which is rolled back). Not restored, and said in the import's notes: a key the bundle's compose file does not declare (one from an override or add-on file), a volume declared with a driver or driver options (Compose creates it when the project starts), a volume it declares external, and each archive of a format-2 bundle, which was read from the wrong volume — unless the volume is named after its key (then it is restored, an external one included). An external volume the compose file uses must exist, or the import is refused before anything is written — or, when the resolution waits for the files, fails right after they are written, and is rolled back. A restored volume carries the import's label and the labels its compose file declares, not Compose's own, so docker compose up prints volume "…" already exists but was not created by Docker Compose: expected, Compose uses it. For the same reason docker compose down -v leaves it: remove it with docker volume rm. The database dump is carried and checked, not applied: a database kept in a named volume comes back with its volume; for one kept in a bind mount (Supabase's self-hosted compose keeps it in ./volumes/db/data), the notes give the command that loads the dump into the running service. MCP import_bundle returns the notes as notes, and the CLI prints them. The folder is held for the whole import, so registering it meanwhile is refused ("is being imported as …"), and so is a second import that would run the same Compose project name at the same time (two folders of one name), and the project is registered — as a Host project — only once every step succeeded. A project the folder is inside keeps out of it from then on, as it does of a nested project's: its env readers and writers, and every other write, are refused there, saying what to do, and a write it already had under way is waited for before the import looks at the folder (and fails the import if it left a file). What a failed import's record keeps is held the same way, though a project registered inside that folder still has its own. A Compose project of the import's name that appears while it runs (any container or network of it, found right before its docker compose up) fails the import before its services start, and is left as it is. When a step fails, the import removes what it created: the services it started, the bundle's volumes, the files it wrote and the folder it made. It leaves the images it loaded (an image may be another project's). What it could not remove, the error names in three kinds: left, and the import's (its volumes come with a command that removes only the volumes carrying that import's label); unknown, when a check could not answer (for example its containers and networks after a stop it could not prove — the compose file, .env and folder are then kept, since they are what stops them); and not the import's, when someone else replaced it meanwhile, which is left as it is. It also names the images as possibly left. The other volumes the services need (declared in the compose file, plain local, not external, with no archive the import restores into it (a format-2 bundle's is never restored), and used by a service the up starts, as Compose itself counts them with the profiles the bundle's .env turns on) the import makes empty itself, before its docker compose up, as Compose would, with the import's label and Compose's own project and volume labels (SUP-413). When Compose can't say which those are, the import makes none, and Compose makes them, as before. The plan preview names them. Compose then takes each as its own, with no warning, and a failed import removes it as it removes the volumes it restored, by that label; one already there is left to Compose, as before. A label added through a Compose override would have been simpler, but Compose stores a volume's labels in its config hash, so every later start without that override would offer to recreate the volume, losing its data (measured with Compose v5.3.1). The volumes Compose itself creates for the services (one declared with a driver or driver options, or one Supbuddy could not make) are recorded around its docker compose up, by name and the time Docker says each was created: those of its Compose project there after the up and not before it, carrying no import label. Supbuddy never removes them: Docker gives a volume no id, and that time is to the second, so it can't prove one is still the one it recorded. While one is there as recorded it keeps the folder, and the fix below frees the folder once none is there. The report names the command that removes it (docker volume rm …), to run if it is the import's, only once the import's services are proven gone and no other project is at its folder or runs as that Compose project, which would reuse such a volume; otherwise it says why it gives none. One made again since under that name is another's, and is left without keeping the folder. When Docker doesn't answer that listing, none is recorded, and they are named as possibly left, as for an earlier version's record. What is left keeps the folder. When anything left is the import's, or could not be checked, the folder stays reserved for it — across restarts and a soft reset: registering it, or importing into it, is refused, naming the failed import, and so is another import that would run the same Compose project name — until supbuddy doctor --fix --only=failed-import-leftovers (MCP doctor_fix with check_ids: ["failed-import-leftovers"], or the app's System Doctor) removes it: it runs the rollback again from what the import recorded, removing only what still carries the import's identity (its label, or a file's identity and content), and frees the folder once nothing of the import's is left. It removes only the services the import's own start created: the import records, by full id, the containers and networks of its Compose project that were there after its docker compose up and not before it (when Docker answers that listing; when it doesn't, nothing is recorded and the fix removes no services, as for an earlier version's record), and the fix removes exactly those that are still there, never by the Compose project's name, which proves nothing once the import is gone. While any other container or network of that project exists, it names the command that stops them (run it if they are the import's) and keeps the folder. When another project runs as that same Compose project — registered, in the trash, being deleted, or one whose folder a release still holds (a Select Folder move's old folder) — it removes none of them, since that project may be using them, and says so instead, since down would stop that project too. A record an earlier version wrote has no ids, so its fix removes no services; an earlier version reads a record this version wrote as one it cannot replay, and only checks it. A full reset (supbuddy reset --tier=full) forgets these records, and removes none of what they left: it names them before you type RESET. When what is left can never be proven gone — Docker removed for good, or the leftovers removed by hand in a way the checks cannot see — supbuddy doctor --forget-import=<token> (the token is in the finding, as (import <token>); MCP forget_failed_import) frees that one folder and removes nothing: the CLI shows what may still be left and where (what the last rollback or purge reported, the folder's contents, the Compose project's containers and networks, what carries the import's label, with the commands that list them), asks y/N, and the daemon asks again (over MCP, preview: true returns that text, and the call itself is confirmed once by the daemon); once forgotten, Supbuddy no longer reports any of it, and the folder is no longer reserved (an import into it still needs it empty or new). It is never part of doctor --fix, and never runs with --fix or under doctor --fix --yes. Each failed import is recorded in a file of its own, failed-imports/<id>.json beside state.json; one that cannot be read is left there and reported by the doctor. An import is bound to what it checked, and stops when its MCP call gives up. Each image and volume archive is hashed again just before Docker reads it: one changed since the bundle was checked stops the import, which rolls back and names the file. Each file the import reads from the bundle, and each archive it hashes, must be the one it found inside the bundle, by its device, inode and birth time: one swapped in after that check, a link out of the bundle in its place included, is refused, saying it changed while it was being checked or it changed while it was being opened (SUP-416). It is a best effort: on a filesystem that keeps no birth time, a replacement given the removed file's inode can't be told apart. Docker never reads an archive by its path: the import sends each one to Docker on stdin from its own handle on it, hashing what it sends, so one changed even while it is sent fails the import, said as changed however Docker's own load or restore ended; for an image, the failure says Docker may have loaded images under other names from it, or moved a tag you had onto one, so check docker images, and a volume it restored is removed (SUP-418). An MCP plan is bound to the bundle it previewed (its manifest, which names every file's checksum) and to the folder project_path resolved to: a bundle changed or repaired, or a project_path that resolves to another folder (a link retargeted), before the apply makes the plan stale (plan_stale), and a plan whose preview said the import would be refused or would fail (the bundle itself, where its volumes would go, or no Docker Compose) cannot be applied — make a new plan. The plan's preview hashes the bundle's archives only up to 2 GiB of them, so a plan of a very large bundle is made in seconds: past that, it checks each archive is there and says it did not check their checksums, and the import checks every one before it writes anything (a wrong one refuses the bundle, with nothing written). Over MCP, an import still running at the 11-minute reply is stopped: no step starts after that, a read or a restore under way is cut short, and a request Docker is already carrying out (loading an image, creating a volume, starting the services) is left to finish first, so nothing it creates escapes the rollback. The reply waits up to 5 more minutes for the rollback and says what became of the import; if the import has not ended by then — still finishing a Docker request it never cuts short, or still rolling back — the reply says so and its outcome is logged when it ends — under its plan id, or the apply id the reply names — so do not start it again until then. A long import runs as a job. Pass background: true to import_bundle, and it has no ceiling: the call (or the plan's apply) answers at once with its import_id and state: "running", nothing imported yet, with the plan's binding and the same rollback. MCP get_bundle_import_status { import_id } (scope read) says how it is going: percent, message and updated_at, the last progress, which stands still through one long step (a large restore can take hours) as well as when Docker is not answering, so it does not by itself mean the import is stuck. It ends succeeded, with what import_bundle returns; failed, with what its rollback left in error, and folder_kept and fix (what to do about it) while what it left keeps the folder; refused, with nothing held or written (and for a domain on a real public suffix user_message and public_tld, as import_bundle refuses it); or cancelled. With no id it lists every import known, which is the way back if you lost the id. cancel_bundle_import { import_id } (scope services, no plan) stops it at its next step and rolls it back, answering at once with stopping; a request Docker is already carrying out runs to its end first, and a cancel after it has registered its project is too late, and stops nothing. One that never answers holds the import and its folder, whatever cancel_bundle_import asked, and only restarting Supbuddy ends it: the import is then a failed import, as below. A second start for a folder a job holds is refused, naming that job. A finished job is forgotten after 50 later ones, and at a restart: an id not known is invalid_args, and list_projects says whether it registered. The CLI's bundle import runs as a job: it says the id, then waits on the status, printing each new progress line to stderr, and ends as an import did (exit 0, or 1 with the failure). --timeout=MS is how long to wait for it, and ends the waiting, never the import: the wait names the id and exits 2, as it does when it loses the daemon. Ctrl-C ends the waiting too. supbuddy bundle status [<id>] says how one is going, and supbuddy bundle cancel <id> [--timeout=MS] stops it and waits for its rollback: exit 0 once it is rolled back with nothing left, exit 1 while what it left keeps the folder, saying what to do about it, or if it registered its project first, which stays registered. The app's import runs as the same job, so supbuddy bundle status and get_bundle_import_status see it by its id, and the app can follow it and stop it, rolling it back (a stop after it has registered its project is too late). That is ready for the app's import dialog, which no screen shows yet. Before it starts the import, that dialog checks the bundle to read its domain: every file but the archives' checksums, which it leaves to the import, so the check doesn't take longer for a bundle of a few GB; validate_bundle and supbuddy bundle validate still hash every archive (SUP-409). If Supbuddy stops while an import runs, a restart neither resumes it nor rolls it back. The import keeps its journal on disk before each step (failed-imports/<id>.json; a journal that cannot be written stops the import), so the next start finds a failed import: its folder reserved, failed-import-leftovers in the doctor, and the fix above, which runs the rollback from that journal; get_bundle_import_status answers for it by its id, with interrupted: true. If Supbuddy stopped while it waited for Docker to create a volume, a helper or the services, that request may still be under way and could create what the fix found gone, so the fix keeps the folder and says so: check that it has ended, with the commands it names, and only the forget above frees it. A journal is taken for a failed import only with no doubt about it. An import that registered its project and only failed to delete its journal is recognised whatever became of the project, and nothing is replayed (state.json keeps finishedImportTokens for this until the journal is gone). If state.json cannot be read, whether the import finished cannot be known: its journal is marked so on disk, the fix removes nothing and offers no command to remove anything, since what carries its label may be a live project's, and that holds across saves and restarts until a forget, a fix that finds nothing left, or a state.json naming it as finished. While another project is at its folder or runs as its Compose project, however its path is spelled, the fix removes nothing, and fix says so and names the forget. Each volume is restored by a helper container named supbuddy-import-<id>-<n> and labelled with the import's label, which the rollback removes by name — and only once its label proves it the import's.

Moving a secret between env files

copy_env_var ( { source_path, source_key, target_path, target_key? } ) relocates a single variable from one env file to another (e.g. a value put in an app's .env.local that the stack actually injects from the repo-root .env.local). The value is read and written entirely inside the worker (it never crosses the MCP boundary and never appears in the audit log), so an agent can move a secret without it being printed. target_key defaults to source_key.

write_env_file ( { path, patch }, a key set to null is removed) and copy_env_var edit the file rather than rewrite it: only the keys they set or remove change, and every other line (comments, export lines, the order, line ends) is kept as it was. Each value is written so that dotenv, which Next, Vite and the Supabase CLI load, reads it back exactly as given: unquoted when that reads back, otherwise in a quote that can hold it. A value holding $ (Next and Vite expand it), one no quote can hold, a key whose line Supbuddy reads as another key (K: v), or an edit that would change how another key reads, is refused with invalid_args, naming the key, and nothing is written. An export K= line is K to Supbuddy as to dotenv, so it can be set, and removing a key from a file that isn't there creates nothing. The config editor's secrets follow the same rule, checked before their .gitignore entry is added, except that a secret's $ is kept as it is (an SMTP password pa$$w0rd): only Supbuddy reads those SUPABASE_* values, and passes them to the Supabase CLI as given.

Plan / apply for destructive tools

Tools that delete or mutate state (delete_mapping, delete_project, switch_isolation, write_env_file, etc.) return a plan with a preview instead of a result. The MCP client (or you, in the Activity panel) explicitly calls apply with the plan_id to execute; cancel_plan discards it. Plans expire after 5 minutes if not applied. Soft-deletes go to the Trash and are recoverable for 7 days. A restore — restore_project, restore_mapping, or Restore in the app's Trash panel and Undo in its Activity panel — reloads the proxy, when it is running, and re-applies the OS resolver files, as the delete did, so the restored domains are served at once; when a step does not land, the reply of restore_project or restore_mapping says which (caddy_reload_warning, resolver_warning). The app's two answer as soon as the restore is made and reload after it, so a password prompt for a resolver file never leaves them waiting; a resolver file that could not be written is shown on its project. A Thin project whose loopback IP another project took meanwhile comes back on a new one: restore_project says so (loopback_ip_changed: { from, to }), so restart its dev servers, and, while the new alias is not on lo0 yet, carries requires_user_action with how to add it. A client with auto-apply skips staging and executes directly — except system_wipe, which always stages.

A staged plan carries two fields an agent should act on:

  • can_apply: true — the plan is applyable. It is on every pending plan, because a plan only exists once scope, argument validation and rate limiting have all passed. In particular it outranks required_feature, which is declarative metadata that nothing enforces — never read that field as a denial.
  • __apply_via — the literal next call: { tool: 'apply', args: { plan_id } }. The mirror of __reversible_via on completed operations.

The MCP server states the same contract in its initialize instructions, so any client sees it at connect time.

Confirmations, and why one came back without a yes

Some tools ask a person before they run: install_ca, uninstall_ca, revoke_mcp_client, request_scope_elevation, doctor_fix, forget_failed_import, forget_sync_check, confirm_folder_quiet, install_trust, remove_trust, set_port_forwarding, and the apply of a system_wipe plan. The daemon asks on its own machine, not in the agent's session: with the Supbuddy app open there, a native Allow / Deny dialog; with a foreground supbuddy daemon in a terminal there, a y/N prompt. A call that doesn't get a yes fails with one of three codes, and the error's details.approval names the case, so an agent never has to read the message:

Codedetails.approvalWhat happenedWhat to do
system_modal_deniedapproval_declinedA person was asked and said no: Deny, a cancelled dialog, or anything but y at the prompt.Don't retry on your own. Ask the user.
system_modal_unavailableapproval_unavailableNobody on that machine could answer. No app is attached and the daemon has no terminal (the start-on-login service, or an app-spawned daemon whose app is closed); the app could not show its dialog (no logged-in GUI session, or osascript failing); or the app went away before an answer, in which case its dialog may have been on screen.Open the Supbuddy app on that Mac, or run supbuddy daemon in a terminal there, and try again.
system_modal_timeoutapproval_timed_outThe question was put, and nobody answered within 60 seconds. The app's dialog closes itself just before then, and so does a terminal prompt (2 seconds before). A confirmation a foreground daemon could not put because its terminal stayed busy with an administrator prompt for 50 seconds answers this too. This is also what a remote Mac answers when the app runs in a logged-in session but nobody is at the screen.Ask the user to be there to answer, then try again.

Before this, all three came back as system_modal_denied "User denied the action" — even from a remote Mac where nobody had been shown anything. A daemon from before this change still answers that way, and its denial has no details.approval; supbuddy doctor --fix and supbuddy reset say so rather than call it a person's no.

Each message still names its case in words an older CLI recognises: the declined one says "denied the action", and the other two end with their code in parentheses. A supbuddy CLI older than this change therefore still reports these as the daemon's confirmation, but only with its old, combined explanation; update it (npx supbuddy@latest) for the three distinct answers.

The app shows its dialogs one at a time, in the order they were asked for, and stays connected to the daemon while one is open. Its confirmation dialog closes itself just before the call's 60 seconds run out, less any time it waited behind another dialog, and the call answers system_modal_timeout. An admin password prompt has no such limit. A request that waits behind another dialog until its caller has given up is never shown: a confirmation after 50 seconds, and an admin password prompt after 90 seconds, which leaves a minute to answer it within the 3 minutes the prompt is waited for. Requests that need nobody, such as saving an MCP client's token, never wait behind a dialog. Up to 3.8.2 the app instead dropped its connection to the daemon 20 to 45 seconds into any unanswered dialog, which failed the request while its dialog stayed on screen.

A foreground supbuddy daemon asks one thing at a time in its terminal, as the app shows one dialog at a time. A confirmation waits while an administrator (sudo) prompt the daemon started there is open, or its command still running, and a sudo prompt waits while a confirmation's y/N is open; two y/N prompts are never open at once. Before this, the two could share the terminal: a y could go to sudo, or the password to the y/N, which shows what is typed. A confirmation that has waited 50 seconds is not put, and the call answers system_modal_timeout; one put after a wait closes 2 seconds before the call's 60 seconds run out, less the time it waited. Two sudo prompts can still be open at once, as before. A daemon that stops while a sudo prompt waits for its turn never shows it, and the command does not run. With SUPBUDDY_ASKPASS, sudo asks nothing in the terminal and waits for nothing, but a confirmation's y/N is still asked there and waits behind another one, with the same 50-second cutoff. With --yes, no y/N is asked, but sudo still asks for the password in the terminal. With both, nothing is asked there and nothing waits. A daemon that is stopping runs no administrator command asked after its stop began, on either path.

Each confirmation leaves one line in the daemon's log: the tool, and approve or deny (<reason>). The request's summary, which the agent wrote, is never logged.

Remote setup: what needs a screen session

When you drive Supbuddy on a Mac nobody is sitting at, over SSH or through an agent, some steps still need a person at that Mac's screen, in person or over Screen Sharing. macOS asks for them in a dialog, and nothing else can answer it:

  • Administrator password prompts. Supbuddy's privileged steps each ask for one: port forwarding, /etc/resolver files, Thin projects' loopback aliases, and the /etc/hosts fallback. When nobody can be shown the prompt, the step fails with elevationKind unavailable. When nobody answers it, the step fails with timeout, and the prompt may still be on screen.
  • Confirmations for the tools listed above, unless a foreground supbuddy daemon runs in a terminal on that Mac.
  • Trusting the local CA, the first time, and again whenever its root changes.

When the local CA changes. Caddy's root changes rarely, for example after its data folder is reset. macOS then trusts none of the certificates Supbuddy serves until the new root is trusted. Supbuddy remembers the last root this Mac trusted, so it can tell a changed root from one that was never trusted. Only Supbuddy itself writes that record: a settings change from the app or an agent can't set or clear it. On macOS, supbuddy doctor, the app's System health and MCP doctor report it as "The local CA changed and needs trusting again (screen session)", and the app's CA Certificate row reads changed, not trusted. That is a fixable warning, and its steps are listed under it. MCP get_ca_status returns rootChanged and the same steps as remediation. A first install never reports a change, and neither does a root or a trust store that can't be read. The steps are:

  1. Connect to this Mac with Screen Sharing, or sit at it, logged in as the macOS user who runs Supbuddy.
  2. Open Supbuddy → Settings (the gear) → General → System health → Scan, click Fix… beside "The local CA changed and needs trusting again", then Apply. Or, in Terminal on that screen, run supbuddy doctor --fix --only=ca-not-trusted and confirm.
  3. Approve what macOS asks: an administrator password, to trust the new root for every user of this Mac. On newer macOS, Supbuddy may instead trust it in your login keychain, and macOS asks you to confirm with your login password.
  4. Fully quit and reopen your browsers (⌘Q, not just closing the window).

Until then, if bundled-runtime trust is on, dev tools that use Supbuddy's CA bundle trust the new root once restarted: the bundle picks it up when the proxy starts, with no password. Browsers don't use that bundle.

An attempt made from a distance gets the same steps back. Say an install_ca or doctor_fix reaches a dialog that nobody could be shown, or nobody answered: the admin prompt (elevationKind unavailable or timeout), or on macOS 15 and later the login-keychain trust dialog (trustDialog, the same two values). Then install_ca returns the steps as remediation, and doctor_fix returns them first in the repair's manualSteps, ahead of the Terminal command, which needs that screen too. Either way, only as long as the change still stands when the attempt ends. When Supbuddy's own confirmation gets no answer, the call fails before any prompt with system_modal_unavailable or system_modal_timeout (see above); while the change stands, that error carries the same steps too, in its message and as details.remediation (for doctor_fix, when it names ca-not-trusted), so supbuddy ca install and supbuddy doctor --fix print them, numbered, after the line saying what the confirmation came to.

Add-on Compose services

A project can declare extra Docker Compose services that Supbuddy discovers, merges, runs, health-checks, and tails alongside the managed stack: a Redis cache, a worker queue, a search engine, etc. Add-on services run on the host's shared Docker daemon in both host and thin isolation, with no extra setup needed.

Declaration files & merge precedence

Supbuddy looks for up to three Compose fragments in the project and merges them, later wins:

  1. Your base Compose file: compose.yaml, compose.yml, docker-compose.yml or docker-compose.yaml, the first of them in that order, as Docker Compose picks it.
  2. Your own override, honored if present: compose.override.yml, compose.override.yaml, docker-compose.override.yml or docker-compose.override.yaml, the first of them in that order, as Docker Compose picks it.
  3. supbuddy.addons.yml: Supbuddy-owned add-on fragment.

All present fragments are passed explicitly, e.g. docker compose -f docker-compose.yml -f docker-compose.override.yml -f supbuddy.addons.yml --project-name <pinned> …. The project name is pinned so the same set of containers is addressed every time. So a folder with both compose.yaml and docker-compose.yml runs compose.yaml, as docker compose there does. A stack an earlier version started there from docker-compose.yml is still running from it: Stop and Disable act on compose.yaml's services, so a service only in docker-compose.yml keeps running and drops off the card, and if the two files' name: differ, Stop reaches none of it. Stop that stack before you update, or run docker compose -f docker-compose.yml down in that folder afterwards; deleting the project still stops the containers Supbuddy recorded starting. A project folder with no Compose file Supbuddy recognizes (compose.yaml or .yml, docker-compose.yml or .yaml, or supbuddy.addons.yml or .yaml) starts, stops or lists nothing through Docker Compose, and nothing is recorded as its containers. A Compose file named only by COMPOSE_FILE in the folder's .env isn't read: give it one of those names. Started, stopped or restarted from the card, start_compose, stop_compose, restart_compose or supbuddy compose, it says <folder> has no compose.yaml, compose.yml, docker-compose.yaml, docker-compose.yml or supbuddy.addons.yml, so nothing was started (or stopped, or restarted), which is no failure; enabling or disabling the project starts or stops none either. Docker Compose with no file named looks in the parent folders for one, so a project inside a monorepo whose root has a docker-compose.yml would otherwise act on the root's stack. Add-on services join the Compose project's default network automatically; no extra network setup is needed for them to reach (or be reached by) the rest of the stack.

supbuddy.addons.yml format

A valid Compose fragment (a standard services: map) plus an optional Supbuddy-only x-supbuddy: extension block. A plain docker compose up ignores x-supbuddy:, so the file stays usable without Supbuddy. Today x-supbuddy supports a one-shot seed step:

services:
  redis:
    image: redis:7-alpine
    ports: ["6379:6379"]
x-supbuddy:
  seed:
    service: redis
    command: ["redis-cli", "ping"]   # explicit argv, runs once after services are healthy
    runOnce: true

The seed step runs once after the add-on services are up and healthy. It's idempotent, keyed by a signature of the seed spec, so it only re-runs if the spec changes (or you force it). It fires automatically on project start, and on demand via the seed_addons MCP tool.

MCP tools

  • scaffold_addons ( { project_id } ): scope config. Creates a starter supbuddy.addons.yml if the project doesn't have one. Never clobbers an existing file.
  • seed_addons ( { project_id, force? } ): scope services. Runs the declared x-supbuddy.seed step. Idempotent unless force: true.
  • tail_service_logs ( { project_id, service } ): scope log_tail. Streams a Compose/add-on service's container logs over SSE (like tail_request_logs, but for container stdout/stderr).
  • watch_supabase ( { project_id } ): scope log_tail. Streams a project's live Supabase start/stop/restart progress over SSE: operation (status + message), progress (image-pull/service snapshots), and log (raw lines, VM projects). The stream ends on a terminal status. Backs supbuddy supabase start --follow.

Scripts MCP tools

Scripts detected in a project (e.g. dev, build, test) are controllable over MCP:

  • list_scripts ( { project_id } ): scope read. Returns all detected scripts with their current status and bookmark state.
  • start_script ( { project_id, script } ): scope services. Starts the named script process. Refuses, having spawned nothing, when no packageManager field and no lockfile identify a manager for the project — the same verdict readiness gives that repo.
  • stop_script ( { project_id, script } ): scope services. Stops the named script process — the whole process group, so the dev server under the shell goes with it.
  • restart_script ( { project_id, script } ): scope services. Stops then starts the named script process. Refuses on the same terms as start_script.
  • bookmark_script ( { project_id, script, bookmarked } ): scope services. Pins (bookmarked: true) or unpins a script in the Quick Access group.
  • tail_script_logs ( { project_id, script } ): scope log_tail. Streams the named script's stdout/stderr over SSE.

get_compose_status shape

get_compose_status ( { project_id } ) returns per-service status, not just whether Compose is installed:

{
  "project_id": "…",
  "compose_installed": true,
  "running": true,
  "services": [
    { "name": "redis", "status": "running", "health": "healthy", "ports": ["6379:6379"], "image": "redis:7-alpine", "container_id": "…", "source": "addons" }
  ],
  "services_source": "store-snapshot (updated by docker events, not probed by this call)"
}

Each service's source is one of base | override | addons, telling you which fragment declared it.

The service statuses are a snapshot, kept current by Supbuddy's docker-events watcher rather than probed when you call — which is why services_source says so. Only compose_installed is checked on the call itself. get_supabase_status reports the same way, and answers the question its name asks: running plus the project's Supabase services, alongside the machine-level cli_installed and docker_running.

Per-project AI context sync

Each project has a Context sync: AI tools panel, accessible via the AI Tools tab in the project card, that writes a project-scoped briefing to disk so AI agents working in that repo see your live mappings, services, and isolation state without having to ask. Files written:

  • .supbuddy/: README.md, mappings.md, services.md, project.md, mcp.md, do-not.md, docs.md. The full live snapshot, regenerated on each sync. The panel's Open .supbuddy/ opens it in Finder (the project's folder, before the first sync has written it). A .supbuddy that is a link is not followed, and a folder macOS would launch (an .app, a .pkg) is revealed in Finder rather than opened. project.md's apps table lists, in each app's row, the mappings made for that app (matched by its name and folder). One made before Supbuddy recorded its app is listed too when it is on the port of the only app on that port, under a name that app's mapping is derived as (the one Supbuddy derives for it now, or <app name>.<domain>); otherwise it is in no row, nor is a manual mapping or a service's.
  • AGENTS.md and CLAUDE.md: a small managed block prepended (or updated in place) telling the agent which project this is and pointing it at .supbuddy/.
  • Editor skill files when detected: .cursor/rules/supbuddy.mdc, .claude/skills/supbuddy/SKILL.md, .codeium/windsurf/rules/supbuddy.md, .continue/rules/supbuddy.md, .github/copilot-instructions.md, .idea/supbuddy.md.
  • .gitignore managed block, ignoring: .supbuddy/meta.json (volatile sync state), *.supbuddy-backup-* (rollback snapshots), and the per-editor skill files that are written locally (see scope below). The rest of .supbuddy/ is intended to be committed; AGENTS.md, CLAUDE.md, and .github/copilot-instructions.md are also kept committable since you may have hand-written content there alongside Supbuddy's managed block.

Global vs. local scope

The per-editor skill files are generic Supbuddy-owned pointers ("this is a Supbuddy project: read .supbuddy/, prefer the MCP tools"). For editors that expose a Supbuddy-owned global location, Supbuddy writes that pointer once, machine-wide instead of copying it into every project, so it isn't duplicated across all your repos. Project-specific data always stays local in .supbuddy/.

  • Claude Code → one global skill at ~/.claude/skills/supbuddy/SKILL.md. Cursor → ~/.cursor/skills/supbuddy/SKILL.md. The global skill self-scopes: it only acts when the working directory has a .supbuddy/ folder, and resolves the active project from that folder's meta.json.
  • All other targets (windsurf, continue, the AGENTS.md/CLAUDE.md/Copilot managed blocks, JetBrains) stay local: their "global" files are shared user files, so Supbuddy won't overwrite them.
  • Each target has a scope setting: auto (default: global for the Claude/Cursor skills, local for everything else), global, local (force the per-project file; when Supbuddy manages the project's .gitignore, it lists the file in its own block, which it rewrites on every sync — to commit it, add a !<path> line below that block, or git add -f it; a .gitignore that is a link out of the project, into another project, or a hard link is left as it is, and the sync lists it as that file's error with the reason; turning sync off over one still releases the project's machine-global files, and says the block was left: the app with a warning, MCP update_project_context_settings with gitignore_note beside the settings), or off. A machine-global file is reference-counted across projects and removed automatically once no project uses it (on disabling sync, deleting a project, or switching that target back to local). Note: uninstalling Supbuddy (e.g. dragging it to the Trash on macOS) does not auto-remove these global files; delete them manually from ~/.claude/skills/supbuddy/, ~/.cursor/skills/supbuddy/ and ~/.agents/skills/supbuddy/ if needed. supbuddy reset (any tier) removes the user-level skills it installed; a skill file a project also routes there stays until the next start's cleanup removes it with the forgotten projects.
  • The always-loaded CLAUDE.md/AGENTS.md managed block stays local as a safety net so agents stay aware even if the on-demand global skill doesn't auto-activate.

Sync modes per project:

  • Auto: Supbuddy regenerates the files whenever mappings, services, or project state change.
  • Manual only: files are only written when you click Sync now (or use the tray's Sync AI context for all projects).
  • Off: nothing is written.

The collapsed header shows an at-a-glance status pill: mode (auto / manual / off), a colored dot for the last sync result, and a relative timestamp. Disabled targets (e.g. an editor whose folder isn't present) appear greyed out in the Detected targets list inside the panel.

Supbuddy Cloud

Push a project — its Supabase schema and data — to a hosted cloud dev-stack (its own full self-hosted Supabase — Postgres, Auth, REST, Storage, Realtime, Studio behind a gateway — as an isolated graph of machines on a per-tenant private network) and control it from the app, the CLI, or MCP. Opt-in and per-project: nothing cloud-related appears in a project until you've signed in.

  • Invite-only, for now — Supbuddy Cloud is not open signup. You need an invite from the Supbuddy operator; redeeming it creates your own organisation, with you as its owner. Until you redeem one, cloud actions answer "Supbuddy Cloud is invite-only. Redeem your invite code to create your organisation." Org members cannot issue invites — only the operator can.
  • Get started — the top bar shows a Get started with Supbuddy Cloud strip; sign in (email/password) there. Once signed in it becomes Open cloud (opens cloud.supbuddy.app in your browser). Sign-in state + the Claude connection also live under Settings → Cloud.
  • Push a project — after signing in, each project's ⋯ menu gains Push to cloud…. The dialog previews what the project's env would mean in the box before you commit: values are classified, never rewritten, and it leads with how many point at this machine — those are meaningless inside a box and are the only ones needing a decision. It never blocks the push (a local-looking value may be exactly what you meant) and changes nothing for you. Secrets are listed by name only; their values are never read out of the file. The push ships the project's stack descriptor + a pg_dump of its Supabase data (fail-closed: uploaded to a private bucket via a single-use key, sha-verified, restored inside the stack's private network, then deleted). Your local project stays intact — a ☁ badge appears on its row; click it (or ⋯ → Open in cloud) to open the stack in the web app.
  • CLI / MCP — the same flow headless: supbuddy cloud login|push|status|teardown (password via arg or SUPBUDDY_CLOUD_PASSWORD), or the push_to_cloud / get_cloud_status / cloud_teardown / cloud_sign_in MCP tools. project ls marks pushed projects with ☁, and get_project / list_projects carry the cloud link. cloud_teardown (and the ⋯ teardown) destroy the remote stack and unlink it locally — routed through the same plan/apply gate as other destructive tools.
  • Service breadth — a self-hosted push provisions the full Supabase stack by default. Pass push_to_cloud's supabase_services: "minimal" (MCP) to opt down to a lean db/auth/REST stack instead.
  • Idle auto-stop — a running cloud stack that reports no activity for ~30 minutes is automatically stopped to save cost (its data + config persist; start it again from the web app). A background reaper also reconciles any stack whose machines went missing.
  • Web console — cloud.supbuddy.app lists your org's stacks; open one for its per-service health, live status, and start / stop / restart / tear down controls, plus a Recent activity feed of control-plane events. Push to cloud in the console provisions a stack from a GitHub owner/repo (self-hosted or bring-your-own Supabase; full or minimal service set) — the code-only path; pushing a local project with its data still goes through the desktop app / CLI.

Public addresses, and renaming them

Each app in a cloud box gets a public address of the form <app>.<project>.<org>.supbuddy.cloud — for example web.site.acme.supbuddy.cloud. The <app> label comes from the runner serving that port, <project> and <org> from the slugs you choose. One wildcard certificate is issued per project (*.<project>.<org>.supbuddy.cloud) and covers every app under it.

  • Renaming is allowed while boxes are running. It used to be refused, and for a real reason: a box was told its hostnames once, when its machine was created, and that value cannot be changed afterwards — so a rename left it serving the old names while the new address showed the editor instead of your app. Boxes now ask for their hostnames on each heartbeat, so a running box moves itself, usually within a minute.
  • The old address stops working immediately. Its DNS records are removed as part of the rename. This is deliberate: leaving them would make the old URL resolve and quietly serve the editor, which is more confusing than a name that has plainly gone away. Links you have already shared will break.
  • A rename can succeed while an address is still moving. Certificates are issued by Let's Encrypt, which limits how often the same set of names can be re-issued (5 per week), so renaming back and forth can hit that ceiling. The rename itself still applies — you will see "The name is changed, but 1 box is still moving to it…" with the reason, rather than a silent half-rename.
  • Hostnames need the deployment to be configured for them (VERCEL_TOKEN, VERCEL_TEAM_ID, SUPBUDDY_CLOUD_BASE_DOMAIN). Without those, boxes are still reachable through the editor and the stack page says "public hostnames are not configured on this deployment" rather than showing nothing.

The Supbuddy panel, inside the box's editor

Every cloud box's editor carries a Supbuddy view in the activity bar — one place to see what the box is doing without leaving it. It reads the status report the box's own supervisor writes, so it adds no credential and no network listener of its own.

  • Box (the main view) — the box's phase and uptime, then four sections:
    • Apps — the runners this project declared. Each shows its state and port, with Open (in the editor's browser), Tab (a real browser tab), Start / Stop, Restart and Logs. A runner that has not started is still listed, because that is usually the one you came to start — and a runner that failed shows why (for example approved for aaaaaaaa, HEAD is bbbbbbbb when autostart's approved commit no longer matches what the box checked out).
    • Services — the stack's own Supabase and sidecar services, with where each one lives. These run on separate machines on your private network, so they are probed rather than supervised; one whose first probe has not landed reads checking, not down.
    • Configuration — read-only: the repository, the commit, the workspace path, the tailnet name and any public hostnames. Nothing here is editable, because all of it is decided by the plan that built the box.
    • System — the box's own plumbing (clone, sshd, tailnet, credential and module installs). It expands itself when something in it is wrong.
  • Logs open inline, under the app that produced them, and press again to close. A runner with no output says so rather than showing an empty box, and when the supervisor cannot be reached the panel shows its reason instead of failing quietly.
  • If the supervisor stops writing, the panel says so — "The supervisor stopped updating 45s ago. What is shown below may no longer be true." A stale report is never rendered as healthy.
  • Apps & Services — the original compact tree, still available below the panel and collapsed by default.

Who runs your code inside the box

The editor, its terminal and Claude Code run as coder, which has sudo: the box is your machine.

Code from your repository that the box runs on its own runs as a separate user, runner, with no sudo. That covers the dependency install, a devcontainer's postCreateCommand and the apps the box starts.

  • runner can read and write the project folder, and can read .git but not change it.
  • runner cannot open anything else in coder's home: your Claude and Codex sign-ins, the box's own tokens, the editor's settings.
  • Files either user creates in the project folder stay editable by the other. Some installed files keep read-only modes (under node_modules, for example); remove those from the terminal with sudo rm.
  • git commands inside your apps still work. A setup step that writes into .git fails as runner (for example husky install); run it from the terminal instead.
  • If the box cannot set these permissions, it runs none of the repository's code and says why under System (isolation). It does not quietly run that code as coder instead.

The separation keeps unattended code away from your credentials. It does not make a repository safe to open: runner can change files that you later run as coder, such as package scripts, .husky hooks and node_modules.

When nothing says what to run (no app was detected when you pushed, or the stack was created from the web console), the box lists one app, web, on port 3000. Starting it runs your project's dev script (or start if there is no dev script), using the package manager your packageManager field or lockfile names. If neither identifies a package manager, or neither script exists, the app shows refused with the reason instead of retrying. The app is expected on port 3000 (PORT is set to it): a dev script that picks its own port, such as next dev -p 3336, still runs, but that port is not reachable through the app's address. Push from the Supbuddy app instead, which reads the port from your dev script.

Pushing again, and a box that was rebuilt

Every push approves the commit you pushed: your local HEAD at the time. That includes a push to a project whose stack is still running. The box's apps start on their own, and its devcontainer setup runs, only for the approved commit.

A box keeps its project folder across rebuilds, so a rebuilt box can come back with an old checkout. When that happens, it moves the checkout to the approved commit before anything else can touch the folder, but only when it is safe to:

  • the checkout is on the branch the box follows, with no local commits, no uncommitted or untracked changes, and no merge or rebase in progress;
  • the approved commit is on that branch on GitHub (a commit from another branch is never moved onto it);
  • the move is a fast-forward. It never overwrites a file git ignores, and no hook in the repository runs.

Otherwise the checkout is left exactly as it was, and System → checkout in the box's Supbuddy panel says why: local commits, uncommitted changes, the commit not being on GitHub yet, and so on. If an update is interrupted part way, the box stops retrying and asks you to check git status first.

New commits on GitHub

When commits land on the box's branch — pushed from Supbuddy or from anywhere else — the box notices within about two minutes, or within seconds of a push from the Supbuddy app. The editor then shows it in three places:

  • the status bar: 3 new commits on main, which runs Pull when clicked;
  • a thin strip at the top of the Supbuddy panel, with a Pull button;
  • one notification per push, with Pull and Later. It isn't repeated when you reload the window.

Pull runs in an editor terminal, so you see every step:

  1. It fetches the branch.
  2. It sets aside your uncommitted and untracked changes (git stash).
  3. It fast-forwards. If the box has local commits, it merges them instead, or rebases them if you've set pull.rebase, just as git pull would.
  4. It puts your changes back.

If step 3 or 4 conflicts, Pull lists the files and offers to resolve them with Claude or Codex (continue your last session in this folder, or start a new one), or to leave them to you. The assistant runs interactively in the same terminal, so you see and approve its edits. Pull never commits or pushes for you without asking.

Pull stops before changing anything while a merge, rebase, cherry-pick or revert is in progress.

While live sync is on, the strip still tells you about new commits but offers no Pull. Pull on your own machine instead, and sync brings the changes into the box. Pulling inside the box would rewrite files that sync then copies back to your machine as unexplained changes.

A pull moves the box past the commit you approved, so after a restart its apps don't start on their own until you push again from the Supbuddy app. Starting them from the panel works either way.

Live sync (local ↔ cloud)

Keep a project's local directory and its cloud box in step, so you can edit locally and run in the cloud. Sync runs over a private Tailscale network; nothing is exposed publicly.

  • Start it — in the app, a cloud project's ⋯ menu has Start live sync… and Stop live sync. Starting opens a chooser: nothing is preselected and the confirm button stays disabled until you pick a side, because the first pass overwrites one of them.
  • Headless — supbuddy cloud sync start <project> --authority=cloud|local, plus status and stop. Same three as MCP tools (cloud_sync_start / cloud_sync_status / cloud_sync_stop). stop also takes the id of a project that is not listed, deleted or in the trash; a name must be listed.
  • Supbuddy refuses a cloud-authority sync that would destroy local-only work. The box clones your repository from its remote, so it has never seen uncommitted changes or commits you have not pushed — and the first pass deletes anything the other side lacks. Rather than let that happen, starting sync with the cloud as authority is refused, naming what is at risk and the remedy: "…has 2 uncommitted changes (commit or stash them), and 1 unpushed commit (push them first)." A directory that is not a git repository is refused too, since nothing there could be recovered. Choosing this machine's copy is never blocked — that direction overwrites the box.
  • Sync survives restarting Supbuddy. The file synchroniser runs in its own process, so quitting and reopening the app (or an update) does not interrupt a running sync; Supbuddy re-adopts the session on start and the status badge picks up where it left off.
  • A project linked to another stack while its old stack's session is still tracked (a stop that couldn't be confirmed, or one not run yet) can't start sync for the new stack: the start is refused, naming the old session. Stop live sync, then start it again.
  • authority decides which side wins the FIRST pass, and that pass is one-way. Choose "cloud" when the box has the truth (the usual case — the repo was cloned there) and "local" when your machine does. It has no default anywhere, deliberately: the named side overwrites the other, so a guess can delete work. After the first sync completes, the session switches to two-way automatically. Only the project's own session at its folder is switched, by its identifier: another checkout of the same repository, linked to the same stack, keeps its session running. Its status is read from its own session too (SUP-404): the one with its identifier, or with none known, the one at its folder, so another checkout's session on the same stack never shows as its phase or holds up its switch; none of its own listed reads as stopped, and two at its folder, or a folder that doesn't answer, as unknown. While the file synchroniser can't say which session there is the project's own, the session stays one-way and the next status tries again: its status reads as unknown, or, when the switch itself can't tell, the badge's hover and cloud_sync_status's promoteError say why. If the switch ends the one-way session and then can't create the two-way one, Supbuddy no longer syncs the folder: the badge reads Sync stopped by Supbuddy, and cloud_sync_status answers phase: "stopped" with the file synchroniser's reason in promoteError and stoppedReason, until you stop live sync and start it again (SUP-411). That is kept in memory, so after Supbuddy restarts the status shows no sync, and you start it again.
  • What is not synced — .git, node_modules, .next, dist and .turbo are ignored by default. .git in particular: the box has its own clone with its own remote, and syncing two managed copies of an index produces conflicts that look like repository corruption.
  • Nor is any supabase/config.toml or supabase/config.hosted.toml, at the root or under a Supabase path, whatever else is ignored. A Thin project's config.toml carries its own port block and Compose project_id, which only Supbuddy writes; a sync would put the box's copy over it while the stack runs. A project can become Thin while its sync runs, so every session leaves them out.
    • In both directions. An edit to config.toml on the box no longer comes back to your folder, and a local edit no longer reaches the box. Make the change on each side that needs it.
    • When the daemon starts, and again at every full proxy start, Supbuddy checks the sessions the file synchroniser still runs for each pushed project. That includes a project whose sync Supbuddy is already running: another session there under its name may have appeared since. One an earlier version started without leaving the files out is stopped; your files are not touched. The project's sync badge then reads Sync stopped by Supbuddy (hover it for why), and cloud_sync_status answers phase: "stopped" with a stoppedReason. Start sync again: the new session leaves the files out.
    • Until that check is done, and while it could not be (a session that could not be stopped, or a file synchroniser that did not answer), Supbuddy does not write a Thin block in that project's folder: its own, or that of a Thin project inside it. That holds for a project whose sync is running, too: if the file synchroniser doesn't answer at a full proxy start, its Thin block waits for a later check, or for live sync to be stopped. A start, a switch to Thin or a rename that needs to write one fails with the reason, before anything is stopped or copied.
    • Stop live sync for the project (its ⋯ menu, cloud_sync_stop, or supbuddy cloud sync stop) checks again, stops a session there that syncs the file, and lifts the refusal; for a registered or trashed project a restart does too. If the file synchroniser still does not answer, a Mutagen daemon of another version may be refusing Supbuddy's: stop it with that version's mutagen daemon stop, then stop live sync again. A check left undone because a link on the folder's path was pointed elsewhere while it ran is the exception (SUP-411): a stop checks the folder the restart checked, so it refuses while the folder leads elsewhere, after it has stopped the sync. The refusal says so: restart Supbuddy, which checks again where the folder leads then (not for a project whose delete has finished, below), or point the link back and stop live sync then.
    • A project deleted, or in the trash, since the check has no ⋯ menu, and the CLI does not list it: the refusal names its id, and supbuddy cloud sync stop <id>, or MCP's cloud_sync_stop with that project_id, checks again, stops a session there that syncs the file, and lifts it. For a project whose delete has finished, a restart is no remedy, unless the check was left to it (below): it forgets the check without looking at its sessions.
    • A delete waits for that check. A project deleted while a check of its folder could not be done is not released until the check has been done: its release checks every session at the folder again, as cloud_sync_stop does, and tries again until the file synchroniser answers. Meanwhile the folder is held (registering it is refused, naming what it waits for, and the doctor's still-releasing check lists it), and a restart resumes the release, which checks again then (and waits again while the file synchroniser still does not answer). supbuddy cloud sync stop <id>, or MCP's cloud_sync_stop with the project's id, checks at once; the release's next try, within a minute, then frees the folder. If the file synchroniser will never answer, supbuddy doctor --forget-sync-check=<id> ends that wait on your word (below).
    • A delete a restart does not resume keeps that check. A restart drops, running none of its cleanup, a delete that overlaps a live or trashed project in a way it does not resume. The check is kept on disk all the same: that restart, every later one and every full proxy start check the deleted project's sessions at its folder, as cloud_sync_stop does, until the check has been done. A session there that syncs the file is stopped; so is one that leaves it out, as long as it is the deleted project's own (next item). No session is adopted for the deleted project. Until then no Thin block is written in that folder, and supbuddy cloud sync stop <id>, or MCP's cloud_sync_stop with the deleted project's id, checks at once. When a live or trashed project uses the same cloud stack in the same folder, those sessions are that project's, and its own check covers them.
    • A delete that finds nothing of its sync keeps that check too. A session no restart adopted is tracked by nothing: one left by a stop after a restart at which the file synchroniser did not answer, or one of two checkouts on the same cloud stack. So a delete that stops no session it tracks there, and finds no check left at its folder, keeps a check of its sessions there, on disk, as above, unless its folder is on record as relative or spelled with .., which names no single folder. The next restart or full proxy start makes it. Nothing waits for the file synchroniser at the delete.
    • A deleted project's own session is stopped, by its identifier, even when it leaves the file out, whichever of those checks finds it: under that project's session name, at its own folder, with no live or trashed project on that cloud stack at that folder. It was still syncing that folder with the deleted project's box, and the folder may since be another project's. The synced files stay where they are. A session of that name at any other folder is not touched. One Supbuddy can't prove is its own is left running, and the log says which, where and why: no identifier in Mutagen's form, another listed name, or a live or trashed project on that stack that is, or may be, at that folder (one whose folder can't be told counts). To stop it yourself: mutagen sync terminate <its identifier>. A project whose folder is on record as a relative path is never adopted, so its checks take the same proof at the folder that path resolves to, whatever the project is: without it, they stop only a session there that syncs the file. A session such a check leaves running is in the log too, with why and how to stop it.
    • A deleted project's session that a link takes to another folder is not stopped there. The file synchroniser follows a link above a session's folder, so a link pointed elsewhere since takes the session to whatever folder it names now, and a check at the deleted project's folder finds nothing there. When a check finds one of its stack's sessions that syncs the file and reaches another folder that way, with no live or trashed project on that stack there, the check stays owed, on disk, and no Thin block is written in the folder it reaches, nor inside it. The refusal names the session, and the log says it once. Stop it yourself with mutagen sync terminate <its identifier>: the next restart or full proxy start finds it gone and concludes the check, and supbuddy cloud sync stop <id> checks at once. A link at the session's own folder takes it nowhere: the file synchroniser refuses to sync one. One behind a link that points nowhere now keeps its check owed too, with nothing refused: pointed somewhere again, it reaches that folder.
    • When the file synchroniser will never answer, every one of those ways waits for it. Once you know that sync is gone, supbuddy doctor --forget-sync-check=<id> (MCP forget_sync_check, scope system) forgets the checks owed for that deleted project, and the refusal ends, at a folder a session of it reaches through a link too. It also ends a delete's wait on such a check: the release's cloud sync part tries again at once and finishes, and the folder is freed once the rest of the release has finished. Each wait it ends keeps its own check of that folder, saved, made once the file synchroniser answers again, which stops the deleted project's own session there. A folder on record as relative, or spelled with .., keeps none, and the confirmation says so. Until then the freed folder may become another project's, and a session left there would sync its files with the deleted project's box. Your yes is kept in memory only: if Supbuddy stops before the whole release has finished, a wait can come back when it starts again, and you can forget it again; that start also holds the folder until you confirm it is quiet (supbuddy doctor --confirm-quiet=<id>). It stops and removes nothing: a session of that name goes on running, and Supbuddy no longer looks for an owed check it forgets. It says so, naming each check it forgets and each delete it lets finish, asks y/N, and the daemon asks again. doctor --fix never does this. It forgets nothing while a live or trashed project of that id, or its move away from that folder, still relies on the check, since that refusal would stay: stop that project's live sync instead, or let the move finish.
    • Without the mutagen package sync cannot run, so there is nothing to check and nothing is refused.
  • Requirements — sync needs the tailscaled and mutagen platform packages, which install automatically with the CLI on macOS and Linux (Intel and Apple Silicon / x86-64 and arm64). Windows is not supported yet, and Supbuddy says so rather than reporting a missing package. Without the packages Supbuddy reports sync as unavailable and everything else keeps working.
  • Your own Tailscale is untouched. Supbuddy runs its own tailnet daemon with a separate state file and socket, so joining does not log you out of a personal or work tailnet.
  • Teardown stops sync first, and the box's tailnet node is removed with the stack — nothing outlives a destroyed stack.
  • Seeing it — a syncing project shows its state beside the ☁ badge: First sync…, In sync, n conflicts, or Paused — stack stopped when the box has been idle-stopped. Nothing is shown for a project that is not syncing.
  • If sync is unavailable, everything else keeps working. Provisioning, the IDE, runners and teardown do not depend on the sync network; a stack simply comes up without sync and says so.

Command-line interface (CLI)

Everything the desktop app can do is also driveable headlessly from a terminal, with no GUI window. The CLI runs a daemon (the same worker process the GUI uses: Caddy proxy, DNS, Supabase/Compose lifecycle, MCP-HTTP) and a set of commands that attach to it over the local MCP-HTTP port. This is for SSH sessions, CI, tmux/server boxes, and scripting.

The binary is supbuddy, with a short alias sup. Run supbuddy help for the full usage list.

You can install the CLI on its own, without the desktop app:

npx supbuddy@latest        # asks to install the CLI globally (supbuddy + sup)

That command does nothing on its own except offer to put supbuddy and sup on your PATH. The CLI runs independently of the desktop app, so you can add the app later (or never). On a Mac the app installs the same two commands for you.

The daemon

supbuddy daemon --detach        # start the worker in the background
supbuddy status                 # daemon + proxy health, plus which worker the daemon is running
supbuddy version                # which CLI build this is, and which daemon it is talking to
supbuddy stop                   # graceful shutdown

supbuddy version answers a question that used to have no answer: which copy of the CLI is this? Three builds exist and they look identical — the one inside the desktop app (host), the one from npm (npm), and one built from a checkout (dev). The build kind is stamped in at compile time, because nothing at runtime can tell them apart: the version numbers match, and a working-tree build even carries the same daemon/worker.cjs layout as an npm install. It prints the CLI's version, build kind and path, plus the daemon's, and warns when the two disagree — a dev CLI driving a shipped daemon means unreleased code is running privileged repairs against your real machine.

The names supbuddy and sup are reserved for shipped builds. A dev build invoked under either name refuses to run and explains how to find the shadowing symlink, because pnpm link or a hand-made symlink in a directory that precedes /usr/local/bin on PATH otherwise silently replaces the installed CLI. To run a checkout, use ./scripts/supbuddy-dev <command> — it runs from source and needs no build. It deliberately shares the production state dir: a daemon's machine-level resources (the worker port, the Caddyfile, /etc/hosts, /etc/resolver, the pf anchor, the launchd label) are not state-dir scoped, so pointing a dev daemon at a private state dir does not isolate it — it only hides the running daemon from the single-daemon check, after which the dev worker takes port 48760 by killing the process holding it. Sharing the state dir keeps that check working, so supbuddy-dev daemon declines while the app's daemon is running. A dev CLI driving a shipped daemon prints a warning on every command.

--detach backgrounds the daemon and prints its pid + ports. Foreground supbuddy daemon runs it attached (Ctrl-C shuts it down cleanly). On start the daemon writes a discovery file, daemon.json (mode 0600), into the shared state dir holding its pid, the Socket.IO port, the MCP-HTTP port, and a control token; every other command reads it to find and authenticate to the daemon, so you never pass ports or tokens by hand. Only one daemon may run per state dir; a second daemon start is refused. A daemon that starts while the one recorded in that daemon.json still holds its port (one left running when its launcher died, say) stops it before it reads state.json, and waits up to 5 s for it to exit, so nothing that one saves is lost to the new one's first save (SUP-348); on Linux without lsof, it asks iproute2's ss who listens there (SUP-421), and a listener whose process it can't see stops nothing; anything else on the port is never stopped, and the start then fails, naming it. If the daemon refuses the token a command presents (a stale --token, or a different daemon answering on that port), the command says so rather than "could not reach the daemon". The Socket.IO port, which the app's window connects to directly for live updates, listens on 127.0.0.1 only, takes WebSocket only (a polling request, Engine.IO's JSONP included, gets 400 whoever sends it), and accepts only the app's own origins (tauri://localhost; http://tauri.localhost and https://tauri.localhost; the dev build's http://127.0.0.1:5199 and http://localhost:5199) or a client that sends no Origin, as supbuddy selftest does: a web page open in a browser on this machine is refused at the handshake (logged once a minute as Refused a Socket.IO connection from origin "…"), unless it is served from port 5199, which the token below then stops. It also takes a token of its own (socketToken in daemon.json, a new one at each daemon start; not the control token): the app's window reads it through the app and sends it at the handshake, and a connection without it, or with another, is refused (logged once a minute as Refused a Socket.IO connection from …: no socket token, …: a wrong socket token, or, while the window has none to send yet after a daemon restart, …: an empty socket token (the app has none yet), retried a second later), whatever its origin. So a program running as another user account, which cannot read daemon.json, can no longer listen in; a program running as you can read the file, as it can the control token. supbuddy selftest's probe of this port opens the WebSocket only, and needs no token. An app older than 3.14.0 sends no token, and since SUP-303 its window gets no live updates from a newer daemon (its socket is refused, logged as no socket token): update the app. Until then such an app's window was admitted without the token while that app was attached (SUP-264's fallback), which any program sending the app's origin, another account's too, could use to listen. The socket only reports, and changes nothing.

The CLI and the desktop app share one state dir (~/Library/Application Support/Supbuddy/), so they manage the same projects, mappings, and settings. They must not run two workers against it at once: if you launch the desktop app while a CLI daemon is running, the app detects it and offers to stop the daemon and continue or quit. It never forks a competing worker (which would corrupt state.json).

One app per daemon. Supbuddy runs one desktop app per daemon. Opening it again (a second copy of the app, a development build beside the installed one, open -n) brings the running app's window forward, and the new launch exits before it touches the daemon. Two apps on one daemon used to take the daemon's password prompts and confirmations from each other, and a second copy of another version could replace the daemon under the first. If the running app does not answer, the new launch says "Supbuddy is already running but not responding": quit it in Activity Monitor, then open Supbuddy again. A running app that could not open its hand-off socket (for example, its state folder's path is too long for one) cannot be asked, so the new launch leaves without the alert after about 5 seconds. To run a development build, quit the installed app first: both use the same daemon. During an update, the app on its way out stops taking the daemon's password prompts and confirmations as soon as it begins to exit, and gives them up then, as it does when you quit: from that moment none is sent to it, nor handed back to it. A password prompt raised before the relaunched app has taken them over waits for it (up to 15 seconds); a keychain read or a confirmation is handled by the daemon, as when no app is attached. An app the daemon told that another app has taken them no longer takes them back with its background checks; it does again when it reconnects or the daemon asks.

After the app updates itself, it replaces an outdated daemon. The daemon is detached, so it survives the app relaunching — without this the app would look updated while still running the previous version's worker, and any fix shipped in that worker would silently not take effect. On launch the app compares the running daemon's version (stamped into daemon.json) against its own: an older daemon is stopped and replaced, and a newer one is left alone and attached to, since an out-of-date app must not downgrade a running worker. The app's window then says so in a strip under the title bar ("This app (v…) is older than the Supbuddy daemon it is using (v…). Some of its requests may be refused. Update the app."), with Check for updates: a newer daemon refuses some requests an older app still sends. The window checks again each time it reconnects, so a daemon a newer app started after launch is noticed too. Only a daemon an app started records its version; one run from the npm CLI (supbuddy daemon) or a login service records none, and shows no strip. If the daemon ignores the graceful stop, the app forces it rather than carrying on as though the stop had worked — attaching to the daemon it just judged stale is exactly how an updated app ends up running old code, and the replacement spawn would be refused anyway ("already running"). Shutdown is bounded from the other side too: every stop step has a timeout and the worker exits even when a service refuses to stop, because a daemon that cannot be stopped cannot be updated. A forced shutdown may leave Caddy briefly running; the health monitor reaps it and the replacement daemon takes over.

Run on login (service)

supbuddy service install        # start-on-login (launchd on macOS, systemd-user on Linux)
supbuddy service status
supbuddy service uninstall

Commands

All app surfaces have a command. Names follow supbuddy <module> <action> [args] [--flags]. The main groups:

GroupExamples
Dev launcherrun [--print] -- <dev command>: on a Thin project, binds the dev server to the project's loopback IP, asked from the daemon (SUPBUDDY_LOOPBACK_IP=127.0.0.N runs without Supbuddy), so it keeps its canonical port (e.g. supbuddy run -- next dev stays on :3000)
Health / proxystatus, doctor [--fix] (health & drift scan — see System doctor), ready [<proj>] [--fix] [--only=<category>] (can a project run? — see Project readiness (supbuddy ready)), reset [--tier=soft|deep|full] (tiered system reset — see System reset), proxy status|start|stop|restart. proxy start and proxy restart bring up the DNS server too (and mDNS, with LAN sharing) and rewrite resolver files that no longer match, which asks for a password; proxy restart also rewrites a port-forwarding anchor that no longer matches and repairs port forwarding that is on but not enforcing, each behind a password prompt too. Both wait up to 12 minutes for the daemon's answer (--timeout overrides it). proxy start exits 1 when the DNS server or that rewrite failed, proxy restart when the DNS server did. Neither turns port forwarding on or adds loopback aliases (the privileged setup): that is Start in the app; a restart only repairs port forwarding that is already on. proxy stop stops Caddy only; the DNS server keeps answering
Mappingsmap ls|add|get|set|enable|disable|rm|restore. add, set, enable, disable, rm and restore wait up to 12 minutes for their answer (--timeout overrides it): re-applying the resolver files can ask for a password
Projectsproject ls|add|get|scan|set|enable|disable|rm|restore|env|refresh-context. project restore <id> [--no-children] restores a project from the trash, without its mappings with --no-children. project add <path> [--isolation=thin|host]: a relative <path> is resolved against your current directory. Without --isolation the daemon uses Settings → Default isolation and keeps on Host a project whose own Supabase already runs on the host; --isolation=thin skips that check, and any other value is refused before the daemon is asked. project add, set, enable, disable, rm and restore wait up to 12 minutes for their answer (--timeout overrides it): re-applying the resolver files can ask for a password, and add of a Thin project can ask for its loopback alias first
Supabasesupabase start|stop|restart|status <proj> (add --follow to stream live progress), supabase config apply <proj> <file>. status shows the project's last recorded Supabase failure, as its card does, under the CLI and Docker line: ✗ Supabase start failed: <why> (or stop, restart), or ✗ Supabase stopped, not prepared: <why> for a switch to Thin that stopped the stack and could not prepare it; --json has it as supabase_error
Cloudcloud login <email> [<pw>] (or SUPBUDDY_CLOUD_PASSWORD), cloud push <proj> [--repo=owner/repo] [--force], cloud status [<proj>], cloud teardown <proj> — push a project (with its Supabase data) to a hosted cloud stack; project ls marks pushed projects with ☁
Composecompose up|down|restart|status|logs <proj> [svcs]
Scriptsscripts ls|start|stop|restart|logs|bookmark <proj> [script]
Isolationisolation switch <proj> <host|thin>, isolation pending-migrations, migrate start|finish <uuid>
Certificatesca status|install|uninstall
Env filesenv copy <src> <key> <target>, env write <path> <K=V>… (each with --project <id|name> to hold the paths to it)
Settingssettings get, settings set <key>=<value>… (true / false and plain integers — digits with an optional leading -, within JavaScript's safe range — are sent as booleans and numbers, anything else as text, 1e3 and 1.5 included: supbuddy settings set lanSharing=false), settings set --json <patch> (both wait up to 10 minutes for their answer: a LAN-sharing change can queue behind an open admin prompt, then restarts Caddy; --timeout overrides it)
MCPmcp add [<agent>] (register Supbuddy into a coding agent: interactive, or --write/--print/--prompt), mcp ls, mcp revoke <id>, mcp approvals apply|cancel <id>
Host / networkconnect, trust, tailscale, dns, pf (port-forwarding)
Logslogs requests [-f], logs audit [-f], logs get <id>
Accountaccount, caps, addons scaffold|seed <proj>
Dashboardtui (alias dash), shell (alias menu) — see Live dashboard (TUI)
App updateupdate [--yes] [--no-restart]: updates /Applications/Supbuddy.app from supbuddy.app, from a terminal. Before anything is replaced, the new app must be Supbuddy at the version offered and newer than yours. It must also be signed by Supbuddy's Apple team, pass codesign --verify, and be accepted by Gatekeeper. A swap that fails puts the old app back. Works from the CLI inside the app and from the npm CLI (npx supbuddy@latest update); the npm CLI itself updates with npm install -g supbuddy@latest. A bare npx supbuddy@latest offers this when your app is outdated

Global flags: --json (machine-readable output), --yes (skip confirmations), --quiet, --url/--token (attach to a specific/remote daemon instead of auto-discovery; --url=… or --url …, and the same for --token), --state-dir (override the shared dir), --timeout, and -f/--follow for streaming log commands and live supabase start|stop|restart progress. Flags go after the command: a flag in its place (supbuddy --url=… status) is refused, naming the flag and never its value. A --url that is not an http(s) URL, or carries a user name or password, is refused before anything is sent, and its value is never printed: --url is not an http(s) URL (e.g. http://10.0.0.2:9877), or --url must not carry a user name or password: pass the token with --token.

When the daemon refuses a call, the CLI prints its reason and exits 1. An argument the daemon's schema rejects names each field and why (Error: Argument validation failed: domain: must be a domain name: it must have at most 63 characters between dots), and a token without the scope a command needs names the tool and the scope. The daemon's own refusals read the same way: a request body over 1 MB (Error: Body > 1MB), an unknown path, a foreign Host header, a body that is not JSON, and an unexpected error it catches before it has started answering. A refusal that carries no reason still prints mcp http <status>. A control character in a reason (ESC, BEL, a C1 control) is printed escaped, as \u001b, so a reason can't drive your terminal; the dashboard does the same.

Destructive operations go through the same plan → apply gate as MCP (see Plan / apply for destructive tools); the CLI's control token is granted auto-apply, so they execute directly.

Live dashboard (TUI)

supbuddy tui        # the full-screen dashboard; alias: dash
supbuddy shell      # the interactive picker; alias: menu

tui opens a full-screen terminal dashboard that attaches to the running daemon and shows live connection/proxy status, the project list (with each project's isolation, Supabase, and Compose state), the mapping count, and a tail of recent requests. A read the daemon refuses or fails is named in red with its reason (projects: Tool list_projects requires scope read) while the rest stays live, and a request log that fails, is refused or is closed by the daemon says so in its own panel (! request log stopped: …). Press r to refresh, q to quit. It needs a running daemon (supbuddy daemon --detach); if none is found it tells you so. With --url (and --token) it attaches to the daemon at that address, a daemon on another machine included: its connection line shows that address's origin (no path), and every panel is filled from that daemon, whatever a local daemon.json says. A SUPBUDDY_DAEMON_URL in its environment does the same. An address that is not an http(s) URL, or that carries a user name or password, is refused before anything connects, and its value is never printed: the header says Supbuddy ○ not connected, and the line below names where the address came from and why, --url is not an http(s) URL (e.g. http://10.0.0.2:9877) or --url must not carry a user name or password: pass the token with --token (SUPBUDDY_DAEMON_URL … when it came from the environment). The header says Supbuddy ○ connecting… until the dashboard has connected, and Supbuddy ● connected … only while the daemon answers its reads (a read the daemon refuses is an answer). When none is answered — a wrong address, a daemon that stopped — it says Supbuddy ○ http://10.0.0.2:9877 (no answer) instead, or (token refused) when the daemon refused the token (HTTP 401), and the line below adds the daemon refused the token (HTTP 401): pass the right one with --token. It goes back to ● connected at the first poll the daemon answers.

shell opens an interactive picker over the same command tree — modules on the left, that module's actions on the right, type to filter. The command you choose runs in the parent shell, so its output lands in your terminal rather than scrolling past inside a full-screen app. A bare supbuddy, or a bare module like supbuddy proxy, opens the same picker when you are on a terminal. To list the projects or mappings an action can take, the picker asks the daemon the chosen command will run on: the local one, or the one supbuddy shell --url=… --token=… names (and --state-dir=… too; a bare module such as supbuddy proxy --url=… takes them as well). The command runs with those same flags, and the $ supbuddy … line it prints shows the address's origin and never the token. A SUPBUDDY_DAEMON_URL or SUPBUDDY_BOOT_TOKEN in the environment steers neither the picker's list nor the command it runs. The dashboard still honours them wherever it is opened from, the picker's tui included, as supbuddy tui does. A --url that is not an http(s) URL, or carries a user name or password, is refused before the picker opens, and the value is never printed.

It ships in every build, including the npm CLI — which is the point, because an SSH, CI or server box has the CLI and nothing else. The dashboard and the picker are a React/Ink program bundled into a single ~550 KB file (tui.js) that sits beside the CLI in the package, so npm install -g supbuddy is all it takes and nothing extra is downloaded at runtime. It adds no runtime dependencies. If an install is incomplete and that file is missing, tui, dash, shell and menu say so and exit non-zero rather than exiting 0 having done nothing, and they are left out of that install's --help and shell completion.

Both need an interactive terminal. They take over the terminal and put stdin into raw mode, so when stdin or stdout is not a TTY — piped, redirected, or a CI job — tui, dash, shell and menu print why and exit non-zero instead of half-rendering a frame and reporting success for a screen nobody can see. On those boxes use the non-interactive commands below, with --json where a script is reading.

Without the TUI, supbuddy status, supbuddy project ls, supbuddy map ls and supbuddy logs requests -f report the same information, as does the desktop app window.

System doctor

supbuddy doctor                              # scan, repairs nothing; prints findings by severity
supbuddy doctor --fix                        # scan, show the repair manifest, confirm (y/N), then apply
supbuddy doctor --fix --only=ca-not-trusted  # restrict repairs to specific check ids (comma-separated)
supbuddy doctor --fix --yes                  # skip the interactive confirm (scripting / CI)
supbuddy doctor --forget-import=<token>      # free a failed import's folder, removing nothing (see below)
supbuddy doctor --confirm-quiet=<id>         # free a folder held after a stop, once nothing of it runs there (see below)
supbuddy doctor --forget-sync-check=<id>     # forget a deleted project's owed cloud sync check, or one its delete waits on, stopping nothing (see *Live sync*)

supbuddy doctor runs a health and drift scan that never repairs or changes the system, and prints its findings grouped by severity — critical, warning, info — each with a title, a one-line detail, and concrete evidence (paths, container names, certificate fingerprints). The scan changes nothing on the system, so you can gate a script or CI on it. The one thing it may record is what it learned about the CA: the last root this Mac was seen trusting, kept in Supbuddy's own settings so a changed root can be told from a new one.

Exit codes. A check that can't run is an unknown, not a clean bill of health — so the scan reports "I couldn't look" separately from "I looked and it's fine":

CodeMeaning
0The scan completed and found nothing critical
1Critical findings — something is definitely broken
2The scan could not complete — one or more checks never ran (see SCAN ERRORS in the output), so the result is an unknown

Exit 2 covers cases that used to (wrongly) exit 0: with Docker stopped, for example, every Docker-backed check fails to run, and a 0 there would tell CI the machine was healthy while part of the scan was blind. A critical finding outranks an incomplete scan — if both apply you get 1, because that's the actionable one. Gating on "non-zero" catches both; check for 2 specifically if you want to start Docker and retry rather than fail the build. These codes apply to --fix too: a run where every repair applied but part of the scan never ran also exits 2.

--fix re-scans, prints a manifest — one line per fixable finding, taken from the scan you just saw — and, unless you pass --yes, asks Apply these fixes? [y/N] (default No) before touching anything. (The desktop app's doctor panel shows the finer-grained repair actions themselves; the CLI lists the findings those actions belong to.) --only=<comma,ids> restricts the repair to specific check ids; --yes skips the prompt for non-interactive use. This is the confirm-before-harm contract: the scan never repairs or changes the system (it may record what it learned about the CA), and every repair is opt-in and gated. Fixes that need elevated access prompt for your password when they run.

A repair that ends up doing nothing is reported as such, never as success: if a requested check's finding is already gone, is advisory, can't be re-checked, or names an unknown id, it's listed under NOT APPLIED and the command exits non-zero.

An aborted --fix also exits non-zero (1). Declining the confirmation applies nothing, so every finding is still there — exiting 0 would tell a script the machine was fine when it had just been reported as critical. This matters most where nobody actually declined: with no TTY to prompt on, --fix refuses on principle (confirm-before-harm), so a scripted run prints aborted — no fixes applied and stops. Pass --yes to run it unattended. A daemon-side denial of the confirmation has always exited 1; the same outcome now gets the same code regardless of which side refused.

The daemon's own confirmation says what it came to. doctor --fix asks the daemon to apply the fixes, and the daemon confirms on its side (see Confirmations, and why one came back without a yes). When that doesn't come back yes, the command exits 1 and prints one of three lines: declined on the host when a person said no; nobody answered the confirmation in time; the dialog may still be open on the host; or nobody on the daemon's side could answer the confirmation, followed by how to get asked (open the app, or run a foreground supbuddy daemon in a terminal). Only that last case gets the setup advice. supbuddy ca install answers its own confirmation the same way (ca install: …, on stderr), followed by a changed root's screen-session steps, numbered.

A repair whose password prompt failed says which way. In the Results list, such a line reads ✗ <action> — <what happened to the prompt>: <message>, where what happened is one of: the admin prompt was refused; no admin prompt could be shown: open the app, or run the daemon in a terminal; the admin prompt timed out (it may still be open); the app went away before the admin prompt was answered (it may still be open); or the privileged command failed (it ran and did not succeed, could not be started, or could not be sent to the host). A failure that wasn't a password prompt (a check before it, a file that couldn't be read, a re-check afterwards) shows its message alone. The app's System health panel shows the same words.

Rows marked Advisory have no auto-fix at all: --fix will never touch them, and the finding's detail tells you what to do by hand. Checks marked macOS return nothing on other platforms.

Check idSeverityWhat it flagsAuto-fix
state-corruptcriticalstate.json can't be parsed (or isn't an object), so the daemon boots with empty state — no projects, mappings, settings or MCP clientsCopies the file aside as state.json.corrupt-<timestamp> so you can hand-recover it. Nothing is deleted or rewritten
dns-not-resolvingcriticalSupbuddy serves these domains but the OS will not resolve them, so every mapped URL fails before it reaches the proxy — a missing /etc/resolver file, a file that is there but sends lookups to another port than the DNS server's (the server moved, and the rewrite was declined or went unanswered), the local DNS server not answering, or (the case a file audit calls healthy) the files being correct while the OS has never loaded them. Leftover files for suffixes nobody uses are not this — they break no resolution and belong to stale-resolver-files. Uses the same verdict get_health and get_proxy_status use, so the three cannot disagree about one machineFixable when resolver files are MISSING (typically after a TLD change) or name another port: doctor --fix writes them and re-audits to confirm; supbuddy proxy restart and supbuddy proxy start write them too — except past 256 managed suffixes, the most resolver files Supbuddy writes, where neither is fixable and the detail says to disable or remove some projects or mappings. Advisory for the other two causes, where the only re-apply on offer is audit-gated and would elevate, change nothing and report success. A DNS server not answering: start the proxy — supbuddy proxy start, or Start in the app — which starts the DNS server. Files the OS has not loaded: Retry in the app (or Stop and Start there) reloads the resolver; supbuddy proxy restart does not, since it reloads only when its audit finds a file to rewrite. Then toggle Wi-Fi to force a rescan; the /etc/hosts fallback engages at the next proxy start in the app. On Linux the two fixable causes are a suffix with no route through systemd-resolved, and one listed in Supbuddy's configuration but not routed to its DNS server; doctor --fix sets the route up (again), asking through sudo in the terminal running supbuddy daemon — except past the 256-suffix bound, where neither is fixable and the detail says to disable or remove some projects or mappings. Two more causes, both advisory: systemd-resolved not running, or something that is not Supbuddy's in the way of its unit, drop-in or link, or in systemd-resolved's own configuration — the detail says which, and what fixes it; and a route in place whose names still do not resolve, where this machine most likely resolves around systemd-resolved (check that /etc/resolv.conf points at 127.0.0.53, or that /etc/nsswitch.conf's hosts: line names resolve)
dns-global-routewarningLinux. systemd-resolved lists Supbuddy's DNS server among its global servers, from a setting that is not Supbuddy's (/etc/systemd/resolved.conf, or another drop-in): names Supbuddy does not manage are sent there too, so while Supbuddy is stopped they resolve only through another DNS server systemd-resolved can use — and on a machine whose links have none, not at allAdvisory — no auto-fix. Nothing of Supbuddy's makes it. Remove the server from the file that names it, then sudo systemctl restart systemd-resolved; the finding goes with it
public-default-tldwarningThe default TLD is a real public suffix (.com, .dev, .app, any root-zone TLD), so every enabled project on it has a real internet name, and every lookup of those names on this machine, for every user, goes through Supbuddy: the real sites at those names can't be reached from it, and while Supbuddy is stopped they don't work at all (they don't resolve, or they resolve to this machine and fail to connect). Usually a TLD set before the app asked first. The finding lists the enabled projects on itAdvisory — no auto-fix. A new TLD renames every project's domain. Pick a private one (.test, .internal, .localhost) in Settings → General → Default TLD, then update anything you wrote the old domains into (.env files, allowed origins)
public-project-tldwarningA project's own domain, or a mapping's, is on a real public suffix other than the default TLD's (those are public-default-tld's), so it is a real internet name with the same effects on this machine. It lists the enabled projects on one, with or without mappings, and the served mappings on one that belong to none of them (manual ones, typically); disabled ones have no resolver file and are not listed. Usually saved before the app asked firstAdvisory — no auto-fix. A private TLD renames the project's domains. Set one (.test, .internal, .localhost) in the project's Edit dialog, or change a manual mapping's domain, then update anything you wrote the old names into
mappings-without-resolver-routewarningmacOS and Linux. A served mapping that no resolver route reaches, so nothing sends its lookups on this machine to Supbuddy and it doesn't resolve here, while the probes, which sample names with routes, say nothing. That is: a whole suffix (a public suffix itself, such as co.uk, or home.arpa), which Supbuddy never routes; a name whose route would not be a plain DNS name (my_app.test: an underscore, or a label over 63 characters), unless another mapping's route covers it (x.my_app.acme.test under web.acme.test's acme.test); and, while the /etc/hosts fallback is engaged, any name it can't hold as stored (a wildcard, an underscore, a trailing dot). get_health lists the same in dns.resolver.no_routeAdvisory — no auto-fix. Rename the mapping: a name under a whole suffix (app.co.uk), letters, digits and hyphens in the part a route takes (my-app.test), or a name under a domain another mapping routes. Caddy still serves it: curl --resolve, or an /etc/hosts line you add for each name, reaches it
dns-local-tld-mdns-stallwarningmacOS. Managed .local domains resolve fast once and stall ~5s per concurrent lookup — only the IPv6 (AAAA) half, so curl, a single fetch and dig all look healthy while a page issuing parallel requests fails with what looks like a proxy connect timeout. Supbuddy's own DNS server caused it until 3.5.18; it now answers AAAA with ::1, so this is a canary that should not fire.Advisory — no auto-fix. The check measures rather than lints — 8 parallel lookups against a real mapping — so it stays silent on a machine that is genuinely unaffected. If it fires: check supbuddy version (an updated app can be attached to an older daemon) and restart the proxy; if it persists, compare dig -p <DNS port> @127.0.0.1 AAAA for a .local name against one on another suffix — the finding names the port. Renaming domains is not the fix
proxy-not-servingcriticalThe proxy should be serving and nothing is — Caddy is not alive, so every enabled mapping is unreachable. It stays silent when Caddy is up but a privileged step failed (HTTPS still serves on the high port there, and pf-not-enforcing describes that state precisely) — two contradictory critical findings would teach you to ignore both. It reads the same derived status get_proxy_status does, so the two can never disagree about the same machine: a deliberate proxy stop and an in-flight auto-restart are not flaggedAdvisory — no auto-fix. The finding carries the tracked cause and names both routes back: supbuddy proxy restart (or Start in the app), and SUPBUDDY_ASKPASS when the cause is a privileged step that needs a TTY. Starting the proxy is the step that failed, so --fix would re-run the failing path
caddy-stuckcriticalCaddy is alive but its admin API is wedged, so config reloads can't landRestarts Caddy (stop → start)
caddy-ipv4-unreachablecriticalCaddy's loaded config declares an HTTPS listener but 127.0.0.1:<port> refuses connections — every IPv4 client is cut off (browsers, curl, and the pf 443→8443 redirect) while the process is up and its admin API answersAdvisory — no auto-fix. Run supbuddy proxy restart to rebind. Only a connection refused counts: a timeout on a pf redirect target is normal (the reply is reverse-NAT'd back to :443 and never matches your socket), so it is never reported as a fault
ca-not-trustedwarning"Local HTTPS certificate authority is not trusted." The local CA exists but the current root isn't trusted (the padlock stays broken): it is missing from the keychains, or there without trust (security verify-cert fails). Detection is by fingerprint and reads both the System and login keychains, so neither a stale same-name root from an earlier CA nor a per-user install is misread. A root that can't be read is reported as that, as advisory (no auto-fix — the installer refuses an unreadable root): Caddy doesn't replace a root that exists, so the detail says to move its folder aside and restart the proxy, then install the new one. Once the proxy has finished starting and there is no root it can read at all, it reports "The proxy is running, but its local CA root can't be read" (for a root that isn't there yet, only once Caddy's admin API answers too, so a scan during a healthy start stays quiet; the scan that runs after every proxy start looks again) — advisory, naming the root's path and why (no file there, or the read error) — and says to restart the proxy and, if that persists, check that Caddy's data folder is readable. With the proxy stopped, no root is not a fault: Caddy writes it on the first start. The finding points at Settings → General → CA Certificate → Install and MCP install_ca. On macOS, when the root is not the one this Mac trusted before (Supbuddy records the last root it saw trusted), the finding is instead "The local CA changed and needs trusting again (screen session)": still a fixable warning, with the steps for someone at the screen listed under it and carried as remediation ({ requires: "screen-session", steps }) — see Remote setup: what needs a screen session. Never on a first install, or when trust or the root can't be readRuns the same installer as that button (asks for your password — on macOS 15+ this becomes the per-user install with its own confirmation dialog). If the install can't finish, the steps to finish it by hand are shown under its line — in Last repair in the app, under the ✗ line in doctor --fix, as manualSteps over MCP. For a changed root whose admin prompt nobody could be shown or nobody answered, those are the screen-session steps. On Linux, a CA removal that was stopped (or is still running) before the store was rebuilt without it is reported as "A removal of the local CA has not finished": a warning, no auto-fix, saying to remove it again (supbuddy ca uninstall) to finish, or install it to keep trusting it. With no root it can read, it is reported all the same, the proxy stopped or not: a removal needs no root, there is nothing to install then, and the finding says what to do about the root after that. Where trust cannot be read at all (Windows, or an unreadable keychain) this drops to advisory, info, no auto-fix — it reports what to import by hand rather than offering a repair that can't run
pf-not-enforcingcriticalPort forwarding is configured but 443 isn't redirecting, so every https:// URL on the default port is unreachable. It first checks that the HTTPS port has a listener: with nothing serving behind the redirect a closed 443 says nothing about pf, so that machine gets no finding rather than a false oneFixable. doctor --fix turns pf back on if something switched it off, re-applies the pf ruleset (asks for your password) and then probes 443 to confirm — it reports success only if the redirect actually answers. By hand: sudo pfctl -e; sudo pfctl -f /etc/pf.conf ("pf already enabled" from the first is harmless). supbuddy proxy restart also re-applies it now, but only when a probe says it is genuinely broken, so an ordinary restart still prompts for nothing
duplicate-caddy-cawarningmacOS. Stale same-name Caddy Local Authority roots with a different key — the cause of Firefox-family SEC_ERROR_BAD_SIGNATUREDeletes the stale roots and installs the current one in a single elevated batch (asks for your password). Delete-only could leave a machine with no trusted Caddy root at all when the current one wasn't in the keychain yet
orphan-caddy-containerwarningA leftover pre-binary-era supbuddy-caddy Docker containerRemoves the container, its supbuddy-net network and its data/config volumes (the caddy:latest image is kept)
orphan-lo0-aliaseswarningmacOS. 127.0.0.N aliases on lo0, within Supbuddy's own range (127.0.0.2–254), owned by no project — deleting a Thin project never tore its alias down. A project of any isolation holding the IP owns it, and so does a trashed project or one being deleted: a Host project keeps the IP of its last Thin attempt and reuses it at its next switch to ThinRemoves only those aliases (asks for your password), re-checked against the projects when the fix runs: if a project was given one of them since the scan, nothing is removed and the fix says to scan again. 127.0.0.1, .0, .255 and any non-Supbuddy alias are left alone. While its password prompt is open, no project switching to Thin (or restored from the trash) is given one of those IPs. After a prompt that timed out or whose app went away, which may still be on screen, they stay out of use until a later scan sees them gone from lo0 (or the daemon restarts). If the fix is run again for them meanwhile, they stay out of use until the daemon restarts: lo0 can no longer show whether the first prompt's command has run
missing-thin-aliaseswarningmacOS. A Thin project's 127.0.0.N alias is missing from lo0 — every reboot removes them, and one whose prompt was declined or went unanswered was never added — so that project's dev servers cannot bind its address. An unreadable lo0 gives no findingAdds every missing alias with one password prompt. The app's proxy start (Start, Retry) and supbuddy run add them too; supbuddy proxy start does not
duplicate-loopback-ipswarningTwo or more Thin projects hold the same loopback IP, which a restore from the trash by Supbuddy 3.12.0 or earlier could do. Their dev servers bind one address, so two on one port collide, and one project's URLs can reach the other's server. Each line names the IP, the project that keeps it (the one registered first) and the ones that move. A Host project's kept IP and a trashed project's are not counted: neither binds it. Supbuddy never separates them on its own, because supbuddy run binds the IP once, when it starts a dev server, and a server already running would stay on the old IPMoves each later project, with its app mappings, to a free loopback IP (on macOS one password prompt adds the new alias first; if it does not succeed, nothing moves). Then restart that project's dev servers with supbuddy run -- <dev command>: until you do, its URLs reach nothing. If the projects sharing an IP changed since the scan, nothing moves and the fix says to scan again
duplicate-nameswarningTwo records Supbuddy keeps apart that run as one. Two mappings on one name, compared without regard to case, now or once the next start moves each onto its TLD: Caddy serves one, and a delete by name takes the first it finds. Deleting a project with a TLD of its own can leave such a pair, since the manual mappings it moved onto its TLD stay where they are; the delete goes ahead and says so. Each line names the name, both mappings (whose, port), and whether it is now or at the next start. Two projects on one Supabase stack: managed ids that an earlier version made longer than the 40 characters the Supabase CLI keeps, alike in those, so both run one stack with one database, and a Stop, a switch to Host or a disable of either stops the other's too. A Thin project counts, and a Host one whose switch did not finish (its config still carries the Thin block), or whose config can't be read, saying why. Each line names the stack and both projects with their idsAdvisory — no auto-fix. Rename or remove one mapping of each name. For a shared stack, a rename doesn't separate them (an id that long is kept), and a switch back to Thin shares it again: switch one of them to Host, and once that switch has finished it runs the stack its config named before Thin, the shared database staying with the other (start the other's Supabase again). If its card says the switch's stop failed, stop the stack as the card says and switch to Host again, without editing its project_id first; once restored, if that project_id runs as the same stack as the other's, give it another one
orphan-dindwarningDocker-in-Docker containers from the retired Isolated (VM) mode belonging to no registered project — each one confirmed to actually be a DinD firstForce-removes those containers and their <name>-docker data volumes. This is project data: if you deleted a project and chose to keep its data, this is that data. The Caddy container and non-Supbuddy containers are never touched
orphan-supabase-volumeswarningDocker volumes of Supabase stacks Supbuddy set up for a Thin project that is no longer registered. Supbuddy records each Thin stack's Compose project id (sb-<slug>-<id>) when it sets the stack up, and lists only ids it recorded that no live project, project in the MCP trash (restorable for 7 days) or project being deleted owns — by any id it uses, the one its own config.toml names and the one a switch back to Host would restore included. A project deleted with its data kept is no longer listed either, nor, for a delete made after Supbuddy 3.13.0 (earlier versions did not record it), is any stack such a delete used, even one another record still names. Once such a delete could not read its Supabase config or compose file, so which stack it kept cannot be told, the leftovers are listed with no fix offered from then on, and the finding says one of them may be that delete's data, naming its project's id; supbuddy reset also forgets the recorded ids. The sb- prefix alone is not enough: a Compose project you named sb-… yourself, an imported bundle's, and a Host-mode stack are never listed. Neither is a stack whose project was removed while Supbuddy 3.12.0 or earlier was running, since those did not record the ids: remove those with docker volume rm if you no longer need them. Also notes, as info (also when Docker isn't installed), a deleted Thin project's block left in a Supabase config when its restore was given up (another project used that file or that stack, another owner held its folder by then, or a delete with its data kept used it), once no registered or trashed project uses that config: each line names the config, the block's project_id and ports (a mail port as the config's own section spells it), and the original project_id and ports to set back by hand, or says to leave it when a project deleted with its data kept used that config or its stackRemoves those volumes, after checking again that nothing uses the id. This is database data, of no project now: a project deleted with its data kept is never listed. A kept config block is never changed: do what its line says, by hand
failed-import-leftoverswarningA bundle import failed and its rollback could not prove that everything it made is gone, so its folder is still reserved (registering it, importing into it, and a read or write there by a project it is inside are refused; a project registered inside the folder keeps its own). Each one is listed with what its rollback left. Also reports a failed import's record file (failed-imports/<id>.json) that cannot be read: the folder it held is no longer known — check it and Docker by hand, then delete the fileRuns the import's rollback again from its record: removes its restore helpers, volumes, files and folder, each only once it still carries the import's identity (its label, or a file's identity and content), and frees the folder once nothing of the import's is left. Removes only the containers and networks the import's own start created, by the full ids it recorded, and only while no other project runs as that Compose project (registered, in the trash, being deleted, or whose folder is still being released). While any other container or network of the project exists, it names the command that stops them and keeps the folder. A record it cannot replay is only checked, nothing removed. An unreadable record file is never touched. It never forgets a record: when what is left can never be proven gone, supbuddy doctor --forget-import=<token> frees the folder, removing nothing, after you confirm it
orphan-launchagentswarningmacOS. Legacy CA-trust LaunchAgents from older builds that re-export SSL_CERT_FILE / REQUESTS_CA_BUNDLE / NODE_EXTRA_CA_CERTS at every login and break public TLSBoots each agent out and removes it, leaving a .supbuddy-backup copy alongside. Root-owned agents under /Library may resist; the fix reports those as a failure instead of claiming success
orphan-electron-token-fileswarningLeftover ~/.config/Supbuddy/mcp/<clientId>.bin token files from the retired Electron app, for clients that no longer existDeletes those files (no elevation). They can't be decrypted any more anyway; clients that are merely revoked keep their record and are left alone
orphan-mcp-secretswarningsecrets/mcp-<clientId>.secret files whose token can no longer authenticate (client revoked, or no record at all)Deletes those files (no elevation) — it can't log a working agent out. Secrets for current clients, and the non-MCP secrets stored alongside them (license, cloud session, Tailscale key), are left untouched
projects-not-readywarningRegistered projects that wouldn't actually run — dependencies never installed (or a lockfile newer than the last install), or Supbuddy's Supabase connection vars missing from the env file the app loads. One aggregate line, never one finding per project, with project names only as evidence. A project whose folder is gone is skipped; one Supbuddy couldn't read is listed as (could not be scanned) rather than passed as healthyAdvisory — no auto-fix. It points at supbuddy ready and the project card, which carry the specific finding, the file it names and the one-click fix. Doctor installs nothing
steps-waiting-for-folderswarningA step waits for a project's folder that doesn't answer (a stalled network or cloud mount): a delete a stop interrupted, which the start resumes only once every folder answers, the end of a delete whose own folder, config, Compose files or .env don't answer, which records what it used and frees its folder only then, the Compose containers a stopped release left, a step a delete left for later (a Thin restore, the removal of a Supabase stack's data volumes), the others waiting behind it, or the check of the cloud sync sessions that outlived the last stop, which holds every cloud-linked project's Thin block until it runs. Each line names the step, the folder, and since when, and for that check the projects whose blocks it holds. It reads no folder, so it runs while that folder stops every other checkAdvisory — no auto-fix. Each goes on by itself once the folder answers, asked every minute, and the check of the cloud sync sessions as soon as it answers: reconnect it. No line suggests unmounting it: unmounted, a Supabase config there looks gone, and the step would remove what it still names, or leave its Thin block in it. Stopping the live sync of a project whose folder answers checks it at once, and frees its block for the rest of the wait. A restart is no way out: an interrupted delete waits again at the next start, and a step left for later is dropped for good, its work undone. A delete's own cleanup that waits for a folder is listed under folders-still-releasing
folders-still-releasingwarning / infoA folder a deleted, expired or moved project left is still held by its release: a part of it did not stop (warning, at once), or the hold has lasted two minutes (info). Each line names the folder, the project, how long, and what it waits for or how to stop it by handAdvisory — no auto-fix. Freeing the folder while what holds it may still write there is what the hold prevents. Stop what is named, and Supbuddy's next try (every minute) frees it. Stopping Supbuddy before then does not free it: at the next start, a folder whose dev servers, installs, Compose starts or seeds were not yet confirmed stopped (a delete's, a trash expiry's, a move's or the system wipe's) is held again, at once as a warning, until you confirm nothing of it runs there any more (it is not retried): its line names the command, supbuddy doctor --confirm-quiet=<id> (MCP confirm_folder_quiet), which shows the folder and why, asks, and frees it; in the app, Confirm quiet… under the finding does the same, after showing the hold's text. The finding lists those folders as confirmQuiet ([{ id, root, name }], in MCP doctor and supbuddy doctor --json too). Nothing is stopped for you then, since a process group number can be reused. A delete's or trash expiry's runtime cleanup is resumed at the next start too, holding the folder while it runs, and so is its wait for its cloud sync to be checked again ("could not be checked again", "still being checked"), until the file synchroniser answers; supbuddy cloud sync stop <id> or MCP cloud_sync_stop with the project's id checks at once, and the next try frees it. A folder held both ways has a line for each, each with its own way out, and is free only once both have ended. For a folder a project moved out of, a restart ends the cloud sync wait, but not the hold that waits for you to confirm it is quiet. A delete's step that waited for a later delete (its Thin restore, or the removal of its Supabase data volumes) is not saved: a restart drops it for good, leaving what it had still to do — the volumes, which orphan-supabase-volumes lists, and its Thin block in the config
unmanaged-supabaseinfoA Supabase stack on the host daemon that maps to no registered project (e.g. a plain supabase start). A project's stack counts as known through its saved Supabase project id, its Thin managed id, or the id its own config.toml (in its Supabase folder) runs its stack under: its project_id, or with none the name the Supabase CLI gives that folder (My_App for My App, and the real folder's name for one registered through a link), for live, trashed and being-deleted projects alikeAdvisory — no auto-fix. Supbuddy never tears down a stack you started yourself; run supabase stop in its project if you don't need it
stale-resolver-filesinfomacOS. Supbuddy-marked /etc/resolver/<suffix> files for suffixes no enabled project or mapping claims any more (deleted projects, a disabled one, an older per-project TLD)Removes only those files (asks for your password); suffixes still in use are left alone. Reversible — enabling the project or restarting the proxy writes the file back
stale-hosts-fallbackinfomacOS. A Supbuddy /etc/hosts fallback block is present, but no enabled project or mapping serves a name that would go in it. The usual cause is a password prompt from before a reset --tier=deep, approved after it. Those names resolve to this machine and fail to connect. Or the block is present with the fallback off while this Mac loads /etc/resolver for every suffix the block would serve (a name /etc/hosts cannot answer resolves to this Mac, for each suffix, as Supbuddy's DNS answers it — 127.0.0.1, ::1; an answer with any other address, from a network whose DNS answers every name, proves nothing; never judged when the block serves a name under a public TLD, whose own DNS could answer that lookup): an earlier version turned the fallback off while it could not read /etc/hosts and left the block, which goes on answering its names, removed mappings' includedAdvisory — no auto-fix, in both cases. A removal approved late could delete a block a newer proxy start needs, or has taken back. Delete the marked block from /etc/hosts with sudo; Supbuddy writes it again only if this Mac stops loading /etc/resolver. For a block no name needs, supbuddy reset --tier=deep also removes it and confirms it is gone (it also empties the project list, but keeps your data). With an empty or unloaded project list the finding says so — the names may belong to projects the list lost
pf-conf-backupsinfomacOS. /etc/pf.conf.backup.<timestamp> copies piled up in /etc by older versions (which wrote a new one on every port-forwarding disable)Removes the redundant copies, keeping the newest one and the stable /etc/pf.conf.supbuddy-backup (asks for your password)
stale-mcp-config-tokensinfoAn agent config (~/.claude.json, Claude Desktop, Cursor, Codex, Windsurf, or a registered project's .mcp.json / .cursor/mcp.json) holds a mcpServers.supbuddy token Supbuddy no longer accepts — the 401 "Token not recognized" stateAdvisory — no auto-fix. Supbuddy won't rewrite config files you own and edit. Delete the mcpServers.supbuddy entry from the file named in the finding, or run supbuddy mcp add <agent> to mint a fresh token. The finding names the file, never the token
tracked-mcp-config-tokenswarningA registered project's .mcp.json, .cursor/mcp.json or .continue/mcpServers/mcp.json holds a mcpServers.supbuddy token, and git tracks the file, so a commit puts the token in the repository's history and a push shares it. Since 3.16.0 an install refuses such a file, but one written before, or an entry someone committed, stays. Git is asked only where a .git is at or above the fileAdvisory — no auto-fix. The file is the team's. Revoke each client Supbuddy still accepts (supbuddy mcp revoke <client_id>, named in the finding), remove the supbuddy entry, and if the file isn't meant to be shared, untrack it (git rm --cached) and commit that. The finding names the file (and where it leads, for a link), and the client when the token is one Supbuddy knows, revoked or not, or says no client record matches; never the token
user-mcp-config-tokens-in-gitwarningOne of your own MCP clients' configs (~/.claude.json, ~/.cursor/mcp.json, Claude Desktop's, Windsurf's or Codex's), its Supbuddy backup, or a staging copy of either, holds a mcpServers.supbuddy token, and a git work tree, a dotfiles repository say, tracks the file or doesn't ignore it. Since 3.20.0 an install writes no token where git would commit it, but one written there before stays. Git is asked where the file's bytes are (a stowed ~/.claude.json is a link into the repository, and is named with where it leads), and only where a .git is at or above them; a git that doesn't answer any of its questions reports nothing. Names the file and the client, never the tokenAdvisory — no auto-fix. The file and the repository are yours. Revoke each client Supbuddy still accepts if it may have been committed or pushed (supbuddy mcp revoke <client_id>). Then, where git tracks the file, untrack it (git rm --cached, the file a link leads to) and commit that; tracked or not, ignore it in that repository; and install the client again
compose-project-name-differswarningA registered project's Compose stack has another name for Supbuddy than for a plain docker compose run in its folder. Supbuddy takes the base file's name: first, then the .env's COMPOSE_PROJECT_NAME, then the folder's name; Compose takes the .env's first, then an override file's name: (compose.override.yaml and the like), then the base's. Its start, stop and listing then reach another stack than a docker compose typed there (with no COMPOSE_* variable set in its shell), and a Stop can miss a stack started by hand. Not judged: a folder that isn't answering, or whose Compose files or .env can't be read or parsed, or whose .env is a link, symbolic or hard; a name Compose would take otherwise than Supbuddy can tell, from a ${…} in it, a .env that sets COMPOSE_FILE, a COMPOSE_PROJECT_NAME line with export, a comment, an escape, an empty value or given twice, or a .env name Compose would refuse (a file's name: is normalized, as Compose does). Each folder is bounded at 5 s and the check at 30 s, and a folder whose read hasn't finished isn't read againAdvisory — no auto-fix. Supbuddy keeps its own name (SUP-400: following Compose's would leave a stack running under the old one behind). Make them one: first stop both, Stop in Supbuddy and docker compose down in the folder, then set the base Compose file's name: to the name you want, and remove what overrides it (COMPOSE_PROJECT_NAME in the .env, or the override file's name:). The finding names each folder, both names, and where Compose's comes from
project-mcp-token-excludeswarningA registered project's .mcp.json, .cursor/mcp.json or .continue/mcpServers/mcp.json holds a mcpServers.supbuddy token, git doesn't track it, and the repository's own excludes (.git/info/exclude) lack Supbuddy's lines for it: an install made by 3.16 to 3.19 wrote them into the .gitignore only, so a git stash -- .gitignore, or a branch without the line, would leave the token one git add -A from a commit. A file a .gitignore ! line takes back is named with that line too, as the line outranks the excludes, and so is one git still doesn't ignore with the excludes there, in git's words (a ! line in a deeper .gitignore). Names the file and the excludes, never the tokenFixable only for a file that lacks the lines: adds Supbuddy's lines for it to its repository's own excludes, as an install does now, changes nothing else, and then asks git, failing if git still doesn't ignore it. A file a ! line takes back is left alone: remove or narrow that line, commit that, and run the doctor again
codex-mcp-header-keywarningCodex's [mcp_servers.supbuddy] sets its Authorization under headers, which Codex silently ignores (it reads http_headers). Codex and the ChatGPT desktop app then connect with no token and show no Supbuddy tools. Supbuddy wrote this up to 3.8.2.Renames just that key to http_headers, changing nothing else, with a backup kept. A reinstall from Settings → MCP fixes it too. The finding names the file, never the token
stale-browser-nss-rootsinfomacOS. A Firefox / Zen / LibreWolf / Waterfox profile whose own NSS store (cert9.db) holds a Caddy Local Authority root Supbuddy can't reachAdvisory — no auto-fix. Nothing is wrong unless that browser shows certificate errors. Fix it there: Settings → Privacy & Security → Certificates → View Certificates… → Authorities, delete every Caddy Local Authority entry, then re-import Supbuddy's CA
browser-secure-dnsinfomacOS and Linux. A browser set to resolve through DNS-over-HTTPS, which can send lookups past this machine's resolver: the Chrome family (Chrome, Chromium, Brave, Edge, Vivaldi, Arc) with "Use secure DNS" on a chosen provider (dns_over_https.mode: "secure" in Local State), or a Firefox-family profile (Firefox, Zen, LibreWolf, Waterfox; Snap and Flatpak too) on "Max Protection" (network.trr.mode 3) that doesn't exclude every served suffix. Not reported for .local names in the Chrome family (it resolves them through the system), nor in a Firefox profile that keeps its built-in local exclusion, nor while the /etc/hosts fallback is active (both read that file first), nor for Chrome's "With your current service provider" or Firefox's Increased Protection. It can't see an enterprise policy, a system-wide DNS-over-HTTPS profile, or the network search suffixes Firefox sends to the systemAdvisory — no auto-fix. Nothing is wrong unless that browser is the one where a mapped name fails. See A mapped name works with curl but not in the browser

The same scan and repairs are available over MCP as the doctor and doctor_fix tools (see MCP tool surface), and in the app under Settings → General → System health → Scan — the panel scans on open, groups the findings by severity, and gates every repair behind the same manifest + confirm step (see Settings reference → General). The panel has no reset button: a wipe stays a CLI operation.

Project readiness (supbuddy ready)

supbuddy ready                               # every registered project
supbuddy ready acme                          # one project (id, or an unambiguous name)
supbuddy ready acme --fix                    # show a manifest, confirm (y/N), then apply each fix
supbuddy ready acme --fix --only=deps        # deps | env | toolchain | network
supbuddy ready acme --fix --yes              # skip the interactive confirm (scripting / CI)
supbuddy ready --json                        # machine-readable

supbuddy ready answers "can this project actually run?" — see Project readiness for what it checks. It is presented like supbuddy doctor: findings grouped by severity (ERROR, WARNING, INFO), a [fixable] marker, evidence indented beneath each finding, and a SCAN ERRORS block for projects it could not scan. Without --fix it mutates nothing.

--fix differs from doctor --fix in one way that matters: doctor sends a list of check ids back to one repair tool, while each readiness finding already names its own tool and arguments, so ready --fix calls that. A yarn project gets yarn install, a pnpm project pnpm install, an env finding gets apply_env — the CLI picks none of it. You see the manifest of what will run before anything does; n (and a non-interactive terminal without --yes) aborts having changed nothing.

Because an install is a job rather than a call, --fix then follows the install log to completion and takes that job's outcome as the fix's outcome, so the command blocks with live output instead of exiting 0 over an install that is still resolving.

Exit codes mirror doctor:

CodeMeaning
0Ready — no error-severity findings
1An error-severity finding, or a fix that failed
2The scan could not complete (see SCAN ERRORS), so the result is an unknown

--only narrows the verdict as well as the view: a run filtered to deps exits on the deps findings alone, because a command that printed three findings and exited on a fourth it never showed you would be lying. A project with nothing left in the category prints acme: no deps findings ✓. A dependency install that is running counts too: while it runs, the missing-dependency finding it will fix is hidden from the list (the project prints installing — …), and --only=deps still exits 1 on it, as ready without --only does; a hidden stale-install warning does not. A daemon older than this CLI does not say what it hid, so there --only=deps exits 1 for any running install of a project that is not ok.

With --json, each project's readiness.ok stays the full scan's, so a script that reads it still fails on any error. A filtered run keeps only that category in readiness.findings and readiness.hiddenByInstall, and adds only beside it, with the verdict on that category alone — the one the exit code uses:

{ "id": "p1", "name": "acme", "readiness": { "ok": false, "findings": [ … ] }, "only": { "category": "network", "ok": true } }

Without --fix, the run exits 1 exactly when some project's only.ok is false. Under --fix, only.ok is the scan's from before the fixes, and the exit code is the fixes' outcome, as always.

Related: supbuddy project ls now shows a project's connection-env verdict (env missing / env stale / env refused, when Apply can't update the file where it is) on its sub-line. It was previously hidden from that list entirely, so the CLI could not tell you the one fact that explains why an app 500s against a stack that is up. Only the verdict is printed — never the target path or a KEY=value — for the same reason readiness evidence never carries values.

System reset

supbuddy reset                        # soft (the default): app state + caches
supbuddy reset --tier=deep            # + services, Caddy containers, system integrations, CA trust
supbuddy reset --tier=full            # + project data, repo artifacts, secrets, service, app data
supbuddy reset --tier=deep --yes      # skip the y/N confirm (scripting / CI)
supbuddy reset --tier=full --yes --i-understand   # the ONLY scripted path for a full reset

supbuddy reset removes Supbuddy's footprint from your machine in tiers, and each tier is a superset of the one before it:

TierWhat it removes
soft (default)Stops the dev servers Supbuddy started (it is about to forget which project owns them), then resets app state — projects, mappings, settings, MCP clients, project-context sync and user-skill records — plus the Docker image cache (<app-data>/image-cache, images are re-pulled on demand) and the buffered request log. It also removes the user-level skills it installed (~/.claude/skills/supbuddy/, ~/.cursor/skills/supbuddy/, ~/.agents/skills/supbuddy/), only where Supbuddy's own record shows it wrote the file; the manifest lists each one. A skill file a project also routes there is not removed by this step: the next start's cleanup removes it with the forgotten projects. A skill whose file can't be removed is named in the reset's report and kept as installed so you can remove it again from Settings → AI Skills; the rest of the reset still completes. It touches no Docker container or volume, nothing under /etc, and no file in your repos, so it never asks for your password
deep…plus: stops every service; removes the leftover Caddy container/network/volumes, both /etc/hosts blocks (the legacy # Supbuddy - Start one and the # Supbuddy DNS fallback one), the /etc/resolver files (every stop keeps those and the fallback block — this tier is how they go; it re-reads /etc/hosts afterwards and fails, rather than passing, if the block is still there or the file can't be read), the pf :80/:443 redirect, the 127.0.0.N loopback aliases, the bundled-runtime CA trust and the Caddy Local Authority roots in your keychain, and the token files of already-revoked MCP clients. Your data is preserved: no Supabase volume, no DinD container, no repo file and no live MCP token is touched — deep unwinds what Supbuddy installed on the machine, it is not a data wipe
full…plus your project data, backed up first: every Supbuddy-managed (sb--prefixed) Supabase stack's data volumes and every DinD container with its data volume, the .supbuddy/ directories, managed blocks and .env.supbuddy files in your registered repos, and every credential (license, live MCP tokens, cloud session, Tailscale key) — then it uninstalls the start-on-login service and empties the app-data directory. A host-mode project's Supabase stack is only stopped: those containers and volumes are yours, and they are kept

Most steps enumerate what's actually on your machine first, so anything that isn't there drops out of the manifest instead of being advertised and skipped. soft needs no elevated access at all. deep batches the pf redirect, the resolver configuration (including the /etc/hosts fallback block, which is removed by the same command) and the loopback aliases into one password prompt; the legacy /etc/hosts block and the keychain CA removal ask separately, so expect up to three. On macOS that first batch ends by checking, as root, that no Supbuddy-marked /etc/resolver file is left; if one is, the reset reports it instead of claiming success. full may prompt more than once as it tears projects down.

A full reset covers the projects in the trash too. A project you deleted over MCP (or supbuddy project rm) waits in the trash for seven days, its Supabase stack and data still on the machine until it expires — and a full reset empties the trash with everything else. So --tier=full treats a trashed project as it treats a registered one: its database is dumped and its managed volumes are archived first, then its managed stack is torn down, its DinD (or the one its move to Host kept) removed, and its .supbuddy/ artifacts cleaned. The manifest names each such project "<name>" (in the trash). Where two records share something — one stack, one folder — it is backed up and removed once. A project whose delete was still finishing when the reset stopped the daemon is covered too: a delete's cleanup is saved as pending until it has finished, and the manifest names such a project "<name>" (being deleted).

Running dev servers are stopped first — except on --tier=full. Every tier forgets your projects, and a pnpm dev that outlives that row holds its port against whatever you register next, keeps writing into a directory Supbuddy no longer knows about, and can no longer be stopped from the app or with supbuddy scripts stop (both look the project up first). So soft and deep sweep them before resetting the registry, and the manifest names each one. --tier=full cannot: it stops the daemon before the wipe runs (it has to — a live daemon would rewrite state.json underneath it), and those dev servers are the daemon's own children, tracked only in its memory. Stop them yourself — in the app, or supbuddy scripts stop <project> <script> — before a full reset, or they outlive it as orphans you have to kill by pid.

Reset is a CLI operation, on purpose — there is no reset button in the app. The gates that make a wipe safe don't survive the trip into a GUI: a typed RESET, a refusal on non-interactive input, and a daemon confirmation the app itself would be answering. On top of that, --tier=full refuses outright while the desktop app is running (its watchdog respawns the daemon ~20s after it stops), so a button for it would be a trap. The app's Settings → General → System health panel points here instead.

Backup before harm. Anything you can't regenerate — state.json, every managed Supabase database that is running (pg_dump, custom format, with a .sha256 alongside), every managed data volume (tar.gz, verified with gzip -t) — is written to <app-data>/backups/reset-<timestamp>/ before a single destructive step runs, and if any backup fails the whole reset aborts before destroying anything. The directory is printed prominently before you confirm, and again when the reset finishes; manifest.json inside it records exactly what was planned and what ran. On top of that coarse guarantee, each volume is gated individually: no archive, no removal — a volume with no non-empty .tar.gz next to it is left alone and the run records why.

A backup that can't be written stops the reset — safely. Archiving a volume is given ten minutes; a genuinely large one (tens of GB of Postgres data plus a DinD image cache) can exceed that, and when it does the reset aborts with nothing destroyed. Stop the stack and prune what you don't need (docker system prune, drop old branches/schemas), or archive that volume yourself, then run the reset again. The same applies to any other backup failure: a full disk, an unreadable volume, a Docker daemon that stops answering.

The backups survive a full reset. They live inside the app-data directory, so the last step of --tier=full empties that directory content-wise and skips backups/ rather than deleting it wholesale. Move that directory somewhere safe afterwards — it's the only copy.

Confirmation. Every tier prints the manifest first — the literal list of actions that will run, derived from the same actions the engine executes. soft and deep then ask Apply this "<tier>" reset? [y/N] (default No); --yes skips that prompt. --tier=full requires you to type the word RESET — --yes alone does not bypass it. The one scripted path for a full reset is --yes --i-understand, both flags together. Every prompt refuses on a non-interactive (piped) stdin rather than proceeding.

The daemon confirms too. soft and deep run inside the daemon, which asks for its own approval before it starts — the same gate as doctor --fix and ca uninstall. With the Supbuddy app open you get a native Allow / Deny dialog. A daemon with neither a dialog nor a terminal — the start-on-login service, or an app-spawned daemon while the app is closed — has nobody to ask, and the reset says nobody on the daemon's side could answer the confirmation; run a foreground supbuddy daemon in one terminal and the reset from a second, and it will prompt there. A Deny prints declined on the host, and a dialog left unanswered for 60 seconds prints nobody answered the confirmation in time; the dialog may still be open on the host. Nothing is changed in any of the three. Don't reach for supbuddy daemon --yes to get past it: that auto-approves every confirmation for that daemon's whole lifetime. A step whose password prompt failed is listed the way doctor --fix lists one (see System doctor).

Quit the app before a full reset. The desktop app supervises the daemon and restarts it about 20 seconds after it stops, which would put a live daemon back into the directory the last step clears. --tier=full refuses up front while the app is running — before it asks you to type RESET, and before it changes anything. Quit the app (menu bar icon → Quit) and run it again; the quit dialog's default Leave running is fine, since the reset stops the daemon itself. The check looks for the app process only, so nothing else has to change. --tier=full also runs with no daemon at all, so if you quit with Stop service you can go straight ahead.

The order of a full reset, once you've confirmed: the start-on-login service is uninstalled, the daemon is stopped and waited for (the reset refuses to run against a live daemon, which would rewrite state.json underneath it), the backup and teardown steps above run, and only then is the app-data directory emptied — keeping backups/. If the reset aborted, or if a daemon came back while it was running, the app-data directory is left in place and the CLI tells you so rather than clearing it under a live process. It is also left in place when a machine-wide file Supbuddy wrote (a skill file under ~/.claude, ~/.cursor or ~/.agents) could not be removed: the step that failed names it in the report and the CLI lists it again. A file a project used is removed at Supbuddy's next start, once it can be; a user-level skill is kept as installed so you can remove it again from Settings → AI Skills. Or delete it yourself, then the app-data directory, keeping backups/. The same happens when Supbuddy's global-file registry can't be read: the reset can't confirm that no such file remains, so it keeps the app-data directory and says so. The closing "nothing else of Supbuddy remains" line appears only when every step succeeded.

soft and deep are also available over MCP as the plan-gated system_wipe tool (see MCP tool surface). --tier=full is CLI-only: it deletes the credentials any agent would be calling with, and a daemon cannot uninstall the service it runs under or delete the directory it runs from.

What a full reset does not remove. It only ever touches paths of registered projects — there is no disk scan for stray .supbuddy directories — and it won't delete or rewrite files whose ownership is ambiguous. So after --tier=full these are still on disk, and you can remove them by hand:

  • Per-editor rule files Supbuddy wrote in your repos: .cursor/rules/supbuddy.mdc, .claude/skills/supbuddy/SKILL.md, .codeium/windsurf/rules/supbuddy.md, .continue/rules/supbuddy.md, .idea/supbuddy.md. Shared files (CLAUDE.md, AGENTS.md, .gitignore, …) keep their content and only lose Supbuddy's sentinel-delimited block.
  • Values apply_env merged into your own .env* files. The fully-owned .env.supbuddy files are deleted.
  • The .env.supbuddy line in .gitignore (for a .env.supbuddy linked to a file of another name, that file's anchored path, such as /shared/supbuddy.env) — it sits outside the managed block.
  • vite.config.* allowedHosts and next.config.* dev-origin patches.
  • supabase/config.toml port / project_id patches, when restoring the original file failed during the Thin teardown.
  • MCP client config entries written by mcp add / install_mcp_config (~/.claude.json, Claude Desktop, Cursor, Codex, Windsurf, a project .mcp.json / .cursor/mcp.json / .continue/mcpServers/mcp.json, and the lines for each of those three in the repository's .gitignore and in its .git/info/exclude). The token they hold is dead the moment the secrets are deleted; supbuddy doctor's stale-mcp-config-tokens check will name each file.
  • The caddy:latest Docker image (shared and re-pullable) and anything a host-mode project owns.
  • The Supbuddy app itself — drag Supbuddy.app to the Trash — and the backups directory, which is the whole point of keeping it.

Settings reference

Open Settings via the gear icon top-right, or from the tray icon → Open Supbuddy → gear. Six tabs: General, Network, Storage, MCP, AI Skills and Cloud.

A change Supbuddy can't take, such as a port out of range, says why in a toast, and the setting stays as it was. What you typed stays in the field so you can correct it.

The settings saved in Supbuddy's state file are checked when it starts, too. A value that is the wrong type or out of range, from a hand edit or a partial write, is replaced by its default, logged as [loadState] Saved setting <key> is not valid (<reason>): using the default (the reason, never the value), and written back once. A value an older version could save keeps working: a port below 1024, a default TLD the editor would refuse today, more than 100 Supabase search paths, and a request-log size outside 100–10000 (MCP update_settings took any before 3.8.0). A project on a TLD that is not one DNS label, the default or its own (a dotted dev.local, say), is left on the domains it has, mappings included, rather than moved to it; this is logged once per start. Every other project is still moved onto its TLD, and the check that refuses a name the next start would make too long judges the same way. A search path outside the project (absolute, or with a ..) is dropped, as the scanner never used it, and named by its place in the list. A retired vm default isolation becomes thin. The records Supbuddy keeps for itself are checked the same way: MCP's own settings one by one (an MCP server you turned off stays off when its saved port is bad; a missing one takes its default; port 0, any free port, is kept), the CA trust record (when only its time is bad, the time is left out and the trusted root kept, logged as … : left out, the trusted root kept), the /etc/hosts fallback flag, the bundled-runtime trust flags and the retired VM's resources, each falling back to its default (the CA trust record and the fallback flag are facts Supbuddy learns again). The one-shot isolation migration's marker is read as it always was, so a host default you chose after it is kept (logged as … : read as true).

General

  • Theme: dark or light.
  • Auto-start at login: registers Supbuddy as a macOS login item. Default: on.
  • Default TLD: applied to new auto-generated mappings. Existing projects and their mappings on the old default are renamed to the new one on save, and so are manual mappings on the old default; a project with its own TLD keeps it, and a manual mapping on any other TLD keeps its own. A change that would put two mappings on one name is refused, naming them, and nothing changes, and so is one that would make a project's domain or a mapping over the DNS limits (63 characters between dots, 253 in all). One DNS label: letters, digits and inner hyphens (not first or last), at most 63 characters. Default: test. The presets are .test, .local, .internal and .localhost; Custom takes any other. A real public suffix (.com, .dev) shows what it would do and is set only with Use .com anyway (see Custom domains & TLDs).
  • Default isolation: host or thin for newly added projects. Default: thin (per-project loopback IP; apps keep canonical ports like :3000). MCP registration additionally keeps a project on host when its Supabase stack is already running on the host outside Supbuddy.
  • Auto-subdomain mapping: when on, services and apps detected during a project scan get mappings created automatically. Default: on.
  • CA Certificate: whether this Mac trusts Supbuddy's local HTTPS certificate authority, the one browsers use (see Trust the local Certificate Authority).
    • States: checking…; trusted (green); not trusted (amber), with Install and Show; changed, not trusted (amber, the same buttons) when the root is not the one this Mac last trusted, its tooltip saying when that one was (when that time was kept); unverified where the trust store can't be read (not a fault — manual steps are shown); couldn't check when the status itself couldn't be read, with Retry.
    • Install runs the installer and shows Installing… until it ends; macOS's dialogs can take a few minutes each. The toast and the row then say how it ended.
    • Show reveals root.crt in Finder. It reveals that file only: the app refuses any other path.
    • If an install can't finish, its reason and, when it gives them, the steps to finish by hand stay pinned under the row, with the time it ended. That holds for an install the System Doctor or an agent started too, which also shows Installing… while it runs.
    • There is no Uninstall button: use supbuddy ca uninstall or MCP uninstall_ca.
  • Bundled-runtime trust: installs Supbuddy's local root CA into a place that apps with bundled JavaScript runtimes (Claude Code, Cursor, Windsurf, Continue, Codex CLI, OpenCode, …) actually read. These apps don't consult the system Keychain (they ship their own Mozilla bundle), so without this they fail OAuth/MCP/HTTPS calls to *.test with unable to get local issuer certificate. Default: prompted on first launch when one of those tools is detected.
    • macOS: writes ~/Library/LaunchAgents/com.cueplusplus.supbuddy.bundled-runtime-ca-trust.plist and calls launchctl setenv NODE_EXTRA_CA_CERTS so GUI-launched apps inherit it at process-start time.

    • Linux: writes ~/.config/environment.d/supbuddy-ca.conf (read by systemd-aware user sessions on GNOME/KDE/Sway/etc.). That is all Install does there: the systemd user manager reads the file at login and nothing reloads it, so trust takes effect at your next login — log out and back in, or reboot.

    • Windows: per-user setx NODE_EXTRA_CA_CERTS to HKCU\Environment.

    • Only NODE_EXTRA_CA_CERTS is set session-globally, because it is additive — Node appends the file to its built-in public roots, so a stale or wrong value can never strip public trust. SSL_CERT_FILE / REQUESTS_CA_BUNDLE are deliberately not set globally: they replace the entire trust store, and pointing them at a local-only bundle breaks every public TLS handshake in the login session. Older builds did set them; install and every boot reconcile now actively unset them. OpenSSL/Python tools that need local trust get it per-project, from the merged public+local bundle.

    • It points at ~/Library/Application Support/Supbuddy/ca-bundle/current.crt (or the platform equivalent), a cumulative concatenated PEM Supbuddy maintains — not Caddy's own caddy-data/…/pki/authorities/local/root.crt, which rotates independently. When Caddy rotates its root (yearly today, sometimes more), Supbuddy appends the new root automatically; long-running TLS contexts holding the old root keep working until the process restarts.

    • The bundle's own health: every trust-status read judges the bundle the way it judges every other value (below) — current, outdated, missing, invalid or unknown — so a rotation can't be missed just because the file watcher wasn't running. While trust is installed, the read repairs a bundle that is proven outdated, missing or invalid against a known active root, and an invalid one whatever the root: it rebuilds the bundle from the certificates that parse, drops any malformed or duplicate block, keeps the old valid roots, adds the active root when there is one, and writes it atomically. One repair runs at a time. An unknown bundle (unreadable, a symlink) is never rebuilt blind, and with trust not installed nothing is repaired, so a bundle Remove deleted stays deleted. If the repair fails — including when the merged public+local bundle fails its validation, even though the bundle itself then reads current — the panel shows its error. The fix is Remove, then Install, which starts a fresh bundle holding only the active root; the panel offers it only while Caddy's root is present, because Install needs it, and otherwise says that Caddy's root is missing or can't be read.

    • Test trust: starts a new Node process with NODE_EXTRA_CA_CERTS pointed at the current bundle and fetches the first available *.test mapping, to verify end-to-end without relaunching anything. That is exactly what Test OK · a new process with the current bundle proves: apps already running keep the CA they started with. It probes the real access path (port 443 when port forwarding is on, otherwise the high port), matching what real clients hit, so it doesn't false-negative against a port nothing is forwarding.

    • Effective-value detection: status reports the value in effect, not just the one Supbuddy set. launchctl setenv cannot retro-patch an already-running process, so an app launched before an install keeps whatever it captured and hands that to every shell and dev server it spawns — a terminal can be using a completely different CA path from the one launchctl getenv prints. Supbuddy samples three places: what it set, what a fresh login shell resolves, and what live processes actually hold.

    • Certificates, not paths: for each Supbuddy-owned value that isn't the bundle, Supbuddy reads the file and compares its certificates, by the SHA-256 of their DER, with Caddy's active root. It only ever opens the bundle, the merged bundle and Caddy's root.crt, and safely: through no symlink, whether the file or a folder on its path (checked again after the open), never a special file, at most 1 MiB, and a file that changes while it is read counts as unchecked. A path naming one of them in another case (an older build's …/supbuddy/…) is read as that file only when it is that file — the same device and inode — as on a case-insensitive volume; on a case-sensitive one it is just another path. Any other path is never opened: if it doesn't exist it is missing, otherwise it is reported as unchecked. Each value gets one verdict:

      • current: every certificate parses and Caddy's active root is among them. Nothing to do, and nothing is shown: a different path to the same certificate is fine. The usual case is Caddy's own caddy-data/…/pki/authorities/local/root.crt, which Connect → Apply writes into a project's .env.local; Caddy replaces that file in place when it rotates.
      • outdated: valid, but without the active root.
      • missing: the file doesn't exist. Node ignores a missing NODE_EXTRA_CA_CERTS silently, which presents as unable to get local issuer certificate with nothing to explain it.
      • invalid: no certificate, or any block that doesn't parse. Unusable, whatever the root.
      • unknown: Supbuddy couldn't read it safely, or Caddy's root is itself missing or unreadable. Shown as "couldn't check", with the reason, and nothing more is claimed.

      This describes the file on disk now, not what a running process trusts: Node reads NODE_EXTRA_CA_CERTS once, at start, so an app started before a root rotation keeps the certificate it started with.

    • What to do depends on where the value comes from. The panel names a replacement only when this read verified it — the bundle, else Caddy's root.crt — and otherwise says it can't verify one right now:

      • the value Supbuddy installed: remove bundled-runtime trust, then install it again — or, when trust isn't installed, install it, which replaces the value. Neither works while Caddy's root is missing or unreadable, and the panel says so instead;
      • your shell profile: point it at the replacement, then open a new shell (or remove the line, when trust is installed and the replacement is the bundle);
      • a running app: if a project env file sets it, point it at the replacement (or run Connect → Apply when that is Caddy's root); if the app inherited it, relaunch the app.
    • Conflict refusal: if NODE_EXTRA_CA_CERTS is already set to a bundle Supbuddy doesn't own (corporate proxy, Zscaler, another vendor's CA), install refuses and surfaces the conflicting path. You can override with the explicit prompt that pops up on Install. A path Supbuddy does own but that isn't the current bundle — an older build's value, or Caddy's root.crt from a hand-rolled setup — is not a conflict: install corrects it. Connect → Set env vars follows the same rule for the NODE_EXTRA_CA_CERTS it writes into a project's env file, and keeps a value Supbuddy doesn't own (see The connection panel).

    • Quit and relaunch your AI tools after install. On macOS (and Windows) apps launched from now on get it; on Linux it takes effect at your next login (above). Either way, apps already running — and the shells and dev servers they start — keep what they started with. Install names an app only when it holds a CA file proven outdated, missing or invalid.

    • For automation (get_trust_status over MCP, supbuddy trust status): the status carries caPathObservations (every Supbuddy-owned value with its origin, holder, fileContent and pointsAtCaddyRoot, current ones included), bundleContent, activeRootState, caReplacement and, when a repair failed, bundleRepairError. Contract change, caObservationContract: 2: divergentNodeExtraCaCerts, and the install result's staleHolders, now list only values whose file is proven outdated, missing or invalid (process holders only, for staleHolders), and conflictingNodeExtraCaCerts names a Supbuddy-owned value only when it is one of those (a foreign value still comes first). Before, they covered every Supbuddy-owned value that wasn't the bundle's path, whatever the file held. bundleContainsActiveCaddyRoot is false only when Caddy's root is known and the bundle is proven stale.

  • System health (Scan): opens the System Doctor panel — the same health & drift scan as supbuddy doctor (see System doctor), in the app. Opening the panel only scans: it never repairs or changes the system, though it may record what it learned about the CA.
    • Findings are grouped critical → warning → info, each with its title, one-line detail, concrete evidence (paths, container names, fingerprints), check id and category. Rescan re-runs the scan; the header shows the counts. A scan that times out says so and points at supbuddy doctor — the daemon is installed and updated separately from the app, and one older than this panel doesn't answer its channels.
    • Fix… on a fixable finding — or Fix all (n) in the header — never repairs anything by itself. It opens the manifest: the literal list of actions that would run, each marked destructive or safe, built from the same actions the engine executes. Apply stays disabled until that manifest has loaded and contains at least one action, so an empty or failed plan can't be rubber-stamped. Same confirm-before-harm contract as doctor --fix.
    • Repairs that need elevated access ask for your password when they run. Apply shows Applying… until they finish — the app waits up to 10 minutes for them. One that outlives even that is shown as No answer yet — the repair may still be running; rescan in a moment — not as a failure; for the CA repair it adds that any steps to finish by hand will be pinned under Settings → General → CA Certificate. A second Apply while one is still waiting for its answer (after reloading the window, say) is refused, and shown as Not started — another repair is still running; this one wasn't started. In Last repair, a repair that could not finish on its own shows the steps it gave for finishing by hand under its line (the CA install on macOS 15+ when its dialog was dismissed), and a repair whose password prompt failed says which way before its message — the admin prompt was refused, timed out (it may still be open), no admin prompt could be shown, and so on — in the same words as doctor --fix.
    • Findings with no auto-fix show advisory instead of a Fix button; the detail says what to do by hand. Checks that couldn't run at all are listed at the bottom as Checks that could not run, rather than being silently dropped.
    • There is no reset button here, on purpose — the footer points at supbuddy reset instead. See System reset.

Network

  • HTTP port: default 8080. 1024–65535; Save saves only the port you changed.
  • HTTPS port: default 8443. 1024–65535.
  • DNS port: default 5353, 1024–65535. When it is taken at start, the next free port is used and saved here.
  • Port forwarding: when on, inserts a pfctl rule mapping 80→HTTP port and 443→HTTPS port into /etc/pf.conf (correct translation-section placement; self-heals a file corrupted by older versions). Asks for sudo once. Status reflects a live 443 enforcement probe, not just file presence.
  • LAN sharing: binds Caddy to 0.0.0.0 + starts mDNS responder. Off, Caddy listens on loopback only (plus docker0 on Linux).
  • Tailscale: paste a tailnet API key so Supbuddy can remove the split-DNS routes earlier versions pushed (it pushes none: see Tailscale).
  • The CA's Install is under General, not here (see CA Certificate above).

Storage

Trash retention (per-kind), volume sizes, image-cache controls.

MCP

  • Clients: list of connected clients. Each row has a ⋯ actions menu: install, edit scopes, set-primary, rotate token, revoke.
  • Activity: audit log with Apply/Cancel/Undo on plan rows.
  • Trash: soft-deleted mappings and projects, restorable for 7 days.
  • Settings: server enabled, port (default 9877), audit_cap (default 5000), trash_ttl_days (default 7).

AI Skills

Install Supbuddy's agent skill at the user level (machine-wide) so the agent sees Supbuddy in every repo without per-project setup. Each global-capable agent has a master on/off plus an autosync toggle (keeps the installed skill refreshed when Supbuddy updates it) and shows its install path + version.

  • Who can install at user level: only agents whose global file Supbuddy fully owns and that self-scope (act only when the working directory has a .supbuddy/). That means three agents, all getting the same file:
    • Claude Code: ~/.claude/skills/supbuddy/SKILL.md.
    • Cursor: ~/.cursor/skills/supbuddy/SKILL.md.
    • Codex & ChatGPT: ~/.agents/skills/supbuddy/SKILL.md, the user-level skills folder OpenAI documents for the Codex CLI, its IDE extension and the ChatGPT desktop app. ChatGPT on the web runs only plugin-bundled skills, so it has nothing to install.
  • Not merged across folders: same-name skills are not merged. Cursor also reads ~/.agents/skills (locally), so with both the Cursor and the Codex & ChatGPT rows installed, Cursor may list Supbuddy twice. That is harmless, since the content is identical. Keep the Cursor row for Cursor Cloud agents, which don't read ~/.agents/skills. Supbuddy does not write ~/.codex/skills, which OpenAI does not list as a discovery location.
  • How it persists: the install is reference-counted under a synthetic __user__ ref, so it persists independent of any project and is never pruned by the boot reconcile. With autosync on, it is refreshed at every daemon start, whether or not the MCP server is enabled.
  • Reset: supbuddy reset, any tier, removes these files along with their records, only where Supbuddy's own record shows it wrote the file. A file a project also routes there stays until the next start's cleanup removes it with the forgotten projects. A skill whose file can't be removed is named in the reset's report and kept as installed so you can remove it again from Settings → AI Skills; the reset still completes.
  • Master ↔ project: the AI Skills tab is the master (user-level). To write a skill into a specific repo, use that project's AI Tools tab and set the target to Project (the old local scope). When Supbuddy manages the project's .gitignore, it lists the generated file in its own block, which it rewrites on every sync; to commit the file for teammates, add a !<path> line below that block, or git add -f it. User there means the master install covers it. Codex & ChatGPT is user-level only: in a repo, Codex reads the project's AGENTS.md block.
  • The shared instruction files — Claude CLAUDE.md, Codex AGENTS.md, Copilot, Windsurf, Continue, JetBrains — also hold your own content, so Supbuddy writes them per project only: a machine-wide write there could clobber your config. The skill files above (Claude Code, Cursor, Codex & ChatGPT) are separate files Supbuddy owns, and those are the user-level ones.

Cloud

Sign in to Supbuddy Cloud. See Supbuddy Cloud.

Tray menu

The macOS menu bar tray icon opens a menu with:

  • Status: …: current proxy state (running / idle).
  • DNS :<port>: the DNS server's port in use, shown while it runs.
  • LAN Sharing (<ip>): shown when LAN sharing is on.
  • Tailscale (<ip>): shown when Tailscale is connected.
  • Start Proxy / Stop Proxy: opens the dashboard.
  • Projects: each project opens a submenu with Apps (click to open the mapped URL), Supabase services (status dot + open), and Scripts (your bookmarked scripts as a one-click Start <name> / Stop <name> toggle), plus Restart Supabase/Restart services and Show in Supbuddy.
  • Open Supbuddy: opens the window (Settings is the gear, top right).
  • Sync AI context for all projects: runs the project-context sync engine for every registered project (writes .supbuddy/, CLAUDE.md, AGENTS.md, etc.).
  • Show Logs: reveals main.log in Finder.
  • Check for Updates...: manual update check (only enabled in packaged builds). The panel names all three moving parts and their versions — the app, the daemon running inside it (bundled when it ships with the app, npm when it came from the CLI package), and the CLI itself — because they release on their own cadences and a single unlabelled version number cannot tell you which is behind. A CLI-only release is detected too: the check asks npm for the newest supbuddy and, when yours is older, says so and gives you the command (npx supbuddy@latest) even though the app itself is current. In that case the panel says "The app is up to date" rather than "You're up to date", which would not be true. A CLI version it cannot determine is shown as unknown rather than left blank, and a failed registry check says it failed instead of implying you are current.
  • Quit.

File locations

All under ~/Library/Application Support/Supbuddy/ on macOS:

  • main.log + main.log.1: app logs (rotates at 2 MB).
  • state.json: persistent state (projects, mappings, settings, MCP clients, license). Each save writes a temporary file beside it and renames it over, so a crash leaves the old file or the new one. A save that has not finished in 30 seconds (a home folder on a network mount that stopped answering, a flush that hung) is reported in the daemon log, and the next save goes ahead: one given up on before its rename is reported failed and never replaces the file afterwards; one whose rename was already under way is reported unconfirmed, and the next save waits for that rename (a save waiting behind it is reported unconfirmed too, no sooner than 30 seconds after it was asked and at most 30 seconds after that rename overran, and is made once the rename returns); one with only its folder's flush left counts as saved. At most two saves given up on are left stuck at once; past that a save is refused at once, and once one of them finishes, a save of every change made meanwhile is asked for. The system wipe's reset step fails, saying so, when the emptied state could not be saved; one reported unconfirmed (behind a rename that has not returned) may still land later, once that rename returns.
  • state.json.trash-repair-<hash>: a copy of state.json as it was, made when a load found trash entries with no project or mapping in them (or a trash list that was not a list) and left them out. The repair is written back only once the copy is made. One copy per content: a file loaded again as it was is not copied again. Supbuddy never removes it; delete it once you no longer need what it held.
  • caddy-data/: Caddy's data dir (PKI, autosaves, certs).
  • caddy-data/caddy/pki/authorities/local/root.crt: the local CA cert installed in your Keychain.
  • ca-bundle/current.crt: cumulative PEM containing every Caddy root that has ever been emitted. Used by Bundled-runtime trust as the target for NODE_EXTRA_CA_CERTS / SSL_CERT_FILE / REQUESTS_CA_BUNDLE. Real file (not a symlink) so Bun-bundled CLIs read it correctly.
  • ca-bundle/versioned/<sha>.crt: per-root snapshots for forensics.
  • Caddyfile: generated reverse-proxy config.
  • daemon.json: written while a headless CLI daemon is running (pid, Socket.IO + MCP-HTTP ports, control token); 0600, removed on shutdown. Used by supbuddy CLI commands to discover and authenticate to the daemon, and by the desktop app to detect a running CLI daemon at launch.
  • certs/: legacy CA from the pre-Caddy era (unused in current builds).

MCP-specific:

  • MCP client tokens (file-backed secret, mode 0600): ~/Library/Application Support/Supbuddy/secrets/mcp-<client-id>.secret
  • MCP audit log: under ~/Library/Application Support/Supbuddy/, capped at audit_cap entries (default 5000).

Troubleshooting

Run a health & drift scan first (supbuddy doctor)

When something's off, supbuddy doctor is the quickest triage. It runs a scan that never repairs or changes the system, and prints findings by severity, and many of the issues below have a matching check — an unreadable state.json, an untrusted CA, a wedged Caddy, port 443 not redirecting, stale duplicate CA roots, legacy CA-trust LaunchAgents poisoning public TLS, an agent config still holding a revoked MCP token, a Firefox profile pinning an old Caddy root, a Thin project's missing 127.0.0.N loopback alias, and leftovers from deleted projects (Docker containers/volumes, 127.0.0.N loopback aliases, /etc/resolver files, MCP token files). Add --fix to apply the opt-in repairs after a confirmation prompt — some checks are advisory and have no auto-fix. See System doctor for the full check list and flags.

A mapped name works with curl but not in the browser

The browser is probably resolving names through DNS-over-HTTPS (secure DNS). It sends its lookups to a DoH server, which has never heard of app.demo.test, instead of asking this machine's resolver, which is where Supbuddy's names live (/etc/resolver on macOS, systemd-resolved on Linux). Every Supbuddy check asks that resolver, so they all say the name resolves. supbuddy doctor reports it as browser-secure-dns (info) when it can see the setting.

  • Chrome, Chromium, Brave, Vivaldi, Arc: Settings → Privacy and security → Security → Use secure DNS. Choose With your current service provider, or turn it off. A chosen provider (Cloudflare, Google, …) always uses DoH.
  • Edge: Settings → Privacy, search, and services → Security → Use secure DNS. Choose Use current service provider, or turn it off.
  • Firefox, Zen, LibreWolf, Waterfox: in about:config, add your project TLDs to network.trr.excluded-domains (comma-separated, for example test,internal): those go to this machine's resolver whatever the protection level. Or use Default or Increased Protection instead of Max Protection.
  • .local names go to the system in the Chrome family, and in Firefox unless its built-in exclusions (network.trr.builtin-excluded-domains) were changed. Names in the /etc/hosts fallback resolve from that file in both, whatever the DoH setting.
  • Not seen by the doctor: an enterprise policy that sets DoH (DnsOverHttpsMode), and a system-wide DNS-over-HTTPS profile (a macOS configuration profile, or a VPN client's DNS). Turn those off for the project TLDs, or ask whoever manages them.

Browser shows "Not secure" or certificate warning

The Caddy CA is not trusted. Open Settings → General → CA Certificate and click Install (an agent can call MCP install_ca). macOS will prompt for your password — on macOS 15+ this is the "You are making changes to your Certificate Trust Settings" dialog for the per-user install. After install, fully restart your browser (Cmd+Q, not just close window). Verify: Keychain Access → System keychain, then the login keychain → search for "Caddy Local Authority".

If the install fails with SecTrustSettingsSetTrustSettings: The authorization was denied since no user interaction was possible, that is macOS 15+ refusing system-wide trust to a background helper; Supbuddy retries per-user automatically, and if you dismiss that dialog it shows you the no-sudo command to run yourself.

If it worked before and supbuddy doctor now says "The local CA changed and needs trusting again (screen session)", Caddy has made a new root, and that one needs trusting. On a Mac you reach from a distance, follow the steps in Remote setup: what needs a screen session.

"unable to get local issuer certificate" / "self signed certificate in certificate chain" from Claude Code, Cursor, MCP servers, or other AI tools

These tools ship their own bundled JavaScript runtime (Bun, Electron, pkg-bundled Node) and ignore the system Keychain. Open Settings → General → Bundled-runtime trust and click Install. Then fully quit and relaunch the AI tool; the env var only takes effect for newly-launched processes. Verify with launchctl getenv NODE_EXTRA_CA_CERTS (macOS); it should print ~/Library/Application Support/Supbuddy/ca-bundle/current.crt. If install is refused with a conflict warning, you already have NODE_EXTRA_CA_CERTS pointing at a bundle Supbuddy doesn't own (often a corporate proxy / Zscaler), so Supbuddy won't silently overwrite; use the override prompt or manually concatenate the two PEMs.

If it still fails after a relaunch, the process is probably not using the value launchctl getenv prints. Compare them:

launchctl getenv NODE_EXTRA_CA_CERTS                     # what Supbuddy set
node -e "console.log(process.env.NODE_EXTRA_CA_CERTS)"   # what your shell actually has

If they differ, the trust panel tells you whether it matters. It compares what each file holds, not its path: a value whose file holds Caddy's active root is fine and isn't listed. That includes Caddy's own caddy-data/…/pki/authorities/local/root.crt, which Connect → Apply writes into a project's .env.local, and which Caddy replaces in place when it rotates. A value whose file lacks the active root, doesn't exist or isn't a valid certificate file is listed with what to change. If a project env file sets it, point it at the file the panel names. If an app launched before the install captured it, quit and reopen that app (not just the terminal tab): launchctl setenv cannot change an already-running process. An app started before a root rotation keeps the certificate it started with, whatever the file holds now.

"Docker is not running. Please start Docker Desktop."

Compose and Supabase features need Docker. Open Docker Desktop and wait until the whale icon stops animating.

"Docker Compose is not installed"

Compose v2 ships inside Docker Desktop. If you removed Docker Desktop and are using a standalone Docker daemon (e.g. Colima, Rancher), install compose: brew install docker-compose.

"Docker Compose did not answer within 30 s"

Supbuddy asks docker compose version (then, if that is missing, docker-compose --version) before it runs Compose: for a Compose start, a bundle export or import, and the Compose status and prerequisite checks (MCP get_compose_status and check_compose_prerequisites, and the app's own). Each ask is stopped after 30 s with its process group (so a hung Compose plugin goes too), and is reported as this rather than as "not installed": Compose is there but did not answer, often because Docker Desktop is still starting or is stuck. A Compose v2 that hangs is not replaced by v1. The status checks (compose_installed over MCP) read false meanwhile. A probe still running when the daemon stops is stopped with it. The app waits at most 15 s for the daemon's answer to a Compose start, less than the check's 30 s, so with a Compose that hangs the app says it has no answer yet; the CLI and MCP wait for the message above. Run docker compose version in a terminal; once it answers, try again.

"Leftover host containers" / "isolation drift" warning on a project

Supbuddy flags isolation drift when a project's running containers don't match its configured isolation mode, for example a Host project with a stale thin-mode stack still running, or a Thin project with leftover host-mode containers. Switching isolation modes doesn't tear down the old layer, so those containers linger, waste resources, and can shadow the project's real stack. The warning appears in the warnings chip next to the enable toggle (click it to see each item; it shows a spinner while Supbuddy re-checks), as an entry in the issues counter, and as a notice on the Supabase tab listing the exact containers and any data volumes.

Guided cleanup. Open the Supabase tab → Clean up leftovers… to stop and remove the leftover containers. Data volumes are kept by default; deleting them is opt-in, and when the leftover copy looks newer than the active one, it requires an explicit choice and a backup (tarred to …/Supbuddy/backups/<project>-<timestamp>/). If you recently migrated a VM project, any leftover VM container from before migration can also be cleaned up from this flow. A VM project moved to Host keeps its stopped VM container on purpose, and this flow lists it; a data volume you keep here is removed when you delete the project.

If the leftover copy's data looks newer than the active one, the warning turns red; don't delete its volumes without first deciding which copy to keep. The Configure tab also shows a dismissible note when Supabase stacks are running on your host that Supbuddy doesn't manage at all (e.g. a plain supabase start).

MCP client says "Invalid OAuth error" or "JSON Parse error: Unexpected EOF"

The MCP client is trying OAuth discovery and getting an empty 404. Either the token was lost (regenerate it in Settings → MCP → the client's ⋯ menu → Rotate token) or you're on a build older than the OAuth-probe fix. Update to the latest version; the server now answers OAuth discovery paths with a structured 404 instead of an empty body, and 401 responses include WWW-Authenticate: Bearer so the client doesn't fall back to OAuth.

An agent's call failed with system_modal_unavailable, and nobody was asked

The tool needs a person's yes on the machine running Supbuddy, and nobody there could answer: no app attached, a daemon with no terminal, no logged-in screen to show the dialog on, or an app that went away before an answer. (If the app is running in a logged-in session and nobody is at the screen, the answer is system_modal_timeout after 60 seconds instead.) Open the Supbuddy app on that Mac, or run supbuddy daemon in a terminal there, and retry. Up to 3.8.2 this was reported as system_modal_denied "User denied the action", which read as a person saying no. See Confirmations, and why one came back without a yes.

MCP token disappeared after app restart

Fixed in recent builds. If you're on an older version, regenerate the token. Root cause was that addMcpClient didn't trigger state persistence; the client was held in memory only.

Server Actions return 403 in a Next.js app behind Supbuddy

Next.js's CSRF guard rejects POSTs whose Origin isn't in experimental.serverActions.allowedOrigins. Supbuddy detects this and flags it in the warnings chip: open the Apps tab and hit Fix on the affected app for a paste-ready snippet, or Apply… to preview a unified diff and write the change to next.config directly. After applying, restart your dev server.

On Next.js 15.3+/16, a proxied dev request can also be blocked (e.g. a "Cross origin request detected" warning) because Supbuddy now passes the real browser Origin through rather than rewriting it, and Next validates it against allowedDevOrigins (which defaults to localhost). Add your Supbuddy domain to allowedDevOrigins in next.config — see Next.js cross-origin dev requests. This is a separate key from the Server Actions list; 15.3+/16 may need both.

Vite dev server returns "Blocked request. This host is not allowed." (403)

Vite (v5+) rejects requests whose Host header isn't in server.allowedHosts, so a Vite app reached through a Supbuddy domain 403s until the host is allowed. Supbuddy detects this and flags vite: N hosts blocked in the warnings chip: open the Apps tab and hit Fix on the affected app for a paste-ready snippet, or Apply… to preview a diff and write server.allowedHosts into your vite.config directly. Restart the Vite dev server afterward; Vite does not hot-reload its config. A single .your-project.test entry covers every subdomain.

mail.<project> opens another project's inbox, or Supabase refuses to start over port 54324

Supabase CLI 2.x renamed the mail-catcher section [inbucket] to [local_smtp]. Builds up to 3.6.14 only read [inbucket], so a project whose config.toml says [local_smtp] port = 54624 had its mail port silently read as the stock 54324 — which on a multi-project machine is a different project's inbox. Three symptoms came from that one cause: the generated mail.<project> mapping pointed at 54324, supabase start was refused with "Inbucket needs port 54324 (in use by …)" for a project that never wanted 54324, and Thin's port rewrite skipped the mail keys entirely (managed port key "inbucket.port" not found in config.toml). Current builds read whichever section your file declares. If you are on an older build, either update or rename the section to [inbucket]; after updating, rescan the project so the mapping is regenerated on the right port.

Toggling Supabase analytics said it restarted, and the stack never came back

Fixed in current builds. set_supabase_analytics (and the Supabase tab's analytics toggle) writes the config change and then restarts the stack in the background. Up to 3.6.14 the stop ran first and the start was preflighted only afterwards — so a start that could not succeed left the stack down, while the project card and get_supabase_status went on reporting every service as running from the snapshot taken before the stop.

Two things changed. The restart is now preflighted before anything is stopped, excluding the ports this project's own containers are about to free: if the start could not succeed, the whole operation is refused with the port and the process holding it, and the running stack is left running. Its own containers are the ones supabase stop removes in its Supabase folder: those the Supabase CLI labels with the id it runs the config as, which is its project_id, or with none the real name of the folder holding supabase/. So a running stack whose config names no project_id can be restarted, and a stack whose name only ends the same way (my_db for a folder db) is never counted as this project's. A stack the Supabase CLI started from a shell in a link to the folder, or in another spelling of it, runs as that name, which Supbuddy's stop can't reach: when such a stack holds every refused port and no other project's record or folder could run under the name, the refusal names it and says that if it was started from such a shell, to stop it there with supabase stop. And any restart that does fail is recorded on the project — surfaced as supabase_error on get_supabase_status, with the stack's still-"running" services downgraded to unknown, because after a failed restart that is what their state actually is. A later successful restart clears it.

Supabase Realtime: channel reaches SUBSCRIBED but no postgres_changes events arrive

If a channel subscribes fine (and writes succeed) but change events never fire, this is almost always realtime warmup timing right after the stack starts — not the Supbuddy proxy. Local Realtime can accept a channel join and report SUBSCRIBED before its logical-replication binding for the tenant is ready, so INSERT/UPDATEs in that brief window are silently missed. Give the stack a few seconds after the Supabase tab goes green, then re-subscribe (or reconnect the channel). This is unrelated to the .local domain: Kong routes /realtime/v1/* by path and rewrites the upstream Host to its internal realtime tenant, so reaching realtime through https://api.<project>.local behaves identically to the raw localhost:54321 port — forwarding the .local host upstream does not change tenant resolution. The new sb_publishable_* / sb_secret_* API keys also work for local realtime (Kong maps them to the legacy JWT), so you don't need to switch key formats.

A newly registered project's domain doesn't resolve

Fixed in 3.7.8. Resolver files are per project — web.my-app.internal needs /etc/resolver/my-app.internal, its own file — so every new project introduces a suffix nothing on disk covers yet. Registering a project created the project, its mappings and its Caddy routes, and never asked for that file. Enabling, renaming or re-TLD-ing a project all did; registering, the one path that creates the most suffixes, did not.

The result was a project that looked completely healthy — a live mapping, a Caddy site block, no error anywhere — whose domain the OS had no way to resolve. It stayed that way until some unrelated proxy restart happened to audit the machine, which in one reported case was three days. Registering now writes the file as part of the same operation, and if the privileged step is declined or times out the tool says so in a resolver_note on its reply instead of reporting a clean registration.

If a domain still doesn't resolve, get_dns_status and supbuddy doctor now name the specific suffixes the OS has not loaded, rather than reporting one boolean for the whole machine. See below for why that boolean used to read healthy.

get_dns_status said everything was fine and the domain was dark

Fixed in 3.7.8, and worth describing because the failure was invisible by construction.

The "did the OS load /etc/resolver?" signal was a real DNS lookup, but it had two defects that cancelled each other out into a confident "healthy":

  • It resolved one domain out of however many you have. On a machine with several projects, an older project whose resolver file was loaded answered on behalf of a newly registered one whose file was missing. One healthy project made the whole machine report healthy.
  • It resolved a real managed name, and getaddrinfo reads /etc/hosts before it consults any resolver. So the moment Supbuddy's own /etc/hosts fallback engaged, the probe could no longer observe the resolver path at all — and reported success for the fallback's work.

Both are fixed: the check now probes every managed suffix, using a name /etc/hosts cannot answer (it has no wildcards). One suffix that doesn't resolve makes the verdict false and names that suffix, and a lookup that merely times out is still reported as unknown rather than as a fault. The sweep is bounded so status calls stay fast on a machine with many projects.

Supbuddy asked for your password and gave up before you typed it

Fixed in 3.7.8. The DNS resolver step used its own 30-second timeout while every other privileged path in Supbuddy had already moved to a three-minute one. macOS's admin dialog stays open until you answer it, and giving up does not cancel anything — so a password typed at 40 seconds ran the command successfully and delivered the result to a waiter that had already reported failure. The visible symptom was the privileged step did not answer within 30s. Missing: [...] while the prompt was still on screen. All privileged paths now share the same waiter.

An update interrupted the password prompt, and Supbuddy did not ask again

Supbuddy no longer retries a privileged step on its own when that step's prompt may still be on screen: when the app that showed it went away before answering (an update or a restart hands the bridge to the new app), or when the prompt was not answered in time. Each answer names the prompt it answers, but a retry would still put a second dialog beside the first, and the first can still run once it is answered. Answer or dismiss the dialog if one is still open, then press Retry on the proxy banner, which re-runs every step. Without the app, supbuddy doctor --fix repairs pf, missing resolver files and missing loopback aliases. On Linux, where there is no app, supbuddy proxy restart or supbuddy doctor --fix sets up Supbuddy's route through systemd-resolved again, asking through sudo in the terminal running supbuddy daemon. A step that could not show a prompt at all — no app attached yet — is still retried automatically once one attaches.

A mapping change asked for your password and the write did not go through

A new mapping, a project turned on, a registration or restart_proxy re-applies Supbuddy's resolver files, and asks for your password when one must be written. When that write does not go through (you declined the prompt, it went unanswered, an update interrupted it, or no app was attached to show it), the project's card says which domains will not resolve when a resolver file is missing or wrong. For a served name, the proxy banner now offers Retry, which runs the write again. That includes a write that only the /etc/hosts fallback block needed, which the card does not show. A write that only removes stale files (for a deleted mapping) is kept for Retry too, without the banner, since no name you use is broken.

  • A prompt that could not be shown at all (no app attached yet) is retried once an app attaches, and again whenever the work changes after that attempt: the DNS server on a new port, or a mapping added or removed, even when the same names were already waiting. The same holds for port forwarding (new HTTP or HTTPS ports, or LAN sharing turned on or off) and for the Thin projects' loopback aliases (the IPs they need changed, even back to ones already waiting). The same work failing the same way is not retried again. One you declined, or one that may still be open, waits for Retry or the next start.
  • The banner comes down on its own when a later re-apply finds the files right, or writes them. The exception is a prompt that may still be open (unanswered, or interrupted by an update), whose command could still run: that one waits for Retry or the next start.
  • On a Mac using the /etc/hosts fallback, the same holds for the fallback block, which is how names resolve there. A mapping added under an existing domain may need only the block.
  • An /etc/hosts Supbuddy cannot read, on a Mac using the fallback (its permissions were changed so your account can't read it): Supbuddy can't tell whether the block is right, so it never counts it as in place. While the block would carry a name, every mapping change and every start keeps it for Retry, with the banner. No password prompt is shown for it, since none could fix it: make the file readable again (sudo chmod 644 /etc/hosts), then press Retry. An /etc/hosts that is not a regular file (a FIFO, a device) or is over 16 MiB is not read at all, and counts as one Supbuddy cannot read. Nor is the fallback taken down while the file can't be read: a start that finds /etc/resolver loaded again keeps the fallback on, so the next start looks at the block again, until Supbuddy can see the block is gone.
  • A failure that was not the prompt's (the resolver command could not be built, an audit that could not run) shows on the project's card as before.

Supbuddy asks for your password on every mapping change (3.7.8)

3.7.8 created new /etc/resolver files readable only by root (-rw-------). Supbuddy reads those files without elevated access, so it could not see its own files, counted them as missing, and asked for your password to rewrite them on every mapping change, project activation and proxy restart. The rewrite produced the same root-only file, so the prompts never stopped. The same files made doctor report dns-not-resolving, and kept the /etc/hosts fallback from engaging on a Mac that needs it.

The release after 3.7.8 writes them readable by everyone again (-rw-r--r--, as 3.7.7 did), and its next resolver write repairs any file 3.7.8 left behind. On 3.7.8 itself, ls -l /etc/resolver shows the affected files, and sudo chmod 644 /etc/resolver/<file> repairs one by hand.

Supbuddy wrote the resolver files and macOS ignored them

On some Macs — reported on macOS 26 with System Integrity Protection enabled — the files land correctly and scutil --dns never lists them. Supbuddy asks the OS to re-read them after every write, trying dscacheutil -flushcache, then a launchd restart of the resolver daemon under both its modern and legacy labels, then SIGHUP, then a dynamic-store refresh on the primary network interface. On a SIP-enabled machine the launchd restarts are refused outright (Operation not permitted while System Integrity Protection is engaged), and SIGHUP has not re-read /etc/resolver since Darwin 23.

Until 3.7.8 every one of those attempts discarded its own error output, so this was undetectable from inside the app: the files were correct, nothing had failed, and the domains were dark. Supbuddy now records which reload actually worked and logs the refusal text of the ones that did not, so the daemon log says plainly when no strategy succeeded.

What to do if you hit it. Toggling Wi-Fi off and on forces the rescan — macOS appears to re-read /etc/resolver on a network configuration change rather than on a file write. Do not bother with sudo killall -HUP mDNSResponder; this is the one reload that provably does nothing here, and Supbuddy no longer suggests it. The durable answer is the /etc/hosts fallback, which is built for exactly this machine and engages on the next proxy start.

Project shows a red "PROXY ERROR" banner: domain resolves but won't load

After the proxy starts, Supbuddy runs an end-to-end reachability check: it resolves a project domain through the OS resolver and tries to connect to Caddy on the HTTPS port. If the name resolves but the connection fails, the project shows a red PROXY ERROR banner naming the likely cause (DNS, port-forwarding, or mDNS race) plus a recovery action.

Every start has its own check, and only the latest one counts. The app's Start, supbuddy proxy start / start_proxy and supbuddy proxy restart / restart_proxy each run the check after they finish — the restart and a start over MCP used to skip it, so a fault they erased was not reported again until the app's next start. A check still running when a newer start, a stop, or anything else that changes the proxy's status comes along reports nothing, so an older check can no longer put a banner up over a newer start or a stop. Any stop (the app's Stop, stop_proxy, Stop all, a restart's stop half) also ends the 45-second re-check at once, and a fault that had raised the Retry banner takes its part of that banner down with it. A start that finds the proxy already up and showing a reachability fault (an automatic retry skipped because the same failure was just tried, or start_proxy on a live proxy) leaves that fault and its re-check as they are.

The check waits for the OS to settle, and a single miss no longer raises the banner. Starting the proxy runs the privileged setup, which kickstarts mDNSResponder and rewrites /etc/resolver — for a few seconds afterwards macOS legitimately fails to resolve names it is about to serve normally. Up to and including 3.6.14 the check was a single probe fired 1.5 s after that, so it often measured the settling window rather than the machine: the banner cleared on restart and came back "a few seconds later", then stayed up until the next start even though every URL worked. Current builds re-probe across roughly the first 13 seconds and only report a failure that outlives the whole window; a lookup that fails once is also retried before it counts as "doesn't resolve". Proxy start is not slowed — the check runs in the background.

A banner that no longer applies clears itself. While a reachability fault is showing, Supbuddy re-checks about every 45 seconds and takes the banner down as soon as the name resolves and the port answers again — so a machine that recovers on its own (a resolver reload finishing, Wi-Fi coming back, another device releasing an mDNS name) no longer needs a proxy restart just to stop showing a stale error. It is observation only: no password prompt, no repair, and no elevation. It also only clears the fault it raised — the very one, not an error that has since appeared in the same words — and if a port-forwarding failure has since claimed the banner, that one stays up, and clearing still requires Caddy to be serving and the 443 redirect (when you asked for one) to answer. The other way round, a repaired 443 redirect does not take down a fault about a name: a working redirect says nothing about whether the name resolves, so that fault stays until this re-check sees the name resolve and the port answer. The Retry banner, likewise, stays up for as long as something still needs the privileged step — a resolver rewrite that did not land, work that could not be confirmed, or such a fault — whatever the 443 redirect does, and get_health and get_proxy_status say the same (needsPrivilegedRepair). An automatic Caddy restart (the respawn after a crash, the wedged-Caddy heal, a LAN-sharing change) rewrites the proxy's status, and so used to hide such a fault. Now, when a reachability fault was showing as the restart began, Supbuddy runs the same check again once Caddy is back. It shows the fault again if it is still true, and leaves the proxy running if it has cleared. It is observation only, and on a healthy machine an automatic restart stays as silent as before. A Caddy that crashes while such a fault is showing is restarted, as any other crash is.

The most common case: the domain resolves to 127.0.0.1 but port 443 won't connect because the elevated pfctl 443→8443 redirect drifted away (typically after a restart, so Caddy is up on 8443 with nothing forwarding 443). Click Retry; as of v2.3.6 it re-applies the port-forwarding rule (approve the sudo prompt). On older builds, toggle the proxy off→on instead. If LAN sharing is off, disregard any "LAN sharing / Bonjour" wording in the banner; the cause is the missing forward, not mDNS.

If the name doesn't resolve at all, the banner now names the cause it actually measured. Before writing that message Supbuddy probes a name only /etc/resolver can answer, and says one of two different things:

  • The resolver path works, and the project is on .local. macOS reserves .local for Bonjour/mDNS (RFC 6762), and mDNS is consulted by a path an /etc/resolver/<suffix> file does not govern — so the OS can return "server not found" for a name whose resolver file is present and correct. Retrying rewrites files that were already right and asks for your password to do it, which is why the message names the durable fix instead: move the project off that TLD, in the project dialog (Settings → TLD) or with supbuddy project set <project> --tld=test. (This is not the .local slowness of 3.5.17 and earlier — that was our own DNS server and it is fixed. This is resolution failing outright, which the suffix genuinely can cause.)
  • The resolver path is dead — the OS is loading no /etc/resolver file at all. Up to 3.6.14 the banner told these users to change their TLD too. That advice is measurably wrong here: on the machine this was diagnosed on, .local, .test, .internal and .dev all failed while /etc/hosts worked, so no suffix recovers it. The banner now says the OS is not loading /etc/resolver, that changing TLD will not help, and that Supbuddy has written your domains into /etc/hosts as a fallback (or will on the next proxy start). See the /etc/hosts fallback.

Automatic repairs stop re-prompting. When the proxy is running but unreachable, Supbuddy re-runs the privileged setup to recover it — and that batch always asks for your password. In current builds an automatic attempt (the app re-attaching, a boot auto-start, the owner-ready repair) is skipped if the same failure was already re-applied within the last 10 minutes and didn't recover; the daemon logs one line and leaves the banner and its diagnosis standing. A repeated prompt that fixes nothing only teaches you to dismiss prompts. Anything you initiate — Retry in the app, supbuddy proxy restart, the MCP start_proxy — is never throttled, and a recovery, or a different fault, clears the cooldown immediately.

Port forwarding is on but 443 won't connect

Supbuddy reports port forwarding as active only when a live probe confirms 443 actually reaches Caddy — the rule being on disk isn't enough. If the rule is present but not being enforced (typically right after a reboot, or when an older Supbuddy version left /etc/pf.conf in a broken state), the status carries a pf_not_enforcing diagnostic instead of a false "enabled", and the banner tells you to restart the proxy to re-apply the redirect. Every repair — Retry, supbuddy proxy restart, doctor --fix, reload_port_forwarding and the automatic repair after a network change — turns pf back on before reloading the rules, so pf switched off behind Supbuddy's back (another tool's sudo pfctl -d, or a sleep or reboot without a daemon restart) is repaired too; reloading rules into a disabled pf leaves 443 just as dead.

After a network change or a wake, the repair asks in the app. A Wi-Fi change or a wake can drop the app's connection to the daemon for a moment, and with it the app's hold on the daemon's password prompts; a repair that ran then asked through sudo in the daemon instead, which has no terminal, and failed with "requires a TTY", leaving 443 dead until a Retry. Now the app claims the prompts again within a second of reconnecting and whenever the daemon asks, the daemon asks it to on every network change, and a privileged step that finds no app holding them, while one is connected or held them in the last minute, waits up to 15 seconds for it before the daemon tries itself. daemon.log says what happened to each privileged step: host-bridge: proxy:sudo-setup — owner: client … (or owner: none, then the wait and the claim), and answered by the app: succeeded or failed (<kind>), or handled in the daemon: …. An answer from an app the step was not sent to is not taken for it, and says so: [relay] host-bridge: ignored a reply to <type> from client …: it was sent to client …. A daemon no app is attached to, or was in the last minute, handles the step itself at once, as before: a supbuddy daemon running in a terminal asks there, and one started without a terminal fails as it always has.

If you see "not enforcing" or repeated password prompts with no mappings enabled, you are on a build older than 3.6.12. The 443 probe was gated on the Caddy process being alive rather than on something actually listening, so a project with no enabled mappings — whose Caddyfile has no site blocks, leaving nothing bound to 8443 — made a correctly-loaded pf rule look dead: NOT ENFORCING, the red banner, and a repair prompt on every network change. Current builds report that machine as unknown and stay quiet. To confirm your ruleset is fine: sudo pfctl -a 'virtual.localhost' -s nat lists both rdr rules.

Older versions appended their rdr-anchor to the end of /etc/pf.conf, after Apple's filter anchor — which pf rejects, because translation rules must come before filtering rules. That silently invalidated the whole ruleset, so every later pfctl -f failed and 443 was dead. Current builds insert the anchor in the correct translation section and self-heal a file corrupted by the old version on the next proxy start. Supbuddy keeps a single stable backup at /etc/pf.conf.supbuddy-backup (older builds accumulated unbounded timestamped backups). If pf refuses the new rules when they load, Supbuddy puts back the anchor and /etc/pf.conf exactly as they were just before that change, and reloads them; earlier builds copied the stable backup over /etc/pf.conf instead, losing any edit made since Supbuddy first changed it, and left the refused anchor in place. If a restart doesn't fix it, inspect /etc/pf.conf and confirm the rdr-anchor "virtual.localhost" line sits before anchor "com.apple/*".

Proxy came up but shows a degraded "error" state

If the one-time sudo prompt for port forwarding / DNS is cancelled or fails, Supbuddy no longer aborts the whole start. Caddy still starts and HTTPS keeps working on the high port (8443), and the CA is still generated; the proxy just shows an actionable error (degraded) state with a Retry. Click Retry and approve the sudo prompt to restore real-port (80/443) access and DNS. Until then, reach your apps on https://<domain>:8443.

Port already in use (8080, 8443, 5353, 9877)

Default ports: HTTP 8080, HTTPS 8443, DNS 5353, MCP 9877. The DNS server moves to the next free port by itself when its port is taken, and saves it. Change them in Settings → Network / Settings → MCP. Find what's holding a port: lsof -i :<port>.

Supabase says a port is already in use

A Supabase start or restart that finds one of its ports taken lists them, and what to do depends on the project's isolation:

  • Host: a project's Supabase on host runs on the ports its config.toml names, the CLI's stock 54320–54329 unless changed, so two such projects collide. Switch the project to Thin (switch_isolation { target_mode: "thin" }, supbuddy isolation switch <project> thin, or Isolation in the app), which gives it a port block of its own. Or stop the other project's Supabase first.
  • Thin: stop whatever holds the listed port. A start or restart first writes the project's managed port block back into a config.toml that lost it (a supabase init run in a terminal rewrites the stock block; see Thin), so the ports it lists are the project's own managed ports: do not edit them in config.toml.
  • Anything else (a legacy VM project): free the port, or stop the other project's Supabase first.

When the project's config.toml is there but Supbuddy won't read it (a link out of the project's folder, a FIFO), the check is made on the CLI's stock ports, and the refusal says so, with why the config wasn't read and how to fix it, in place of the advice above: switching to Thin refuses such a config too.

Find what holds a port with lsof -i :<port>.

Wipe everything and start over

Use supbuddy reset (see System reset) — it backs up anything you can't regenerate first, and it removes the things a plain rm -rf leaves behind (the pf redirect, the resolver files, the loopback aliases, the trusted CA):

supbuddy reset --tier=soft   # just the app state and caches
supbuddy reset --tier=deep   # + services, Caddy leftovers, /etc integrations, CA trust
supbuddy reset --tier=full   # + project data, repo artifacts, secrets, service, app data

The manual equivalent, if the CLI isn't available — quit Supbuddy first, and note that this deletes secrets/ and any backups under it with no copy anywhere:

# Wipe app data (state, certs, Caddyfile, logs, MCP tokens under secrets/)
rm -rf ~/Library/Application\ Support/Supbuddy

# Optional: remove the trusted CA
sudo security delete-certificate -c "Caddy Local Authority" /Library/Keychains/System.keychain

FAQ

Is Supbuddy free?

Yes. Supbuddy is free. Register as many projects and mappings as you want, with full HTTPS, full DNS, full Supabase isolation, and full read and write MCP access. There are no caps and no tiers.

Does Supbuddy send my data anywhere?

No. Caddy, the DNS server, and the MCP server all run locally on your Mac. The only outbound traffic is: Tailscale split-DNS reads and removals of Supbuddy's old routes (only if you set an API key), update checks (supbuddy.app), and Google Analytics on the marketing site (not the desktop app). The desktop app does not send telemetry.

Can I work offline?

Yes. The app works fully offline once the CA is trusted and projects are registered.

Linux / Windows support?

The desktop app is macOS-only in v2. The headless CLI and daemon also run on Linux, where supbuddy service install registers a systemd-user start-on-login unit (macOS uses launchd). Windows is not supported. A few desktop code paths (certutil, update-ca-certificates) anticipate other platforms but are not tested there.

Can I use my own TLD?

Yes. Set any TLD in Settings → General → Default TLD. Supbuddy installs /etc/resolver/<project-domain> files that tell macOS to query our DNS server for that project's domain. Avoid TLDs that actually resolve on the public internet (.com, .net, .dev, etc.): each project would take over a real internet name on this Mac, your browser will hit the real site for cached entries, and while Supbuddy is stopped names under that domain don't resolve on this machine. The app asks you to confirm one first (see Custom domains & TLDs).

What happens if I delete a project?

The project moves to the Trash (visible in Settings → MCP → Trash) for 7 days, then is permanently deleted by the sweep timer. Restoring brings back the project record and all its mappings.

How do I uninstall Supbuddy?

  1. Quit the app (the full reset refuses to run while it's open, because its watchdog restarts the daemon).
  2. Run supbuddy reset --tier=full and type RESET when it asks. This backs up your project data, then removes the containers, volumes, /etc integrations, CA trust, repo artifacts, credentials, the start-on-login service and the app-data directory — keeping <app-data>/backups/reset-<timestamp>/. See System reset, including the short list of things it deliberately leaves behind.
  3. Drag Supbuddy.app from /Applications to the Trash, and move the backups directory somewhere safe (or delete it).
  4. If you'd rather not use the CLI: see "Wipe everything and start over" above for the manual equivalent, plus sudo security delete-certificate -c "Caddy Local Authority" /Library/Keychains/System.keychain to remove the trusted CA.

Where do I report a bug?

Email support with your version (visible at the bottom of the Settings popover) and the relevant lines from ~/Library/Application Support/Supbuddy/main.log.