Folders and environment variables

JETCARP keeps its files in three folders: one for settings, one for data and one for output. Each has an environment variable that moves it, so tests, scripts and portable installs can keep JETCARP away from your own folders. jetcarp paths prints the three folders as JETCARP sees them, with any overrides applied:

$ jetcarp paths
settings: /home/ada/.config/jetcarp
data:     /home/ada/.local/share/jetcarp
output:   /home/ada/Pictures/JETCARP
bundled:  /home/ada/.local/lib/jetcarp/packs

The last line is the folder of packs that came with the program, the starter pack, which JETCARP reads and never writes; it says (no packs came with the program) when there is none, as after cargo install. Where it is looked for is in Installing JETCARP.

jetcarp paths --json prints the same as JSON (the last as bundled_packs, null when there is none). jetcarp doctor adds the catalog file, how much data is in use, the starter pack’s size (or where it looked for one), and every JETCARP_… variable that is set, which makes it the thing to paste into a bug report.

The three folders

The defaults are the operating system’s own folders. On Linux they follow the XDG settings ($XDG_CONFIG_HOME, $XDG_DATA_HOME and the Pictures folder in user-dirs.dirs), so the paths above are only the usual case. On Windows the data goes in the local application-data folder, not the roaming one, because search databases can be large. On macOS the settings and data folders would be the same, so the data goes in a data folder inside it.

If the system has no such folder, JETCARP falls back: without a settings folder, settings are simply not saved; without a data folder, it uses jetcarp-data in the current folder; without a Pictures folder, ~/Pictures/JETCARP, and failing that jetcarp-out in the current folder. An override set to an empty value counts as not set.

What lives in each folder

Settings. app.json holds the app’s layout, panes, tool windows and display settings, and host.json the background host’s. Screensaver profiles are in screensavers/ and rotations in rotations/, one JSON file each. The host records the command that starts it in host-program, for GNOME’s menu and the Windows screen saver; while it shows a still picture as your desktop background it keeps the stills in desktop-pictures/ and remembers your own picture in desktop-picture.json, so that it can put it back. Files written by another settings version, or that cannot be read, give the defaults.

Data.

• library.sqlite, the pattern library: every verified pattern with the rules it works in and where it was seen, the jobs and their checkpoints, census results, every Quick Start entry (the built-in examples, entries from packs, the atlas and your own), ratings, and ant and turmite runs, each with its provenance and geometry pin (see Library format). Beside it, SQLite’s own -wal and -shm files, a library.sqlite-jobs/ folder of lock files (one per job, so two programs never run the same job), and media/, the frames, animations and thumbnails rendered for the library’s records, each file stored once under the SHA-256 of its bytes as media/ab/<sha256>.<ext> (see Library format). jetcarp media list KIND ID shows a record’s files, jetcarp media export KIND ID --to DIR copies them out under readable names, and jetcarp media gc deletes the files no record uses any more. JETCARP_LIBRARY moves the library (see below), and its media and lock files move with it.
• searches/, one folder per exploratory search, beside the library and moving with it: searches/<uuid>/ holds the search’s runs as Parquet files (runs/part-000001.parquet, a million runs each), a manifest.json, and its working database search.sqlite (its saved state and its newest runs); see Search runs. Reviews of a search’s runs are kept in the library, so deleting a search folder keeps them, and so is the atlas that jetcarp quickstart publish picks from a search (see Quick Start entries).

Output. Everything JETCARP makes for you to look at: pictures, the folders of script runs and sweeps (each with a manifest.json, and favourites.json for the runs you star), piles/ for large sandpiles, wallpapers/, media/<name> for a scene (or a built-in Quick Start entry) rendered with jetcarp media render, under readable names, and the run folders of evolutionary searches. Script runs, sweeps, sandpiles and evolutionary searches get folders named with the time they were made and a label, such as 2026-11-05_14-30-02_my-sweep or piles/2026-11-05_14-30-02_hex-10000. Scripts can write only inside the output folder and folders they are explicitly allowed. Commands that write a single file, such as jetcarp run --png, write where you tell them.

Runtime. One more, small folder holds the files through which the running app and the background host accept local control (their port and access token): $XDG_RUNTIME_DIR/jetcarp, else ~/.cache/jetcarp, on Linux and macOS, and %LOCALAPPDATA%\jetcarp on Windows.

To remove what JETCARP set up outside these folders, and optionally the folders themselves, see Uninstalling.

Environment variables

For everyone

A safe way to try JETCARP without touching your own folders is to point the first four at scratch folders. This is what JETCARP’s continuous-integration tests do:

export JETCARP_CONFIG_DIR=/scratch/jetcarp/config
export JETCARP_DATA_DIR=/scratch/jetcarp/data
export JETCARP_OUT=/scratch/jetcarp/out
export JETCARP_LIBRARY=/scratch/jetcarp/library
jetcarp paths

For development and debugging

These are read by JETCARP but meant for its developers: headless screenshot checks of the app, timing traces, and test fixtures. They may change without notice.