# Where Are Workspace-Specific Configurations and Themes Stored in Craft Agents OSS

> Discover where Craft Agents OSS stores workspace configurations and themes. Find config json files in your workspace directories and themes in the resources folder.

- Repository: [Craft Ai Agents/craft-agents-oss](https://github.com/craft-ai-agents/craft-agents-oss)
- Tags: how-to-guide
- Published: 2026-07-04

---

**Workspace-specific configurations reside in [`config.json`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/config.json) files inside individual workspace directories under `~/.craft-agent/workspaces/`, while theme definitions are static JSON files shipped in `apps/electron/resources/themes/`.**

The craft-ai-agents/craft-agents-oss repository uses a file-based persistence layer for workspace settings and UI customization. Each workspace maintains its own isolated configuration directory, allowing granular control over permissions, default behaviors, and visual themes on a per-workspace basis.

## Workspace Configuration Storage Location

### The Root Directory Structure

All workspace data lives under the user's home directory in a dedicated dot-folder. According to the source code in [`packages/shared/src/workspaces/storage.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/workspaces/storage.ts), the system computes the default location using `getDefaultWorkspacesDir()`, which resolves to `~/.craft-agent/workspaces/`.

Each workspace occupies a subdirectory identified by its UUID or slug (for example, `~/.craft-agent/workspaces/my-workspace`). When a workspace is initialized, the system creates this folder alongside several metadata files including status, label, and permission files.

### The config.json File

The primary workspace configuration is stored in a file named [`config.json`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/config.json) at the root of the workspace directory. This JSON file contains UI-related preferences, default session settings, and the permission mode. The `loadWorkspaceConfig()` function in [`packages/shared/src/workspaces/storage.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/workspaces/storage.ts) handles reading this file, while `saveWorkspaceConfig()` persists changes.

```typescript
// packages/shared/src/workspaces/storage.ts
const CONFIG_DIR = join(homedir(), '.craft-agent');
const DEFAULT_WORKSPACES_DIR = join(CONFIG_DIR, 'workspaces');

/** Load workspace config.json from a workspace folder */
export function loadWorkspaceConfig(rootPath: string): WorkspaceConfig | null {
  const configPath = join(rootPath, 'config.json');
  // ... implementation details
}

```

## Theme Storage and Resolution

### Static Theme Definitions

Theme definitions are not stored per-workspace but are instead shipped as static assets with the Electron application. All built-in themes reside in **`apps/electron/resources/themes/`**, with each theme represented by a single JSON file (e.g., [`default.json`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/default.json), [`dracula.json`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/dracula.json), [`nord.json`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/nord.json)).

These files define color palettes including background, foreground, and accent colors. The build process copies these files into the application resources at build time via [`scripts/electron-build-resources.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/scripts/electron-build-resources.ts), though the source files remain in the repository path above.

```json
// apps/electron/resources/themes/dracula.json
{
  "name": "dracula",
  "type": "dark",
  "colors": { "background": "#282a36", "foreground": "#f8f8f2" }
}

```

### Theme Selection in Workspace Config

The connection between a workspace and its visual theme is established through the workspace configuration. The [`config.json`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/config.json) stores the selected theme name under the `theme` field (or nested under `defaults.theme`). When the UI initializes, it reads this value and loads the corresponding theme file from the static resources directory.

## Programmatic Access to Workspace Configurations

The `@craft-agent/shared` package exports utilities for interacting with these storage locations programmatically. This enables CLI tools and automation scripts to read or modify workspace settings without manual file manipulation.

```typescript
import {
  getWorkspacePath,
  loadWorkspaceConfig,
  saveWorkspaceConfig,
} from '@craft-agent/shared/workspaces';

// Assume we have a workspace id (e.g. from `craft-cli workspaces`)
const workspaceId = 'my-workspace';

// 1️⃣ Resolve the absolute path on disk
const workspaceRoot = getWorkspacePath(workspaceId);
// → ~/.craft-agent/workspaces/my-workspace

// 2️⃣ Load the existing config (or null if none)
const cfg = loadWorkspaceConfig(workspaceRoot);
console.log('Current config:', cfg);

// 3️⃣ Change the theme (e.g. to "dracula")
const newCfg = {
  ...cfg,
  defaults: {
    ...cfg?.defaults,
    theme: 'dracula',            // ← theme name stored in config.json
  },
};

// 4️⃣ Persist the changes
saveWorkspaceConfig(workspaceRoot, newCfg);

```

## Summary

- **Workspace directories** are stored under `~/.craft-agent/workspaces/` with each workspace having its own subdirectory identified by UUID or slug.
- **Configuration files** named [`config.json`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/config.json) in each workspace root contain preferences including the selected theme, managed by [`packages/shared/src/workspaces/storage.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/workspaces/storage.ts).
- **Theme definitions** are static JSON files located in `apps/electron/resources/themes/` and are referenced by name in the workspace configuration.
- **Programmatic access** is available through the shared workspace utilities to resolve paths, load configurations, and persist changes.

## Frequently Asked Questions

### Can I manually edit the config.json file for a workspace?

Yes, you can manually edit [`config.json`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/config.json) located in `~/.craft-agent/workspaces/<workspace-id>/`. The JSON structure follows the `WorkspaceConfig` type defined in [`packages/shared/src/workspaces/types.ts`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/packages/shared/src/workspaces/types.ts). Changes take effect the next time the workspace loads, though manual editing carries the risk of JSON syntax errors that could prevent the workspace from loading properly.

### How do I add a custom theme to my Craft Agents installation?

Custom themes require adding a new JSON file to the `apps/electron/resources/themes/` directory with a valid theme structure (name, type, colors object), then rebuilding the application. Alternatively, you can modify an existing theme file, as the UI loads themes by filename. The theme name referenced in your workspace's [`config.json`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/config.json) must match the filename (without the `.json` extension).

### Where does the application store workspace-specific API keys or secrets?

The [`config.json`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/config.json) file stores workspace-specific settings including permission modes and default configurations, but sensitive credentials should be referenced through environment variables or secure credential stores rather than plain text in this file. The permission mode field in the configuration determines the security context for the workspace session.

### What happens if the config.json file is corrupted or deleted?

If [`config.json`](https://github.com/craft-ai-agents/craft-agents-oss/blob/main/config.json) is missing or corrupted, `loadWorkspaceConfig()` returns `null` as indicated in the storage implementation. The application typically regenerates a default configuration upon the next save operation or workspace initialization, though you may lose customized settings such as theme preferences or default session parameters.