wikis / Orca / wiki / entities / settings-reference.md view as markdown report a mistake

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.)

• 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.
• 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.

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.

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.

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.

Shortcuts

Full keymap — every binding remappable.

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.

Related entities

• Orca CLI reference
• Supported agents

Related concepts: SSH worktrees, Remote Orca Servers, Skills and MCP, Notifications and inbox, Usage and rate limits.

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.