Settings

Most people configure OpenFolks from the app. The packaged desktop validates credentials before saving them and stores supported secrets in the operating system's secure storage.

Engine discovery

OpenFolks checks the inherited process path, common install locations, and the login shell. If an engine lives somewhere unusual, open Settings → Engines and point at the executable.

Explicit paths help when you:

• keep more than one CLI version;
• use a wrapper script;
• installed an engine where desktop apps cannot see it; or
• launch OpenFolks from a shortcut or app menu with a different environment than your terminal.

Optional credentials

Local chat through an installed CLI works without these.

Environment

Source and headless runs can set supported environment variables before starting the harness. Prefer in-app settings for a packaged install — they validate inputs and keep secret values out of the renderer.

• OPENFOLKS_DATA_DIR — data root (default ~/.openfolks)
• OPENFOLKS_PORT — harness port for source runs (default 8799)

Per-instance Claude tool scope

Source and headless installs can give Claude instances different built-in tool sets in ~/.openfolks/config.json:

{
  "instances": {
    "claude-browser": {
      "driver": "claudeAgent",
      "config": {
        "tools": ["Read", "WebFetch", "WebSearch"],
        "disallowedTools": ["Bash(git *)", "Edit", "Write"]
      }
    }
  }
}

tools selects Claude's available built-ins; an empty array disables every built-in; omitting it keeps Claude's default set. disallowedTools is an extra deny list of Claude tool-name patterns. These settings do not grant MCP integrations. Those stay on the instance's mounted integrations and the OpenFolks permission flow.