Settings and configuration

Open Settings from the gear beside a workspace or project in the desktop sidebar. Start with the scope selector at the top of the Settings sidebar. It determines where your next edit is saved.

Change where a setting applies

  1. Open the scope selector.
  2. Choose Workspace for your personal configuration on this computer.
  3. Choose an entry labeled Team workspace for configuration shared through that team.
  4. Choose a project by name for configuration that belongs to its repository.
  5. Confirm the scope name at the top of the sidebar before editing.

Changing the selector changes the settings context; it does not copy the item you were viewing.

Use this quick reference when a destination is missing from the Settings sidebar. Logs opens a separate application view rather than a settings form.

ScopeAvailable from the Settings sidebar
Personal workspaceWorkspace, Fleet, Providers, Channels, GitHub, Teams, Keybinds, Analytics, Memories, MCP, Packs, Recipes, Agents, Skills, Actions, Routes, Responses, Workflows, Logs
Team workspaceRecipes, Agents, Skills, Actions, Routes, Responses
ProjectProject, Analytics, Memories, MCP, Recipes, Agents, Skills, Actions, Routes, Responses, Workflows

Connect a provider account

  1. Select Workspace.
  2. Open Providers.
  3. Choose Anthropic, OpenAI, OpenRouter, or Ollama.
  4. Use the connection control shown for that provider. Anthropic and OpenAI may offer subscription sign-in or installed command-line authentication. Hosted API providers accept API keys. Ollama accepts host addresses.
  5. Refresh the provider's model catalog and confirm that the account or host is available.

Connection methods and model catalogs change. The provider tab is the current source for the options available on your installation.

Choose the default provider and tier mappings

  1. In Workspace > Providers, open Overview.
  2. Set Default Provider. Agents set to Any backend use this provider.
  3. Review the Tier matrix. Each row maps a capability tier to the model and options used by each provider.
  4. Open a provider tab when you need to change one of its mappings. Choose from its discovered catalog.
  5. Return to Overview and confirm the resulting matrix.

Agents request tiers instead of fixed model names. Do not use model identifiers from old documentation as defaults; read the live catalog and matrix. See Providers and backends for runtime and data-flow details.

Create an agent or skill at the right scope

  1. Select the workspace, team workspace, or project that should own the item.
  2. Open Agents or Skills.
  3. Choose New Agent or New Skill.
  4. Choose Start blank, or copy an existing item into the selected scope.
  5. Complete the editor and save.

In a project, the creation dialog identifies when a copy with the same name will shadow an inherited workspace item. This named project override is the precedence behavior the current UI exposes. Do not assume that every Settings section follows the same precedence rule.

The Agent editor sets the prompt, tier, optional provider preference, fence, icon, description, and scope. The Skill editor sets the description, instructions, and optional tool restriction. The current Agent editor does not have a per-agent skill-assignment control. Follow Agents and skills for the complete workflow.

Create automation for a scope

Select the scope first, then choose the section for the job:

  • Open Recipes to compose agents and control-flow nodes into a reusable graph. See Recipes.
  • Open Actions to define commands used by recipes and automation.
  • Open Routes to decide what handles an incoming event.
  • Open Responses to define reusable response behavior.
  • Open Workflows to manage executable workflow packages for the personal workspace or a project.
  • Open MCP to connect an external Model Context Protocol server for the personal workspace or a project.
  • Open Packs in the personal workspace to install packaged configuration.

For package files, skill scripts, external servers, and workflow code, continue to Scripting and workflows.

Configure project checks

Project checks belong to a repository's configuration.

  1. Select the project.
  2. Open Project for repository-specific settings.
  3. Define the project's check commands in its Cairn project configuration.
  4. Run work normally; Cairn reports configured checks after commits and at turn end.

See Checks for the supported cadence and how results return to an agent.

Connect GitHub or a team

For GitHub:

  1. Select Workspace.
  2. Open GitHub.
  3. Follow the GitHub App connection flow.
  4. Review GitHub before enabling repository events; it explains the relay boundary and what data crosses it.

For team configuration, open Teams in the personal workspace to connect the desktop and inspect team state. Team creation, invitations, membership, billing, and sync enablement are web workflows. After a team workspace appears in the scope selector, select it before creating shared recipes, agents, skills, actions, routes, or responses. Follow Teams and remote work for the complete connection and recovery path. Use Channels for personal-workspace communication channels.

Find operational settings

Use the personal workspace for machine and application controls:

  • Workspace changes general application, repository-cache, label, and web-service settings.
  • Fleet manages enrolled execution machines.
  • Keybinds changes desktop shortcuts.
  • Logs opens the machine's application log stream.
  • Analytics changes analytics settings.
  • Memories opens captured lessons awaiting review. See Memories.

A project also has Analytics and Memories sections for that project. If a section is absent, change the scope instead of editing a different scope as a substitute.