GrigDesk data folder
Everything the server does — chats, routes, profiles, plugins and state — lives in a single folder. It is created on first start and is moved or backed up as a whole.
Where it is
By default GrigDesk stores its data in ~/.grigdesk — the home directory of the user the server runs as. To place the data elsewhere, override the path with the GRIGDESK_HOME variable; machine settings live in the .env file inside the same folder.
The folder appears automatically on first start. There is nothing to create by hand: subfolders are added as you start using the corresponding feature — pairing a phone or opening the 3D section, for example.
What is inside
| Folder | Contents |
|---|---|
.env | Machine settings: server environment variables — port, paths, runners. |
state/ | Live server state: log, login sessions, settings, connection profiles, runner installs. |
chats/ | Agent chat history: files grouped by month, attachments and conversation turns. |
artifacts/ | Agent workspace: screenshots, review reports, dumps and prepared files. |
factory/ | Pipeline engine state: published routes, run journals, stage settings. |
profiles/ | Project profiles: environment, runners and review rules for each project. |
plugins/ | Installed plugins; their data is kept separately in state/plugins/. |
drivers/ | Installed tracker drivers. |
db-engines/ | Installed external database engines. |
runtimes/ | Shipped runtimes: server updates and packages of the built-in DeepSeek runner. |
mobile/ | Phone access: server TLS certificates and paired devices. |
telegram/, github/ | Archives of inbox channels. |
3d/ | The 3D section library: models, generation jobs and uploads. |
browser/ | Service socket of the built-in browser. |
provider-cli-leases/ | Locks against simultaneous starts of external CLI runners. |
Server state — state/
The broadest folder. The server maintains it itself; the files are not meant for manual editing:
grigdesk-server.log— the server log, with compressed rotations next to it;server.lock— guard against a second server instance;auth-sessions.json— login sessions;prefs.json— interface settings;models.json— registry of runner models;ssh/,db/— connection profiles and audit journals for SSH and databases;web-log/— web interface journal;tickets/,sandboxes/— internal tasks and manual sandboxes;provider-installs/— state of installed CLI runners;plugins/— plugin data, separated from plugin packages;ui-releases/— downloaded web interface updates;mobile-apk/— the mobile application APK;media-venv/,hf/,speech-install/— speech recognition and synthesis environments and models;tracker-data/— working data of connected trackers;arbiter-cards.json,task-shelf.jsonand other files of personal hints and lists.
Pipeline engine — factory/
routes/— published routes: every version is immutable;state/— run journals and results;control/— trusted stage settings of specific runs;config/— engine settings;analysis/— task triage notes.
Privacy and backups
- A backup is the whole folder: subfolders are not interchangeable, and part of the state changes with every agent turn. Stop the server before copying.
- The folder contains sensitive data: login sessions and tokens in
state/, TLS keys and the device journal inmobile/, tracker credentials. Do not publish or share the folder; keep the copy in a protected place. - Deleting the folder erases chat history, routes, profiles and settings beyond recovery, so subfolders are not cleaned by hand.
Related pages
- Architecture — where the work runs and how the components connect.
- Installation — first start and updates.
- Project profiles — what lives in
profiles/. - Routes — how published route versions work.
- Plugins — installing and structuring packages.
- Task trackers — the drivers in
drivers/. - Databases — connection profiles and external engines.