Docs · Start here

What the cats share

One theme, one AI connection, one set of Git accounts, one set of local domains and the links between the apps — and what each cat keeps to itself.

DevCatz, DBCatz, DialCatz and DoCatz are separate apps: install one, two or all four, and each works on its own. When several are on the same computer they share a few things, so you set them once instead of four times. Nothing is shared over the network — it is all files and Keychain itemsentries in Windows’ protected storage (DPAPI) on your computer. (All four cats run on macOS and Windows, and share the same way on both.)

The shared settings file

The apps keep what they share in one small file:

~/Library/Application Support/Catzoid/shared.json

Only you can read it (the folder is 0700, the file 0600).

%APPDATA%\Catzoid\shared.json

It sits in your own profile, so only your account reads it.

Every app watches it, so a change made in one app shows up in the others right away, without a restart. It holds:

Part What it is Set it in
theme Auto, Light or Dark Settings → General → Appearance in any app
ai The AI provider, the model picked for each provider, custom addresses Settings → AI in any app
git Your connected Git hosting accounts — names and hosts, never tokens DialCatz → Git → Accounts
domains The default domain ending, the local certificate authority, names without a port, and which apps rely on them DoCatz → Settings → Domains, or DevCatz → Settings → General → Default domain (DevCatz and DoCatz only)
site The address the apps use for docs, updates, downloads and reports — (always catzoid.com)

Secrets are never in this file. They live in the macOS KeychainWindows’ protected storage (below).

One theme

Pick Auto, Light or Dark in any cat’s Settings and the others follow. Auto follows your system’s appearance setting. The Settings sections that change shared things wear a Shared with Catzoid apps badge.

One AI connection

The provider (Claude by default; also OpenAI, Gemini, Z.ai, DeepSeek, Mistral, xAI, Groq, OpenRouter, Ollama and any OpenAI-compatible server), its model and its address are shared. So is the key: each provider’s API key is kept in the Keychain item Catzoid AI, one entry per providerin Windows’ protected storage (DPAPI), one file per provider under %APPDATA%\Catzoid\keys\, readable only by your account. Paste a key in DBCatz and DevCatz can use it too.

What is not shared: whether AI is on at all, and each AI feature’s switch. Every app starts with AI off and you turn it on per app — turning it on in DevCatz does not wake it in DBCatz. Each app’s own page says exactly what its AI features send: DevCatz, DBCatz, DialCatz, DoCatz.

Git accounts

Connect GitHub, GitLab, Gitea / Forgejo or Bitbucket once — in DevCatz or in DialCatz — and the other cat has it too. The account (name, host, avatar) goes into shared.json; its personal access token goes into the Keychain item Catzoid GitWindows’ protected storage (DPAPI), under %APPDATA%\Catzoid\git\. Removing an account removes it — and its token — for every cat on this computer.

The Git section itself — changes, history, branches, stashes, tags, worktrees and pull requests — looks and works the same in both apps. See Git in DevCatz and Git in DialCatz.

Both apps use the git on your computer with your own config, credential helper and SSH agent, and the SSH keys in ~/.ssh. Without one, the page says git is not installed: install Git for Windows from git-scm.com.

Keychain items

Keychain item Holds Used by
Catzoid AI One API key per AI provider Every cat
Catzoid Git One token per connected Git account DevCatz, DialCatz
DevCatz Safe Storage The key that encrypts DevCatz’s own secrets DevCatz
DBCatz Safe Storage The key that encrypts saved connection passwords, SSH passphrases, AWS keys and Vault tokens DBCatz
DialCatz Den Each device’s token for your team’s DialCatz Den DialCatz

On Windows the same secrets live in Windows’ protected storage (DPAPI), tied to your account: no other user of the PC can decrypt them.

Secret Holds Where
Catzoid AI One API key per AI provider %APPDATA%\Catzoid\keys\
Catzoid Git One token per connected Git account %APPDATA%\Catzoid\git\
DevCatz Safe Storage The key that encrypts DevCatz’s own secrets (database passwords, tunnel tokens) Windows’ protected storage, used by DevCatz’s settings

DBCatz’s and DialCatz’s items follow when they come to Windows.

One set of local domains (DevCatz and DoCatz)

DevCatz gives your sites names like https://shop.localhost; DoCatz gives every container one like https://web.shop.docatz.localhost. They share the pieces behind those names instead of each bringing its own:

  • The domain ending — .localhost unless you pick another; change it in either app and both follow.
  • The local certificate authority — DevCatz’s DevCatz Local CA when DevCatz made it first, else Catzoid Local CA, made by DoCatz. Trust it once and both cats’ names open on https:// without warnings.
  • Names without a port — there is only ever one forwarding of ports 443 and 80 on a computer. With DevCatz installed it points at DevCatz’s proxy, so its sites keep working, and DevCatz hands every *.docatz.<ending> name on to DoCatz. Without DevCatz it points at DoCatz’s own proxy.
  • The small DNS server for your ending and, on Windows, for .localhost — the same server on the same address; whichever app runs answers for both.

While DevCatz is closed, DoCatz stands in on DevCatz’s ports and answers for its own names; a DevCatz site then shows a page that says Open DevCatz to serve it. DoCatz lets go of the ports within about two seconds of DevCatz starting. Uninstalling one of them leaves these pieces in place while the other still uses them. See what the cats change on your computer.

How the cats find each other

The apps never talk to each other over a port. One app writes a small file in its own data folder; the other reads it.

