Files
orca/docs/site/content/docs/settings.mdx
T
Jinjing 5f3b2fa4bf feat(artifacts): allow artifact publishing by default for new profiles (#40948)
New profiles default artifactSharingEnabled to true. Existing users are
unchanged: stored settings win over defaults on load, and a stored profile
saved before the key existed loads as false instead of inheriting the new
default. The gate still requires an explicit true, sign-in is still
required, and web clients still mirror the host (their local fallback no
longer inherits the desktop default). showArtifactsButton is unchanged.
2026-11-10 17:28:29 -08:00

185 lines
17 KiB
Plaintext

---
title: Settings reference
---
Settings are grouped into panes. Everything here is searchable with `Cmd-,` then typing a keyword. Feature pages in these docs link directly to the relevant pane.
## General
- **Orca CLI** — register the bundled command-line tool for shells and agents.
- **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**. |
- **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**.
- **Insert Final Newline** — add a missing line break when saving a non-empty file from the code editor; off by default.
## 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, 中文(简体), 繁體中文(台灣), 한국어, 日本語, Español, Français, Português (Brasil), Русский, Türkçe, or Deutsch. Settings search also matches native words for “language” (语言 / 語言 / 언어 / 言語 / Idioma / Langue / Язык / Dil / Sprache) 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; see [Troubleshooting GitHub errors](/docs/github-errors) if the numbers look fine but GitHub still rate-limits live calls.
## Terminal
- Font, theme, cursor style, padding.
- Ghostty import.
- Warp theme import — bring in your 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.
- **Terminal shell** (local macOS / Linux) — system shell or a custom executable, with login startup by default. **Custom shell → Advanced → Custom args** requests replacement arguments for ordinary local panes. See [startup files and argument limits](/docs/terminal#macos-and-linux-shell).
- Windows default shell (PowerShell or CMD).
- **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](/docs/mobile).
- 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 — see [Terminal → Quick Commands](/docs/terminal#quick-commands).
## Agents
- Installed agents — detected CLIs you can enable or disable.
- Enable or disable detected agents 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.
- Startup hooks per agent.
- **Agent status hooks** — show working / waiting / done states in Orca. 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. Use **Update** in the dialog to refresh global skills in the background (no terminal). Progress appears on the status bar; closing the dialog does not cancel the run. See [Orca skills](/docs/cli/skills#keep-skills-up-to-date).
## AI Provider Accounts
- Optional saved accounts per provider. Without any, Orca uses your existing logins.
- **Claude** and **Codex** — **Add Account** signs in a separate, isolated account; switching applies to new sessions. See [Hot-swap Codex accounts](/docs/agents/codex-hot-swap).
- **Antigravity** — **Save current account** remembers the current `agy` login and **Select** switches the machine's shared `agy` login back to it. This is switching, not parallel accounts. Antigravity chats use their own sign-in. See [Antigravity accounts](/docs/agents/antigravity-accounts).
## Chat
- Choose whether agents open as chats in **Settings → Agents** for this computer (a [Remote Orca Server](/docs/remote-servers)'s settings page doesn't offer it). **Open agents as** sets the default to **Chat** or **Terminal**; fresh installs default to Terminal. Each supported agent's row in the **Installed** list has its own **Chat | CLI** choice. Agents without their own choice follow the default.
- Existing users keep their previous launch choices. Existing conversations keep their form. See [Chat UI](/docs/agents/native-chat) for continuing conversations in chat or the terminal.
## Browser
- Profiles (see [Browser-use profiles](/docs/browser/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. See [Per-worktree browser → Remote workspaces](/docs/browser/overview#remote-workspaces).
- **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`). See [Per-worktree browser](/docs/browser/overview#link-routing).
- **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. See [Terminal → Link actions](/docs/terminal#link-actions).
- **Default Search Engine** — used when you type non-URL text in the browser address bar or the [new-tab omnibox](/docs/model/quick-open#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** — **on by default for new profiles**; profiles created before this default keep their previous setting. Device-wide gate: when on, you, agents, and the `orca` CLI on this machine can upload HTML/Markdown 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 [CLI reference → Artifacts](/docs/cli/reference#artifacts).
## Integrations
- GitHub — uses the `gh` CLI login on the machine running Orca (on a [Remote Orca Server](/docs/remote-servers), run `gh auth login` on the server); there is no Orca OAuth app to approve or revoke. Expects the `repo`, `read:org`, and `project` scopes. See [Troubleshooting GitHub errors](/docs/github-errors).
- Linear API token.
- Jira — Cloud (email + API token) or self-hosted Server/Data Center (PAT or username/password). See [Jira items drawer](/docs/review/jira).
- 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](/docs/remote-servers), set the env vars on the server instead. See [Hosted reviews](/docs/review/github).
- 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.
## 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; choose a specific device (for example a headset) when you do not want the OS default. 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 Transcribe** — cloud; needs OpenAI key under the same pane. A saved GPT-4o mini or GPT-4o Transcribe choice moves to it, since OpenAI shuts those down on 2027-02-26.
- 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 (see [SSH worktrees](/docs/ssh)).
## 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.
## Shortcuts
- Full keymap — every binding remappable.
- Toggle Sleeping Workspaces ships unbound; assign it here if you want a direct shortcut for the sidebar sleeping-worktree filter.
- **Toggle Child Workspaces** ships unbound; assign it here to show or hide a parent worktree's nested children, the same as clicking its **N children** chip. It targets the hovered worktree, or the active one when nothing is hovered.
- **Toggle Workspace Board** ships unbound; assign it here to open or close the Workspace Board with one shortcut. Existing bindings for `workspace.openBoard` continue to work.
- Close all editor tabs defaults to `Cmd+Option+W` on macOS and `Ctrl+Alt+W` on Windows / Linux.
- **Tab navigation defaults (new installs):** next/previous tab **across all types** is `Cmd+Shift+]` / `Cmd+Shift+[` (Ctrl on Linux/Windows). Same-type next/previous is `Cmd+Option+]` / `Cmd+Option+[`. Previous recent tab is `Ctrl+Tab`. Existing installs keep customized overrides under `~/.orca/keybindings.json`.
- **Switch between Chat UI and terminal** defaults to `Cmd+Shift+J` on macOS and `Ctrl+Shift+F11` on Windows / Linux in a supported agent tab. Remap it or remove its binding here. Existing custom shortcuts keep their chords. On Windows / Linux, `Ctrl+Shift+J` also switches when **Switch worktree** doesn't use it, or from terminal input under the terminal-first policy.
- **Add Review Note** defaults to `Cmd+Shift+A` (macOS) / `Ctrl+Shift+A` (Windows / Linux); remappable.
- **Send Review Notes to Agent** ships unbound; assign it here to open the send-notes menu for the active worktree's diff notes without using the mouse.
- **Delete workspace** defaults to `Cmd+Shift+Backspace` on macOS and `Ctrl+Shift+Backspace` on Windows / Linux. Hover the sidebar workspace you mean to delete; Orca still asks for confirmation.
## 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` (see [Worktrees](/docs/model/worktrees)).
## 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 (Alpha)
- **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
- [Activity Page](/docs/activity) — 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](/docs/agents/hibernation) — pause idle background agents and auto-resume them on reopen.
- **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. See [Agents & sessions](/docs/model/agents-sessions#agent-dashboard).
- **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](/docs/ways-to-run#4-cloud-vms-per-workspace-environments).
- Features not yet stable — behavior may change.