Skip to main content
Settings is where you tune Orkestral to fit you and your team. You manage your profile, pick which AI providers and models power your agents, control how much the team can do on its own, change the look of the app, and run data maintenance. Everything lives behind a single window with a sidebar of grouped sections. Open Settings from anywhere with Cmd , (or Ctrl , on Windows and Linux). Press it again to close, or hit Esc. The same shortcut works as a toggle.
Most changes save instantly. Toggles, selectors and color swatches apply the moment you click them. The General profile form is the exception: edit the fields, then press Save.

​
How Settings is organized

The sidebar groups sections by context so you find things fast. The version number sits at the bottom of the sidebar.

Account

General profile, Team (coming soon) and Subscription (coming soon).

Workspace

Workspace management and autonomy, plus Models (your AI providers).

App

System, Appearance, Audio, Shortcuts, Privacy (coming soon) and Data.

Help

Support links and, in local workspaces only, Advanced developer tools.
Sections tagged Soon persist your preferences but do not yet have a backend behind them. Advanced appears only when your active workspace runs in local mode.

​
General

This is your profile and the app’s about block.
1

Set your identity

Fill in Name and Email. The name is how agents address you in chat.
2

Add aliases

Use Aliases for other names people call you (comma separated). Agents recognize these when they read your repos and messages.
3

Save

Press Save. The button stays disabled until your profile finishes loading.
4

Pick a timezone behavior

Toggle Use device timezone on to follow your machine, or open Date and time settings to adjust the operating system clock.
5

Check for updates

The About block shows your version and checks GitHub Releases. If a newer version exists, you get a clickable link to it; otherwise it confirms you are up to date. Quit closes the app.

​
Workspace

The Workspace section manages the workspaces you have created and sets how autonomous the team is. A scope picker at the top lets you inspect or manage any non-archived workspace without switching the one you are actively working in.
The card shows the name, organization, mission, plan badge (Team or Local), creation date and a live count of agents, sources, issues and knowledge base pages. Below that you see each connected source (GitHub repo or local folder) with its role and primary flag.
The Autonomy slider is a workspace-wide setting that lives on the CEO orchestrator. It has three levels: Low, Medium and High. Higher autonomy lets the team take more steps before it pauses to ask you. It is set here, not per agent, because the orchestrator drives the whole team.
Archiving hides a workspace from the switcher but keeps all its data. Archived workspaces are listed below with a Restore action.
Deleting is permanent and asks for confirmation. If you delete the active workspace, Orkestral switches to another one or, if none remain, opens the onboarding wizard to create a new workspace.
Delete is irreversible. It removes the workspace and its data for good. Archive instead if you might want it back.

​
Models

This is your providers section. It lists the real AI adapters Orkestral discovered and, for each one, the models it actually exposes. Nothing here is hardcoded: the model chips come from each provider’s own discovery.
Each provider shows its name, description and a row of available models. Badges tell you what a provider is: Local, included for the bundled Forge, Recommended, Executor for execute-only models and Soon for providers that are not connected yet.
The bundled local model, the Forge (orkestral_local), is marked Local, included. It runs on your machine at no API cost and is the engine that applies code changes.

​
Smart routing

Below the providers you control how work splits between premium planning models and the local Forge.
  • Allow premium fallback lets routing fall back to a premium model when the local path cannot handle a task.
  • Enabled turns smart routing on or off.
  • Preserve CLI context keeps your terminal context when routing.
  • Require approval for local makes the team pause for your sign-off before running work locally.
Start with Local first and a Medium risk cap to keep cost near zero while the premium models stay reserved for planning. Read more in Hybrid model routing and The Forge.

​
System

System covers operating-system behavior and notifications, split into two groups.

General

Launch on startup opens Orkestral when you sign in. Time format switches between 12h and 24h. Show app in controls whether the app lives in the dock, the status bar, or both.

Notifications

Notifications turns desktop alerts on (the first time, it asks the OS for permission). Notification sound plays a sound with each alert. Inbox notifications controls alerts for inbox activity.

​
Appearance

Appearance has two tabs: the general look, and the code theme used for highlighting and diffs.
1

Pick a theme

Choose Dark, Light or System to follow your operating system.
2

Set the language

Choose Portuguese (Brazil), English or System to follow your OS language. The interface is bilingual.
3

Recolor a workspace

The accent color is per workspace. Use the scope picker to choose which workspace to recolor, then click a color swatch. Recoloring a workspace other than the active one does not change the current session’s color.
4

Tune density and font size

Set Density to Comfortable or Compact, and Font size to Small, Medium or Large.
5

Choose a code theme

Switch to the Theme tab and pick from the live preview cards. Each card shows real syntax highlighting plus a sample diff in that theme’s colors.
Theme, language, density and font size are global. Only the accent color follows the workspace scope picker.

​
Audio

Audio picks the microphone used for voice dictation and the output device. Device names only appear after you grant microphone permission, so the panel shows a permission prompt first. Click the button to request access, then choose your Input and Output devices. Each falls back to System default. If your platform does not support output selection, that control is hidden.

​
Shortcuts

Shortcuts is a read-only reference of every keyboard shortcut the app actually registers, grouped by Navigation, Chat and General. The list is generated from the live shortcut registry, so it always matches what works.

​
Privacy

Privacy is tagged Soon. The three preference toggles persist for real, but Orkestral does not yet collect telemetry or run a masking engine. Treat them as recorded preferences the future will honor. The data actions below are real and take effect immediately.
Local telemetry, Mask secrets and Block sensitive files are stored preferences. Nothing is sent anywhere today.
Clears the app’s browsing cache immediately.
Scoped to the workspace you pick. After you confirm, it deletes that workspace’s chat sessions and messages and reports how many were removed.

​
Data

Data is your maintenance and storage hub. A hero block shows total database size and the on-disk path. A scope picker filters the counts to one workspace.
Two tile grids show workspace counts (agents, sessions, messages, issues) and knowledge base counts (pages, chunks, embeddings, trace events).
When a knowledge base embedding job is queued or running, you see its status and progress, with a button to cancel it.
Orkestral previews safe-to-remove data for the selected workspace and estimates the space you would reclaim. Review the suggestions, then confirm to run the cleanup.
Export to JSON writes a full export and reports the path. Open folder reveals the data directory in your file manager. Clear cache wipes the app cache.

​
Support

Support gathers real links and actions only. It shows your version, then opens the GitHub repository, a new issue form, the release notes, the in-app Logs view, and the data folder.

​
Advanced

Advanced appears only in local workspaces and holds developer and destructive actions. Redo onboarding resets the onboarding state and asks for confirmation before running.

​
Team and Subscription

These two sections are honest placeholders for features that depend on Orkestral Cloud, which does not exist yet.
  • Team lists the only real human (you) as the owner. AI agents are managed in the Agents area, not here. Inviting human teammates is disabled until Cloud ships.
  • Subscription shows your real plan and presents Orkestral Cloud as a Soon tier. There are no prices to buy and no invoices.

​
What to do next

Connect a provider

Add API keys so premium models can plan for your team.

Tune routing

Balance premium planning against the free local Forge.

Set autonomy

Decide how far the team goes before it asks you.

Back up your data

Export to JSON and learn where your data lives on disk.