Configuration layout
Where Isolade keeps config, secrets, and local state on disk.
Isolade follows the XDG base-directory layout. Configuration is meant to be tracked in git, but secret values and local state are not.
What lives where
| Path | Purpose | In git? |
|---|---|---|
~/.config/isolade/config.env | Sandbox port and URL, default image | yes |
~/.config/isolade/workspaces/<name>/config.toml | One directory per workspace, holding its definition | yes |
| OS credential store | Per-workspace secret values entered in the UI | never on disk |
~/.local/share/isolade/isolade.db | Build state, instances, agents, chats | local data |
~/.local/share/isolade/registry/ | In-process OCI registry: index plus content-addressed blobs | local data |
~/.local/share/isolade/auth/ | Harvested Claude/Codex credentials, mode 0600 | never |
The OS credential store is Keychain on macOS and libsecret on Linux.
Tracking config in git
To keep your configuration in a personal dotfiles repo, run git init inside ~/.config/isolade/. The default .gitignore already excludes secrets.env. Because secret values live in the OS credential store, they never reach the repo.
How workspaces are registered
On startup, Isolade reconciles ~/.config/isolade/workspaces/. Each subdirectory that contains a config.toml is a registered workspace, and the directory name is its id.
- A new directory gets an initial build.
- A removed directory has its pushed image deleted from the registry.
Workspaces are added and removed only by editing this directory. There is no POST /api/workspaces or DELETE /api/workspaces/:id. This keeps the set of workspaces reproducible from the files in git.
config.env
A small file for runtime knobs, safe to commit:
# Sandbox HTTP port and the URL the server uses to reach it.
SANDBOX_PORT=7778
# ISOLADE_SANDBOX_URL=http://localhost:7778
# Image used when an instance is created without a workspace.
# DEFAULT_IMAGE=For the full workspace definition, see Workspaces.