---
title: "Settings Reference"
type: entity
tags: [settings, configuration, reference, panes, shortcuts]
created: 2026-09-09
updated: 2026-09-09
sources: ["raw/web_community-settings-reference-orca-docs.md", "raw/web_community-install-orca-docs.md", "raw/web_community-ssh-worktrees-orca-docs.md", "raw/web_community-agent-hibernation-orca-docs.md", "raw/web_community-agents-sessions-orca-docs.md"]
confidence: medium
---

# Settings Reference

## Overview

Orca's settings are grouped into panes, all searchable with `Cmd-,` then typing a keyword. This page transcribes the settings-reference page as of the docs snapshot fetched **2026-09-09**, pane by pane, with key names exactly as the docs write them. Where another docs page adds a value the settings page omits (a default, a range), that is noted inline.

## General

- **Orca CLI** — register the bundled command-line tool for shells and agents. (Note: the CLI reference page instead says to register the CLI under `Settings -> Experimental -> CLI`. See [Orca CLI](../concepts/orca-cli.md).)
- **Updates** — check for and install updates. Modifier clicks on `Check for Updates`:

  | Modifier | Effect |
  |---|---|
  | `Shift+click` | Include the latest `RC` prerelease |
  | `Cmd+click` (macOS) / `Ctrl+click` (Windows/Linux) | Latest `perf`-tagged prerelease |
  | `Option+click` (macOS only) | Pick a `validated local macOS build` (compatibility-checked). Failures surface as "Could Not Use Local Build" with `Choose Another Build`. |

  The install page adds context: Orca auto-updates by default, tracking the `stable` channel, and there is **no permanent in-app opt-in for the RC channel** — the modifier clicks are the mechanism, and they also work from the app / Help menu.
- **Open in menu** — choose apps on the worktree `Open in` menu. VS Code / Insiders enable `Remote SSH` open for SSH worktrees; other editors remain local-path only.
- **UI zoom** — per-install UI scale.
- **Default new-worktree name** — custom prefix or marine creatures.
- **Editor Word Wrap** — default wrap for file editors (**on by default**). Toggle from a file tab's `⋯` menu or `Alt+Z`. Separate from `Diff Word Wrap`.

## Appearance

- Theme, accent color, density.
- Font family for UI; editor font is opt-in (empty = follow terminal font; set a value to override file editors and diffs only).
- Editor minimap toggle.
- Status bar toggles, including `Resource Manager` (CPU/memory/sessions, daemon controls, workspace disk scans).
- **Usage percentages** — show provider limits as `% used` or `% remaining` on the status-bar roster.
- **App Icon** — cycle between Classic, Watercolor, and Blue for the icon shown in the Dock and window switcher.
- **Language** — primary Interface control. Switch between System (follows the OS), English, 中文（简体）, 한국어, 日本語, or Español. Settings search also matches native words for "language" (语言 / 語言 / 언어 / 言語 / Idioma) so you can find Language while the UI is still in English.

## Git

- Default base ref resolver.
- Commit signing options.
- Editor for external git tools.
- **Auto-Rename Branch From Work** — rename Orca-generated creature branches after an agent starts work.
- **GitHub API Budget** — remaining REST (core), Search, and GraphQL quota from the local `gh` CLI. Useful when PR checks or Tasks stop refreshing.

## Terminal

