# How to Access and Modify Orca Configuration Files: Paths, Patterns, and APIs

> Learn to access and modify Orca configuration files. Discover global and project-specific JSON paths, understand file patterns, and leverage the IFilesystemProvider API for programmatic changes.

- Repository: [Stably/orca](https://github.com/stablyai/orca)
- Tags: how-to-guide
- Published: 2026-05-25

---

**Orca stores user-level settings in plain JSON files located in `~/.copilot/config.json` for global preferences and `<repo>/.superset/config.json` for project-specific UI customizations, which you can edit manually or modify programmatically via the `IFilesystemProvider` API.**

Orca, the AI-assisted development environment from Stably AI (`stablyai/orca`), persists all mutable user settings in human-readable JSON files rather than opaque databases. Understanding how to **access and modify Orca configuration files** allows you to automate workspace setup, customize external app integrations, and manage trust settings across local and remote worktrees.

## Configuration File Locations

Orca organizes settings into three distinct scopes. According to the source code in `stablyai/orca`, the runtime resolves these paths using Node’s `os.homedir()` for global configs and repository roots for project-local settings.

### Copilot Configuration (`~/.copilot/config.json`)

The primary user config file resides at `~/.copilot/config.json`. As implemented in [[`src/main/runtime/orca-runtime.ts`](https://github.com/stablyai/orca/blob/main/src/main/runtime/orca-runtime.ts)](https://github.com/stablyai/orca/blob/main/src/main/runtime/orca-runtime.ts#L6800), this file stores:

- **Trusted worktree folders** – Absolute paths the user has marked as safe
- **Telemetry preferences** – Opt-in/out flags for analytics  
- **UI state** – Persistent interface customizations

When working with remote worktrees over SSH, Orca resolves the remote `$HOME` directory and creates an identical `~/.copilot` folder structure on the remote host using the `markRemoteCopilotFolderTrusted` helper (lines 6800–6905).

### Claude Configuration (`~/.claude/`)

Credential caching for Claude agents uses `~/.claude/.claude.json` or `~/.claude/.config.json`. The [`claude-accounts/service.ts`](https://github.com/stablyai/orca/blob/main/claude-accounts/service.ts) module (line 365) handles OAuth tokens and session data in these files.

### Superset Configuration (Project-Local)

Repository-specific UI customizations live in `<repo>/.superset/config.json`. Defined in [[`src/shared/setup-script-imports.ts`](https://github.com/stablyai/orca/blob/main/src/shared/setup-script-imports.ts)](https://github.com/stablyai/orca/blob/main/src/shared/setup-script-imports.ts#L15), this file controls the "open-in" menu mapping file extensions to external applications.

## How Orca Reads and Writes Configuration Files

Orca abstracts filesystem access through the `IFilesystemProvider` interface rather than using raw Node.js `fs` calls directly. This pattern ensures compatibility with both local and remote (SSH) filesystems.

The read-modify-write cycle follows this structure, as seen in [`orca-runtime.ts`](https://github.com/stablyai/orca/blob/main/orca-runtime.ts):

```typescript
const configDir = `${remoteHome}/.copilot`;
const configPath = `${configDir}/config.json`;
const raw = await this.readRemoteTextFile(fsProvider, configPath);
let config: Record<string, unknown> = {};

if (raw.trim()) {
  try {
    const parsed = JSON.parse(raw);
    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
      config = parsed as Record<string, unknown>;
    }
  } catch {
    // malformed JSON → ignore, keep empty config
  }
}

// … mutate config …
await fsProvider.createDir(configDir);
await fsProvider.writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`);

```

The runtime validates JSON structure before mutation and uses `fsProvider.createDir` to ensure directory existence before writing.

## Modifying Configuration Manually

Because these are plain JSON files, you can edit them with any text editor. Common modifications include:

### Adding Trusted Worktrees

To bypass trust prompts for a specific folder, add its absolute path to the `trustedFolders` array:

```json
{
  "trustedFolders": [
    "/home/user/projects/worktree-1",
    "/home/user/projects/worktree-2"
  ]
}

```

### Customizing the "Open-In" Menu

Edit `<repo>/.superset/config.json` to map file extensions to applications:

```json
{
  "openIn": {
    ".png": ["Preview", "ImageEditor"],
    ".js": ["VS Code", "Node REPL"]
  }
}

```

### Disabling Telemetry

Set the telemetry flag in `~/.copilot/config.json`:

```json
{
  "telemetry": { "enabled": false }
}

```

## Programmatic Modification via the Orca API

When building plugins or scripts that run inside Orca, use the provided helper functions rather than direct file manipulation.

### Using `markRemoteCopilotFolderTrusted`

This function (lines 6800–6905 of [`orca-runtime.ts`](https://github.com/stablyai/orca/blob/main/orca-runtime.ts)) atomically updates the trusted folders list on both local and remote hosts.

### Generic File Operations with `IFilesystemProvider`

For Superset or custom configs, use the filesystem provider methods:

```typescript
import { IFilesystemProvider } from '@/main/ipc/filesystem-provider';
import { join } from 'path';

export async function addSupersetEntry(
  fs: IFilesystemProvider,
  repoRoot: string,
  extension: string,
  apps: string[]
) {
  const cfgPath = join(repoRoot, '.superset', 'config.json');
  
  let cfg: Record<string, unknown> = {};
  try {
    const raw = await fs.readFile(cfgPath, 'utf-8');
    cfg = JSON.parse(raw);
  } catch {
    // File missing or malformed – start fresh
  }
  
  (cfg as any).openIn = (cfg as any).openIn || {};
  (cfg as any).openIn[extension] = apps;
  
  await fs.createDir(join(repoRoot, '.superset'));
  await fs.writeFile(cfgPath, JSON.stringify(cfg, null, 2) + '\n');
}

```

This pattern mirrors the test implementation in [[`src/shared/setup-script-imports.test.ts`](https://github.com/stablyai/orca/blob/main/src/shared/setup-script-imports.test.ts)](https://github.com/stablyai/orca/blob/main/src/shared/setup-script-imports.test.ts#L12-L35).

## Summary

- **Orca uses JSON configs**: Global settings live in `~/.copilot/config.json`, while project-specific UI rules reside in `<repo>/.superset/config.json`.
- **Remote support**: The `markRemoteCopilotFolderTrusted` function in [`orca-runtime.ts`](https://github.com/stablyai/orca/blob/main/orca-runtime.ts) ensures configs sync to remote SSH worktrees.
- **Abstraction layer**: Always use `IFilesystemProvider` for programmatic access to support both local and remote filesystems transparently.
- **Safe editing**: Validate JSON before parsing, use `createDir` before writing, and pretty-print with 2-space indentation to match Orca's formatting.

## Frequently Asked Questions

### Where does Orca store its global configuration files?

Orca stores global user preferences in `~/.copilot/config.json` inside your home directory. For remote worktrees accessed via SSH, it creates a parallel `.copilot` folder in the remote user's home directory to maintain consistent trust and telemetry settings across environments.

### Can I edit Orca's configuration files while the application is running?

Yes. Orca reads these JSON files on-demand rather than holding persistent locks. However, programmatic modifications should use the `IFilesystemProvider` interface to ensure atomic writes and proper directory creation, as demonstrated in [`src/main/runtime/orca-runtime.ts`](https://github.com/stablyai/orca/blob/main/src/main/runtime/orca-runtime.ts).

### How do I programmatically mark a folder as trusted in Orca?

Use the `markRemoteCopilotFolderTrusted` method available in the Orca runtime, which handles the read-modify-write cycle safely. Alternatively, manually append the absolute path to the `trustedFolders` array in `~/.copilot/config.json` and ensure valid JSON syntax.

### What is the difference between Copilot config and Superset config?

The **Copilot config** (`~/.copilot/config.json`) contains global user settings like telemetry preferences and trusted worktrees. The **Superset config** (`<repo>/.superset/config.json`) is project-local and defines repository-specific UI behaviors, such as which external applications appear in the "open-in" context menu for specific file extensions.