# File locations

Where the Borago Board desktop app keeps its database, keys, logs, restore points, attachments and each project's Docker files on Linux, macOS and Windows.

The desktop app keeps everything in two places: an application data directory for the database, keys and logs, and a visible `Borago Board` folder in the home directory for each project's Docker files. Both are split per account. Nothing in either is removed by an uninstall. The cloud, the browser and the phone keep nothing of this on the device beyond the browser's own storage.

## The two roots

| Platform | Application data directory | Projects directory |
|---|---|---|
| Linux | `~/.config/Borago Board/` | `~/Borago Board/Projects/` |
| macOS | `~/Library/Application Support/Borago Board/` | `~/Borago Board/Projects/` |
| Windows | `%APPDATA%\Borago Board\` | `%USERPROFILE%\Borago Board\Projects\` |

The application data directory is the operating system's standard per-user application data location, named after the app. The projects directory is deliberately outside it, in a visible folder, because a confined Docker on Linux cannot read files inside a hidden directory and would fail to start a container from them.

The application data directory is also the default **data root**, the directory the per-account workspaces sit under. The bootstrap configuration file (below) holds the data root, so a user who edits it to point at another disk keeps the database, restore points and attachments there while the keys and the configuration stay in the application data directory. The examples on this page use the Linux paths.

## Device files at the root of the application data directory

These describe the installation, not an account. They are never synced and are shared by every account that signs in on the machine.

| File | What it holds |
|---|---|
| `config.json` | The bootstrap settings, including where the data folder is. Created with defaults on first launch. Everything else the app remembers lives in the database and is edited in Settings |
| `secret-key.json` | The key that protects stored credentials while the desktop is not signed in. It is sealed by the operating system's credential store (macOS Keychain, Windows DPAPI, a Linux Secret Service such as gnome-keyring or KWallet). When no store is available the app says so in Settings and in the notifications bell. See [Security](/security/) |
| `device-id.json` | A random installation id, sent to the cloud at sign-in so the account can link exactly one desktop. Not derived from hardware and used for nothing else |
| `device-account.json` | Which account's workspace this device opens. Kept across sign-out so the last board stays open. Absent on an install that has never signed in |
| `accounts.json` | One entry per account this desktop has signed in to: the email, the cloud session and the account's sealed key. Log out clears an entry's credentials and keeps it listed. Remove forgets the entry and leaves its workspace on disk |
| `speech-models/` | The dictation model, downloaded on first use. Kept once per device rather than per account |

## The account workspace

Under the data root there is one directory per account. Its name is `default` for work created while signed out, or the account's id (a UUID) once signed in. `default` means work that belongs to nobody yet. It follows the device to whichever account signs in next, and the first sign-in on a device renames the `default` directory into that account's directory rather than opening an empty board.

| Path inside `~/.config/Borago Board/<account>/` | What it holds |
|---|---|
| `borago.db` | The board: every project, task, comment, chat, note, notification and archived run, with credentials as ciphertext. Two sidecar files, `borago.db-wal` and `borago.db-shm`, belong to it and must stay beside it |
| `secret-history.jsonl` | The earlier values of each project secret, encrypted. 10 versions per project field are kept. It never syncs |
| `secret-holds.json` | Credential values that a change synced from another device removed, held on this machine as a soft delete until the user restores or deletes them |
| `restore-points/` | Whole-board copies taken before a new version of the app is allowed to change the database. Each is a full copy of the database file, with a small marker file beside it. 2 are kept. A restore chosen in Settings, then Data & recovery, is recorded here and applied at the next start |
| `images/` | The bytes of every attachment, one file per attachment, named by a storage key the database refers to. The database holds only the metadata |
| `logs/borago.log` | This account's application log. See below |

Read this before deleting a workspace. The database holds the encrypted provider credentials and project secrets, and the secret journal may be the only copy of a value that exists nowhere else. When cloud sync is on, the cloud has the synced half, but device-local values and anything created while signed out exist only here.

## The log

The log is written to `logs/borago.log` inside the account workspace, one per account. It is per account rather than per device because it names emails, project names, task titles and file paths, and **Report a problem** in Settings sends its last 60,000 characters. When the file grows past 5 MB it is renamed to `borago.log.1` and a new file is started, so at most one previous window is kept. Switching account moves the log to the incoming account's workspace after writing what the outgoing account produced.

An install that predates per-account logs may still have `logs/borago.log` directly under the application data directory. Nothing reads it any more and it can be deleted.

## The projects directory

Each project has a directory named after its project name in kebab case, under a directory per account with the same `default` or UUID name as the workspace, so two accounts on one machine can each have a project called "api" without one overwriting the other's files.

| Path inside `~/Borago Board/Projects/<account>/<project>/` | What it holds |
|---|---|
| `docker-compose.yml` | The Compose file the board generates for the project, or the user's own when one was supplied. Published ports, the startup script, the memory cap and the sandbox runtime are injected into it |
| `Dockerfile` | The generated Dockerfile, built from the chosen base image, or the user's own |
| `workspace/` | A folder that **Create a folder for me** in the project settings makes on the machine that runs the container, from any surface, and sets as the project's local path, so the container's `/app` is bound to it. A project given no local path has no bound folder, and its `/app` lives inside the container |

A deleted project's directory moves to `.recycled/<id>` under the same account directory while the project sits in the recycle bin, so a new project with the same name does not inherit its files. Restoring the project moves it back. Destroying it from the recycle bin removes the directory along with the project's containers, images, volumes and networks.

Environment variables and credentials are never written into any of these files. They are decrypted and handed to the container's process at the moment a run, a shell, a script or a flow starts.

On Linux with the gVisor sandbox, the app also writes a small DNS settings file for sandboxed containers at `~/.cache/borago-board/resolv.conf`.

## An AppImage on Linux

An AppImage is a single file that runs from wherever it was saved, typically the Downloads folder. Its name carries the version and the architecture, for example `BoragoBoard-0.12.3-x86_64.AppImage`. When the app updates itself it writes the new version's file beside the old one under the new name, removes the old file and restarts into the new one, so the file's location is wherever the previous one was.

An AppImage installs no menu entry on its own. The first time it runs the app asks once whether to add one, and Settings, then Application, has **Add to applications** and **Remove from applications**. Saying yes writes two files under the user's data directory (`~/.local/share`, or the directory named by `XDG_DATA_HOME`):

| File | What it is |
|---|---|
| `applications/borago-board.desktop` | The launcher entry, marked as written by the app so that removal touches only that file |
| `icons/hicolor/512x512/apps/borago-board.png` | The icon the entry and the taskbar use |

The entry points at the AppImage's path. After a self-update the app rewrites the entry to the new file's name at once, so the launcher does not point at a deleted file.

## An installed package on Linux

The deb and rpm packages install the application under `/opt/BoragoBoard/`, the `borago-board` command in `/usr/bin/`, a menu entry and icon under `/usr/share/`, an AppArmor profile, and the package repository the app updates from. Removing the package removes all of these and nothing under the home directory.

## What an uninstall leaves behind

Removing the app removes the app, its menu entry and its command. It leaves the application data directory, the projects directory, Docker itself, gVisor, and every project container, image and volume exactly as they were. That is deliberate, since an update is a remove followed by an install. The order that loses nothing, the commands that find every container the board created, and what to delete last are on the [uninstall page](/uninstall/), which the app also shows in Settings, then Legal, under **Uninstalling**.

Related: [Security](/security/), [Recovery](/docs/reference/recovery/), [Switching accounts on one machine](/docs/guides/switching-accounts/), [Recovering things](/docs/guides/recovering-things/), [Containers](/docs/reference/containers/).