- Font, theme, cursor style, padding.
- Ghostty import.
- **Warp theme import** — bring in Warp YAML themes with `Import themes from Warp` (auto-discovers Warp's themes folder per OS) or `Import from YAML` for any folder of Warp-format theme files.
- **JIS Yen (¥) to Backslash (\\)** for macOS Japanese keyboards.
- **Windows default shell** (PowerShell or CMD). The install page notes "Most users want PowerShell."
- **Allow TUI Clipboard Writes (OSC 52)** — **on by default**. Lets Zellij, tmux, Neovim, fzf, Grok (and similar) write the system clipboard over the PTY, including over SSH. Turn off if you prefer the older lockdown.

## Quick Commands

- Saved terminal commands and agent-prompt presets, scoped globally or to a project. Each row has a copy control for the command body.
- Scope filters for reviewing and editing the command list. The same list syncs to the mobile companion — see [Mobile companion](../concepts/mobile-companion.md).
- With remote or multi-host setups, commands are grouped by the Orca host that owns them (`Saved on`). Host ownership is separate from Global/Project scope **and** from where the command runs.

## Agents

- **Installed agents** — detected CLIs you can enable or disable, so launch menus only show the CLIs you want to use.
- **Agent Permissions** — choose `Yolo` for fewer CLI permission prompts, or `Manual` to keep each agent's own approval flow **for agents you haven't customized**.
- Claude and Codex account lists.
- Startup hooks per agent.
- **Agent status hooks** — show working / waiting / done states in Orca. The toggle takes effect **without restarting the app** (including the Windows WSL hook relay). CLI: `orca agent hooks on|off|status`.
- **Keep computer awake** — `On` (stay awake continuously), `Agent` (stay awake while an agent is working), or `Off`. The same control lives on the desktop status bar as `Caffeinate` (coffee icon). **Hidden on paired web clients.**
- **Skill freshness** — the Agents pane and skill cards still show full status. Sidebar navigation only badges skills that need action (`Update available`, `Needs attention` / review); healthy, loading, and optional not-installed rows stay quiet. `Update` in the dialog refreshes global skills in the background (no terminal); progress appears on the status bar, and closing the dialog does not cancel the run.

## Browser

- Profiles (see Browser-use profiles).
- **Default Zoom** — zoom level applied to newly opened browser tabs (per-tab adjustments via Cmd-wheel are remembered separately).
- Design Mode defaults.
- Devtools opt-in.
- **Remote server workspaces** — choose `This device` to render new paired-runtime browser pages on this desktop, or `Server (streamed)` to render them on the server. Traffic **always** goes through the remote server, and the choice applies to **new pages only**.
- **Browse through SSH workspace hosts** — send browser traffic and DNS through each workspace's SSH host. Turn it off to browse from this device instead.
- **Link Routing** — open http(s) links from the terminal, markdown, and editor in Orca's browser or the system browser. Nested `Hold Shift…` inverts that default for one click (`⇧⌘-click` / `Shift+Ctrl+click`).
- **Show terminal link actions** — **on by default**. A plain click on a terminal link opens a compact action popover. Turn off to require `⌘`-click / `Ctrl`-click.
- **Default Search Engine** — used when you type non-URL text in the browser address bar or the `new-tab omnibox`.

## Artifacts

- **Orca account** — sign in (same account family as Orca Relay) to publish and manage shared files.
- **Allow publishing public artifact links** — **off by default**. Device-wide gate: when on, you, agents, and the `orca` CLI on this machine can upload HTML/Markdown up to **10 MiB** and mint public view links. Turning it off does **not** delete existing links.
- **Show Artifacts** / sidebar shortcut — open the Artifacts list to search, preview, copy, or delete account-owned links.
- **Ask Before Deleting Artifacts** — optional confirmation before breaking a public link.
- Share from an open local HTML page or Markdown editor with `Share as artifact`, or via `orca artifacts …` — see [Orca CLI reference](orca-cli-reference.md).

## Integrations

- GitHub OAuth.
- Linear API token.
- **Jira** — Cloud (email + API token) or self-hosted Server/Data Center (PAT or username/password).
- **Bitbucket Cloud** — `Connect` with `Email & API token` (default) or an `Access token`. Orca verifies the credential before saving. `ORCA_BITBUCKET_*` environment variables **take precedence and hide Connect / Disconnect**. Saved credentials stay on this machine — on a Remote Orca Server, set the env vars on the server instead.
- **MiniMax** — paste a MiniMax session cookie (from `platform.minimax.io/console/usage`) to enable local usage and rate-limit tracking for the MiniMax CLI. Optional group ID and usage models fields override the defaults picked from the cookie.
- **MCP servers** — see [Skills and MCP](../concepts/skills-and-mcp.md).

## Notifications

- Agent-finished: system, sound, chip.
- Custom desktop notification sound per category.
- PR check failures.
- Update available.

## Voice

- **Enable Voice Dictation** — requires microphone permission (macOS may open Privacy & Security).
- **Microphone** — pick which input device dictation uses. Defaults to the system mic. If the chosen mic is unplugged or missing, Orca falls back to the system default and shows a non-blocking notice.
- **Dictation mode** — `Toggle` (press shortcut to start/stop) or `Hold` (hold shortcut to talk).
- **Speech Model** — download/select an on-device model, or use cloud OpenAI models after pasting an API key:
  - `Parakeet TDT v3` (recommended) — multilingual European languages, offline.
  - `Parakeet TDT v2` — English, faster.
  - `Zipformer` family — bilingual ZH+EN streaming; streaming EN/ZH; `Zipformer Streaming KO` (Korean).
  - `Paraformer Bilingual` — Chinese dialects + English.
  - `Parakeet TDT-CTC JA` — Japanese.
  - `SenseVoice` — ZH / EN / JA / KO / Cantonese with auto language detection.
  - `Whisper Tiny` — 90+ languages, lower accuracy.
  - `GPT-4o mini / GPT-4o Transcribe` — cloud; needs OpenAI key under the same pane.
- While listening, a `Listening…` pill shows a `Stop` control; in toggle mode the tooltip also shows the dictation shortcut.

## SSH

- SSH worktrees, targets, passphrases, default identity file.
- Advanced: proxy / jump host; **`Reuse SSH connection for faster setup`** (system OpenSSH multiplexing; **default on**).
- Kerberos hosts: `GSSAPIAuthentication` from OpenSSH config drives system OpenSSH auth.

The SSH page adds detail this pane omits: targets are added with `Add Target` in a modal, `Test` verifies connectivity before `Save`, passphrases are held in memory for the life of the Orca session with an opt-in longer TTL, and connection reuse should be turned off only for hosts whose SSH policy rejects multiplexed sessions. See [SSH worktrees](../concepts/ssh-worktrees.md).

## Remote Orca Servers

- Pair and connect to remote Orca runtimes.
- Advertise this desktop app as a server and create revocable access links.
- Advanced default runtime selection for server-routed projects, terminals, and provider checks.

The remote-servers page names the specific controls: `Advertise this app as a server` → `New Link` → `Connection address` → `Generate Access Link` → `Pair another Orca client`; `Add Server` on the client; `Shared Server Access` for revoking grants; and `Advanced → Active Server` for the default routing. See [Remote Orca Servers](../concepts/remote-servers.md).

## Shortcuts

Full keymap — every binding remappable.

| Action | Default |
|---|---|
| `Toggle Sleeping Workspaces` | **ships unbound** |
| `Toggle Workspace Board` | **ships unbound** (existing bindings for `workspace.openBoard` continue to work) |
| Close all editor tabs | `Cmd+Option+W` (macOS) / `Ctrl+Alt+W` (Windows / Linux) |
| Next/previous tab across all types (new installs) | `Cmd+Shift+]` / `Cmd+Shift+[` (Ctrl on Linux/Windows) |
| Same-type next/previous (new installs) | `Cmd+Option+]` / `Cmd+Option+[` |
| Previous recent tab (new installs) | `Ctrl+Tab` |
| `Add Review Note` | `Cmd+Shift+A` (macOS) / `Ctrl+Shift+A` (Windows / Linux) |
| `Send Review Notes to Agent` | **ships unbound** |
| `Delete workspace` | `Cmd+Shift+Backspace` (macOS) / `Ctrl+Shift+Backspace` (Windows / Linux) |

Existing installs keep customized tab-navigation overrides under `~/.orca/keybindings.json`. For `Delete workspace`, hover the sidebar workspace you mean to delete; Orca still asks for confirmation. The agents-and-sessions page adds one more unbound entry: `Toggle Agent Dashboard` has no default binding and works while a terminal, editor, or browser tab has focus.

## Repository

- Per-repo base ref and hooks.
- Auto-run commands on worktree create.
- Repo icons for the sidebar: choose an icon, full searchable emoji picker, uploaded image, website favicon, or GitHub avatar, then pick a preset or custom hex badge color.
- Source Control AI overrides for commit messages, pull request details, and branch names.
- **Worktree Shared Paths** — gitignored paths to materialize from the primary checkout into each new worktree (APFS clone-copy on macOS when possible, otherwise symlink). Complements repo-checked-in `worktree.sharedDirectories` in `orca.yaml` and `.worktreeinclude`.

## Floating Workspace

- **Enable Floating Workspace** — global surface for terminal, browser, and markdown tabs that are **not** tied to a repo worktree.
- **Terminal Directory** — start directory for new floating terminal tabs (`~` = home).
- **Toggle Button Location** — where the floating-workspace toggle appears; the keyboard shortcut works regardless of button placement.

## Plugins (Experimental)

- **Plugin system** — `Settings → Plugins`. Turn the system on, then review and enable each plugin individually. **Nothing runs until you consent.**
- **Marketplaces** — add a git marketplace source, browse plugins, preview capabilities (panels, commands, language packs, VM recipes), install, update, or roll back.
- Plugin workers **always run on this computer**; SSH workspace actions still route through Orca.
- Capability and API shapes may change; treat third-party plugins as untrusted software.

## Experimental

Features not yet stable — behavior may change.

- **Activity Page** — Slack-style worktree feed for agent events.
- **Compact worktree cards** — hide redundant second lines in the sidebar while the layout is still experimental.
- **Agent hibernation** — pause idle background agents and auto-resume them on reopen. The hibernation page adds the tuning control `Hibernate after`, with a **default of 30 minutes** and a range of **1 minute to 24 hours**, whose clock starts from the agent's last `done` update and resets on any keystroke, new output, or return to the terminal tab.
- **Agent Dashboard** — kanban of Needs You / Working / Done agents (optional Idle), with search and project/workspace/PR filters; open in-window or as a pop-out. `Show idle agents` lives on the dashboard board settings control, **not here**.
- **Chat UI** — optional chat surface on supported agent terminals.
- **Cloud VM** — show setup controls and workspace `Run on` targets for repo-owned, on-demand environments (cloud sandboxes, VMs, or local Docker). Setup guide and recipe install live under this experimental toggle. See [Ways to run Orca](../concepts/ways-to-run.md).

## Related entities

- [Orca CLI reference](orca-cli-reference.md)
- [Supported agents](supported-agents.md)

Related concepts: [SSH worktrees](../concepts/ssh-worktrees.md), [Remote Orca Servers](../concepts/remote-servers.md), [Skills and MCP](../concepts/skills-and-mcp.md), [Notifications and inbox](../concepts/notifications-and-inbox.md), [Usage and rate limits](../concepts/usage-and-rate-limits.md).

## Sources

`raw/web_community-settings-reference-orca-docs.md` (primary), with additions from `raw/web_community-install-orca-docs.md`, `raw/web_community-ssh-worktrees-orca-docs.md`, `raw/web_community-agent-hibernation-orca-docs.md`, and `raw/web_community-agents-sessions-orca-docs.md`.