Configuration

Settings File

Braide stores its settings at:

~/.braide/settings.json

This file is managed automatically by the app. It contains:

{
  "theme": "system",
  "selectedProjectId": "...",
  "enabledAgents": ["agent-id-1", "agent-id-2"],
  "registries": [
    { "url": "https://...", "active": true }
  ],
  "terminalStates": {
    "session-id": { "open": true, "height": 300 }
  },
  "agentMeta": {
    "agent-id-1": { "tenant": "acme", "debug": true }
  }
}

Agent Meta

The agentMeta object holds per-agent JSON metadata that Braide attaches as _meta on the newSession request for that agent — once per session at creation. Keys are agent IDs; values are arbitrary JSON objects specific to what that agent understands.

The meta is edited from the cog icon on each agent card in Settings > Agents. Changes are not auto-applied: an Apply button on the agent card restarts the agent with the new meta when you're ready. See Managing Agents > Additional Settings and ACP Protocol > Extensibility via _meta for details.

An absent or empty object for a given agent ID is treated the same as having no meta at all — no _meta field is sent on requests to that agent.

Directory Structure

All project and session data is organized under ~/.braide/:

~/.braide/
├── settings.json                          # Global app settings (see above)
├── logs/
│   └── acp.log                            # Global log file (rotated at 5 MB)
└── projects/
    └── <project-id>/
        ├── project.json                   # Project metadata (name, root path)
        └── sessions/
            └── <session-id>/
                ├── session.json           # Session metadata (agent, label, worktree path)
                ├── logs/
                │   └── session.log        # Per-session log file (append-only)
                └── worktree/              # Isolated git worktree for this session

• projects/<project-id>/project.json — Stores the project name and the path to the source directory on disk.
• sessions/<session-id>/session.json — Stores the session's assigned agent, display label, and the path to its worktree.
• sessions/<session-id>/worktree/ — A git worktree checked out on the session's branch. See Worktrees for details.

Environment Variables

Variable	Required	Description
BRAIDE_HOME	No	Override the default home directory (~/.braide)
GITHUB_TOKEN	No	GitHub personal access token for issue and pull request browsing
GH_TOKEN	No	Alternative to GITHUB_TOKEN
ACP_LOG_LEVEL	No	Minimum console log level (trace, debug, info, warning, error, fatal). Default: info
ACP_LOG_FILE_LEVEL	No	Minimum file log level. Default: debug. See Logging
ACP_LOG_AREAS	No	Comma-separated area filter. Default: * (all). See Logging

BRAIDE_HOME

By default, Braide stores all data — settings, projects, sessions, and downloaded agents — under ~/.braide/. Set the BRAIDE_HOME environment variable to use a different directory:

export BRAIDE_HOME=/path/to/custom/directory
bun run braide:dev

Or inline for a single invocation:

BRAIDE_HOME=/tmp/braide-demo bun run braide:dev

The directory will be created automatically on first use. This is useful for:

• Testing — Run against an isolated data directory without affecting your real projects
• Demos — Set up a self-contained environment with pre-configured projects
• Multiple instances — Run separate Braide instances with independent data

When BRAIDE_HOME is not set, or set to an empty string, the default ~/.braide/ is used.

Electron app override

When running Braide as a packaged Electron desktop app, the BRAIDE_HOME override is persisted in an electron-config.json file located in Electron's user data directory:

Platform	Path
macOS	~/Library/Application Support/Braide/electron-config.json
Windows	%APPDATA%\Braide\electron-config.json
Linux	~/.config/Braide/electron-config.json

The file stores the override as a braideHome field:

{
  "braideHome": "/path/to/custom/directory"
}

This value can be set from within the app's settings UI. When braideHome is absent or empty, the default ~/.braide/ is used. The Electron app passes this value as the BRAIDE_HOME environment variable to the embedded Next.js server on startup.

The settings UI expands ~ (and ~/, ~\) to your home directory at save time, so ~/.braide is stored as the absolute path. The BRAIDE_HOME environment variable itself is consumed verbatim — pass an absolute path there. See Supported Platforms for the full list of platform-specific behaviours.

GITHUB_TOKEN / GH_TOKEN

A GitHub personal access token enables GitHub integration features such as browsing repository issues and pull requests and attaching them to sessions. Set either variable — GITHUB_TOKEN takes precedence if both are set:

export GITHUB_TOKEN=ghp_your_token_here

The token needs read access to issues and labels for any repositories you want to work with. See GitHub Integration for full details.

Ports

Service	Default Port
Braide	3000
Terminal WebSocket	Dynamic (fetched via /api/terminal-port)