From → to Through What you get
DevCatz → DBCatz DevCatz/dbcatz/services.json The databases DevCatz runs appear in DBCatz as DevCatz services, with a live status dot — no host, port or password to copy.
DevCatz → DialCatz DevCatz’s bridge.json Each site becomes a DialCatz environment (its https://*.localhost address and the names of its .env variables); its routes or OpenAPI document become a collection.
DBCatz → DialCatz DBCatz’s bridge.json DialCatz knows your connections (names, engines, hosts — no users or passwords) for Check in DBCatz.
DoCatz → DevCatz DoCatz’s bridge.json The engine’s state, DoCatz’s proxy ports (so DevCatz can hand *.docatz names on) and its containers: name, compose project and service, image, state, ports and URL — never environment values, mounts, labels or secrets.
DevCatz → DoCatz The docatz Docker context and DoCatz’s own docker DevCatz’s Docker tab tests a site’s compose file on DoCatz’s engine — Build & Up, Down, the logs — with the project’s .env kept in DoCatz, and Open in DoCatz shows those containers. The two also share one default domain, one local certificate and one set of names without a port (above).
DevCatz → DoCatz (Windows) DevCatz’s bridge.json What DevCatz runs in DoCatz’s engine — its Docker gateways (devcatz-gw-<kind>) and the servers with no Windows build, Typesense, Sonic and Sockudo (devcatz-svc-<kind>) — shows up in DoCatz as a read-only DevCatz Services group.
DoCatz → DialCatz DoCatz’s bridge.json A compose project’s API services — an API framework, or a plain image with an OpenAPI file in its own folder; front ends and workers stay out — become a DialCatz environment DoCatz · <project> (baseUrl plus a <service>Url for each); their routes — Laravel’s route list from php artisan inside the container, or an OpenAPI document — become a collection, one per service with All. Open in DialCatz on an API container in DoCatz opens that import; importing again adds only the new routes.
DoCatz → DBCatz DoCatz/dbcatz/services.json (readable by you only) Each database container’s engine, version, address on this computer (127.0.0.1:<port>, the engine’s own port plus 10000 — 15432, 13306, 16379 …) and the user, password and database the image was started with. The running database services show up in DBCatz by themselves as DoCatz services, like DevCatz services, and Open in DBCatz on a database in DoCatz opens that very service. services.json also names each database’s container, so DBCatz’s Open in DoCatz comes back to its page.

And they open each other with links:

Link Opens
dbcatz://open?conn=…&db=…&table=… A connection, database or table in DBCatz — at a row, from DialCatz’s Check in DBCatz. Nothing in a link runs as SQL.
dbcatz://url?u=… A connection URL, for this session only
devcatz://db/<service> A database service in DevCatz (Open in DevCatz in DBCatz)
dialcatz://open?site=… A DevCatz site in DialCatz (Open in DialCatz in DevCatz)
dbcatz://open?docatz=… A DoCatz database container in DBCatz (Open in DBCatz in DoCatz) — the link carries no password
dialcatz://open?docatz=…&service=… A DoCatz project’s import in DialCatz, with that service picked (Open in DialCatz on an API container in DoCatz). Works when DialCatz is not running yet: the link waits for its window.
docatz://compose?path=… A site’s compose project in DoCatz (Open in DoCatz on DevCatz’s Docker tab). If it is not running, DoCatz opens the compose file, ready for Up — a link never runs anything.
docatz://open?site=… DoCatz on its Containers page
docatz://container/<name> One container’s page in DoCatz (Open in DoCatz on a DoCatz service in DBCatz)
docatz://gateways?kind=… · docatz://services?kind=… Windows: one of DevCatz’s gateways or servers in DoCatz’s DevCatz Services group
devcatz://gateways/<kind> · devcatz://services/<kind> Windows: that gateway or server (Typesense, Sonic, Sockudo) in DevCatz (Open in DevCatz in DoCatz); ?install=1 opens its install dialog, ?action=start|stop|restart runs that action

Installing each other

When a button needs a sibling that is not installed — Open in DBCatz, Open in DialCatz, Install DevCatz, Get DBCatz — the app downloads the right build for this computer (Apple silicon, Intel or Windows) from catzoid.com, or says plainly that there is no build for it yet. It never hands you another platform’s file. On Windows the cats install each other the same way. DevCatz’s Docker tab installs DoCatz like that too (Download & Install), and so does DoCatz for any sibling a button needs — Open in DevCatz, Open in DBCatz, Open in DialCatz: it asks catzoid.com for this computer’s build, checks it against its SHA-256 and installs it (into Applicationsfor your account), using the GitHub release only when the site cannot be reached.

The same family habits

  • Built with Electron. All four cats are Electron apps, so they look and behave the same on macOS and on Windows. How light are the cats? has the measured cost and why.
  • Settings, About, Updates, Report a Bug, Uninstall and the Welcome dialog are laid out the same way in each app.
  • Updates come from catzoid.com with the GitHub release as a fallback: checked 30 seconds after launch and then every 6 hours (if you leave Check automatically on), and nothing downloads until you say so.
  • Back and forward (mod+[ / mod+]) walk through the screens you visited, in every app.
  • Ask ✦ — each app’s plain-words assistant opens with mod+K and asks before every step.

What each cat keeps to itself

Its own data folder in ~/Library/Application Support/%APPDATA%\ (DevCatz, DBCatz, DialCatz, DoCatz), its own AI on / off and feature switches, its own update settings and its own crash-report choice. DoCatz also keeps its engine — the VMWSL distro and its disk, its docker, compose and buildx — in ~/.docatz%USERPROFILE%\.docatz, and the .env files you keep in DoCatz stay DoCatz’s alone. Uninstalling one cat leaves the shared settings alone while another cat still uses them; the last one to go offers Also remove the shared Catzoid settings. See Uninstall and What the apps send.

Last updated 2026-11-03

← PreviousTroubleshootingNext →What the cats change on your computer