> ## Documentation Index
> Fetch the complete documentation index at: https://docs.overcut.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspace Settings

> Configure workspace-level profile, defaults, and credentials shared across every project in the workspace.

Workspace-level configuration covers the things that apply to the entire workspace and every project inside it: the workspace profile, default LLM model, integrations, team membership, and platform-wide credentials. Project-specific configuration (workflows, agents, repositories, project vault, project permissions) lives inside each project under [Project Settings](/docs/concepts/multi-project-workspaces#project-settings).

This page covers the workspace **Settings** page. For review and audit workflows, see [Audit Trail](/docs/reference/audit-trail) to understand workspace activity, filtering, event details, and redaction behavior.

## Settings

The **Settings** page (`Account → Settings` in the sidebar) contains the workspace profile and the workspace-wide defaults that projects inherit. All fields are saved together when you click Save Changes.

<Steps>
  <Step title="Open the workspace" icon="layers">
    From the global workspace switcher, choose the workspace you want to configure.
  </Step>

  <Step title="Open Settings" icon="gear">
    Click <strong>Settings</strong> in the workspace sidebar. The current workspace settings are displayed.
  </Step>

  <Step title="Update settings" icon="edit">
    Update any of the fields. See the sections below for details on each field.
  </Step>

  <Step title="Save changes" icon="check-circle">
    Click <strong>Save Changes</strong>. A confirmation message appears when your changes are saved successfully.
  </Step>
</Steps>

### Workspace Name

The workspace name identifies your workspace throughout the application. It appears in workspace switchers, breadcrumbs, and other UI elements.

* **Required**: Yes

### Timezone

The timezone selector determines when scheduled workflows execute. The field displays a curated list of major world timezones, sorted by UTC offset and showing current offset information (e.g., "(UTC-8) America Los Angeles (PST)").

* **Default**: UTC
* **Description**: Timezone used for scheduled workflows. All workflows will run according to this timezone.

The timezone options automatically account for daylight saving time changes and are sorted from west to east by UTC offset.

### Default LLM Model

The Default LLM Model selector sets the workspace-wide default that workflows and agents inherit when they use the default model placeholder. This value is resolved at runtime through a cascading priority system.

* **Default**: Falls back to system default if not set
* **Description**: Default model used by agents in this workspace when no other model is specified

The selector displays all available models. When saved, any workflow or agent that uses the default model placeholder will automatically inherit the workspace selection.

<Info>
  Teams should leave workflow and agent model pickers at their default model placeholder unless they have a justified override. Once the workspace value is set, all placeholder usages resolve to the workspace default without per-workflow setup.
</Info>

#### How existing vs. new workflows behave

* **Existing workflows** keep running exactly as configured. Any step that already has a specific model selected continues to use it. Steps that use the default model placeholder immediately inherit the newly saved workspace value during the next execution.
* **New workflows** (and newly created agents) start with the default model placeholder. Until you set a workspace default, those executions fall back to the platform-wide system default. After you set it once, every new workflow automatically inherits it.
* **No retroactive edits** occur. This feature relies on runtime resolution, not bulk edits to workflow definitions. You can therefore experiment safely without rewriting historical definitions.

#### Model resolution order

When a workflow step runs, the system determines which model to use by checking the following sources in priority order:

| Priority | Source               | When it wins                                                                                                                                        |
| -------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1        | Coordinator override | A coordinator or runtime hook explicitly overrides (e.g., manual re-run forcing a model).                                                           |
| 2        | Agent/step config    | The agent definition itself has a specific model selected (Agent Builder, Agent Run/Session forms).                                                 |
| 3        | Workflow default     | The workflow metadata form has a default model set. See the [Workflow Metadata defaults guide](/docs/building-blocks) for workflow-level overrides. |
| 4        | Workspace default    | The value saved on the Settings page; applies whenever upstream layers use the default model placeholder.                                           |
| 5        | System default       | The platform-wide fallback when every other layer uses the default placeholder.                                                                     |

If a level uses the default model placeholder, it is skipped so the next layer can supply a specific model.

### Auto-Improve Workflows

The **Auto-Improve Workflows** toggle controls whether workflows in the workspace can use self-improvement features. Turn it on when you want workflow dashboards to expose the **Self-Improvement** panel and let each workflow run retrospective analysis.

* **Description**: Enables automatic retrospective analysis of workflow runs to generate improvement suggestions

This workspace setting is a prerequisite for workflow-level self-improvement. If the toggle is off, workflow dashboards show a prompt directing you to enable it here first. Once enabled, each workflow dashboard exposes a **Self-Improvement** panel where you configure retrospective cadence, sample size, and view retrospective activity.

<Info>
  See [Workflow Self-Improvement](/docs/how-to/workflows/workflow-self-improvement) for the full walkthrough on configuring cadence, sample size, validation limits, and viewing retrospective results.
</Info>

## Workspace Secrets

Platform-wide credentials, most importantly the **Claude API key** required to use the [Claude Agent SDK](/docs/integrations/claude-agent-sdk) as an execution engine, are stored in **Workspace Secrets**, under `Workspace → Security → Workspace Secrets`. They are available to every project in the workspace.

<Steps>
  <Step title="Open Security → Workspace Secrets" icon="key">
    From the workspace sidebar, click <strong>Security</strong>, then select the <strong>Workspace Secrets</strong> tab. The current Claude API key status is displayed.
  </Step>

  <Step title="Set or update the key" icon="shield-check">
    Enter a new Claude API key (the field is never pre-filled for security) and click <strong>Set Key</strong> or <strong>Update Key</strong>. The form clears once the key is saved successfully. If a key already exists, you'll see a confirmation message: "✓ API key is currently configured."
  </Step>

  <Step title="Clear when needed" icon="eraser">
    Use <strong>Clear Key</strong> to remove the stored secret. A confirmation dialog guards against accidental removal.
  </Step>
</Steps>

<Tip>
  Trying to use the Claude Agent SDK in a workflow step when no Claude API key is configured shows a warning directly in the Agent Run and Agent Session forms. This prevents misconfigured runs and guides you back to Workspace Secrets. See the [Claude Agent SDK integration guide](/docs/integrations/claude-agent-sdk) for more details.
</Tip>

<Info>
  Secrets are encrypted at rest and never exposed to the browser. The form field is always empty for security reasons, even when a key is already configured. A confirmation message indicates whether a key exists without revealing its value.
</Info>

For project-scoped secrets (credentials used by a single project's workflows, agents, and MCP servers), use the [Project Vault](/docs/reference/vault) instead.

## Custom Events

**Custom Events** is a workspace-level surface for defining your own event types that any third-party system can fire via a public webhook URL. Each event has a unique URL, an optional Bearer or custom-header secret, and an allowlist controlling which projects can react to it.

Open it from the workspace sidebar under **Custom Events**. The page lists every event defined in the workspace, with filters for category, scope, and search.

Four permissions, all workspace-scoped and granted to workspace admins by default:

| Permission           | Allows                                                                    |
| -------------------- | ------------------------------------------------------------------------- |
| `customEvent.view`   | List events, see webhook URLs                                             |
| `customEvent.create` | Create a new event                                                        |
| `customEvent.edit`   | Edit fields, change allowed projects, rotate the URL token or auth secret |
| `customEvent.delete` | Delete an event                                                           |

Holding `customEvent.edit` lets a user add any project in the workspace to an event's allowlist. Project admins cannot add their own project to an event's allowlist on their own.

For setup, auth modes, and recipes for common SDLC tools, see [Custom Events (Integrations)](/docs/integrations/custom-events). For the dispatcher contract, see the [Custom Events API reference](/docs/reference/custom-events-api).

## Related references

* [Multi-Project Workspaces](/docs/concepts/multi-project-workspaces): workspace-level vs project-level configuration boundary.
* [Vault](/docs/reference/vault): project-scoped secrets.
* [Claude Agent SDK Integration](/docs/integrations/claude-agent-sdk): learn how to use Claude as an execution engine in your workflows.
* [Workflow Metadata defaults](/docs/building-blocks): covers per-workflow model overrides.
* [Agent builder](/docs/workflows/agent-run): describes per-agent model choices and when to use the default model.
* [Custom Events](/docs/integrations/custom-events): workspace-defined webhook events that any third-party system can fire to trigger workflows.