Files and folders

The Joppa folder

System	Location
macOS	~/Library/Application Support/joppa
Linux	~/.config/joppa

File or folder	Contents
config.json	Projects, domains, services and settings
processes.json	Project processes, when they’re not in a joppa.toml, and those of the worktree environments
team.json	For each project, the joppa.toml as this machine last applied (or ignored) it: Joppa tells what a git pull changes in it
running.json	The dev servers Joppa started that are running, to find them again if Joppa closes without stopping them
control.json	Port and token of the local API, for the joppa command (readable only by you)
reporter.json	The address verified for Report a bug and its token, valid 30 days (readable only by you)
telemetry.json	Your Privacy choices and the statistics’ random ID
crashes/	Crash reports not sent yet (only with Send crash reports on)
logs/	Joppa’s logs: joppa.log, and joppa.1.log past 5 MB (readable only by you)
ca/	The certificate authority: rootCA.pem and its key rootCA-key.pem (read-only)
snapshots/<volume>/<database>/	Database snapshots (Joppa Pro): one .dump (PostgreSQL) or .sql.gz (MySQL, MariaDB) and one .json per snapshot, the oldest deleted past Kept per database
analytics/	Per-domain stats, one row per minute, kept for 7 days
php/<version>/	Downloaded PHP builds
php/xdebug/<8.x>/	Xdebug for one PHP version: xdebug.so, the xdebug.ini that loads it and joppa.json (version, checksum)
bin/	The php and composer commands that follow .php-version
share/cloudflared	cloudflared, if it was downloaded with Download cloudflared for a public link (SHA-256 checksum verified)
share/known_hosts	The host keys of localhost.run and Pinggy, for their ssh tunnels

The license isn’t in this folder: it’s in the system keychain (service com.getjoppa.license), like the ngrok authtoken if one is saved (service com.getjoppa.ngrok).

In your projects

Joppa only writes to a project what you’ve confirmed:

File	When
.env	Linking a service, HTTPS addresses, editing (always with a diff)
.env.joppa-backup	Copy of the original .env, on the first write (a migration included)
joppa.toml	If you share the project’s configuration with the team (see joppa.toml)
.node-version, package.json	If you pin Node or the package manager
.php-version	If you pin PHP
.php.ini	If you write the project’s php.ini
vite.config.*, astro.config.*	If you click Fix the file

In a worktree that Joppa prepares: the .env, .env.local, .env.development(.local), .dev.vars and .php.ini files it’s missing, copied from the project with the worktree’s addresses. New worktree creates its folder next to the repository, in <project>-worktrees/.

Outside these folders

• Shell profile (~/.zshrc…): only the # >>> Joppa (PHP) >>> and # >>> Joppa (Node) >>> blocks, if you turn them on.
• Vite+: installed at first launch in its usual folders (~/.local/share/vite-plus and ~/.config/vite-plus, or ~/.vite-plus if it was already there), with Node LTS and bun. Joppa updates it every day.
• .test resolution: a file that sends *.test to Joppa’s DNS server (127.0.0.1:15353), written with your password: /etc/resolver/test on macOS, /etc/systemd/resolved.conf.d/joppa.conf or /etc/NetworkManager/dnsmasq.d/joppa.conf on Linux. It starts with a # Joppa line. See Resolving .test domains.
• joppa command: a link in /usr/local/bin or ~/.local/bin, if you install it.
• Assistants: the mcpServers.joppa entry in their config, if you connect them.
• Containers: joppa-<engine> and their joppa-<engine>-<version> volumes in your runtime.

Removing everything

Settings › Uninstall › Uninstall Joppa… lists what Joppa installed on this machine; tick what goes:

Item	What is removed
Assistants’ MCP server	The mcpServers.joppa entry of Claude Code, Claude Desktop and Cursor
joppa command	The joppa links in /usr/local/bin or ~/.local/bin
PHP and Node in the shell profile	The # >>> Joppa (PHP) >>> and # >>> Joppa (Node) >>> blocks of ~/.zshrc, ~/.bash_profile, ~/.bashrc and joppa.fish
Services’ containers	The joppa-<engine> containers and the images Joppa built for extensions
Services’ data	The joppa-<engine>-<version> volumes: databases, mails, indexes (unticked by default)
CA approval	“Joppa local CA” removed from your login keychain (your password), or from the System keychain if the terminal command put it there (administrator password)
.test resolution	Joppa’s resolver file (/etc/resolver/test…), with your password. Another tool’s file (Herd, Valet, dnsmasq) stays
License	This Mac’s seat freed, and the key removed from the keychain
Joppa’s folder	The folder above, and the window’s data (~/Library/WebKit/dev.joppa.app, caches…)
The app	Joppa.app (macOS) or the .AppImage file (Linux)

Joppa’s folder and the app are deleted once Joppa has quit: the button then reads Uninstall and quit. Files in your projects (.env, .env.joppa-backup, joppa.toml…) are never touched.

From the terminal, joppa uninstall does the same: see The joppa command › Uninstall.

A step that fails (password cancelled, runtime stopped, no network to free the license) is reported without stopping the others. To do it by hand: docker rm -f joppa-postgres, docker volume rm joppa-postgres-17, and on macOS Keychain Access › login (or System) › “Joppa local CA”.