GenerateSaaSProjects
How the desktop app keeps its on-device data per project, and how a connected folder lets that project's chats and automations run in one of the user's own real folders.
The desktop app scopes everything it writes on the machine to the active project - the entity the web app switches, documented at Projects. Switching project switches chats, automations, per-task model overrides and the agent work folder at once.
| Follows the active project | Machine-global, shared by every project |
|---|---|
| Chats and their history | Connected CLIs and the device default model |
| Automations and their last-run result | Secrets held by the runtime |
| Per-task model overrides | CLI trust prompts and approvals, and MCP servers |
| The agent work folder, Terminal sessions included | The local audit log and model favorites |
Agent runtime gives the path each of these takes on disk.
Which workspace the app uses
The app scopes by project whenever either flag is on, so tenancy.multiTenant alone is enough:
projects.enabled | multiTenant | The app's workspace |
|---|---|---|
| off | off | one legacy bucket, byte-identical to a pre-projects app |
| off | on | each organization's first project, resolved invisibly - no switcher |
| on | off | the user's own projects, in a flat switcher |
| on | on | the active organization's projects, in one sidebar switcher that also picks the organization |
Automations tick for every project the app can still surface and stop, not only the active one. Leaving an organization, deleting a project, or signing out stops that project's automations on this device.
Data written under one workspace is never migrated to another. Turning multiTenant or projects on - or back off - in a shipped app leaves the previous bucket's chats and automations on disk but unaddressable, and stops those automations firing. Announce the flip to your users first.
Connected folders
A grant is durable, not per-session: after the consent dialog, every chat, automation and default-cwd Terminal session for that project reads and writes in the granted folder.
- Connect: Connect folder on the Project screen, which opens the OS native dialog. Needs
projects.enabledandconfig.desktop.agents.enabled. - Scope: one folder per project, unattended runs included, across restarts, for any account signed into this app on this device.
- Revoke: Disconnect, on the same card. The runtime accepts it whether or not
projects.enabledis on, but the button only renders while the flag is - so revoke before you turn it off.
| Situation | Behavior |
|---|---|
| No grant | The managed work folder. The normal case, not a failure |
| Grant present | The run's cwd, and the cwd its audit entry records |
| Grant broken - folder gone, moved, or now refused | The run fails and a Terminal session is refused, never a silent fall back |
| Terminal, folder picked by hand | The pick wins over the grant |
| Approvals | Machine-global, so what a user approved in the managed folder also applies in the connected one |
projects.enabled turned off | Every grant goes inert - they are consulted only while the flag is on - and the Disconnect control stops rendering, so nothing in the app can revoke one |
Folders the app refuses
A pick that would let an agent rewrite the app's own state, the user's credentials, or their machine's startup is refused with a code the UI translates:
| Code | Refuses |
|---|---|
APP_DATA / LOCAL_DATA | The app's data folder, and the local plane inside it |
SECRETS / CREDENTIAL_STORE | The app's secret store; on Windows the credential and DPAPI stores, plus the Chrome, Edge, Chromium, Brave and Firefox profile folders |
RUNTIME_IDENTITY | The runtime's identity and socket directory |
CODEX_CREDENTIALS | ~/.codex, the app's own Codex home, and a redirected $CODEX_HOME |
GROK_CREDENTIALS | ~/.grok, the app's own Grok home, and a redirected $GROK_HOME |
OPENCODE_CREDENTIALS | ~/.local/share/opencode, where opencode keeps its provider logins, and a redirected $XDG_DATA_HOME |
HOME_SENSITIVE | ~/.ssh, ~/.aws, the macOS keychain and browser profiles, and the rest of the sensitive-home set |
PERSISTENCE | Login items and autostart - macOS LaunchAgents and LaunchDaemons, ~/.config/autostart, ~/.config/systemd/user, the Windows Startup folder |
A folder is refused when it is, sits under, or contains a protected entry, so $HOME and / go too. Both sides are canonicalized and compared segment by segment, case- and Unicode-folded on macOS and Windows; a second drive or a network share is a legitimate target.
The check runs at four sites: the native dialog, the runtime's write of the grant, every run dispatch, and every Terminal grounding. Only the runtime is authoritative - it re-decides, and re-resolves the folder on every run. That narrows misuse to one run without closing the gap between check and process, so the OS user account stays the real boundary.