Settings
The Settings dialog holds your preferences. Open it with ⌘, (Ctrl+, on Linux), from Settings… in the command palette, or by right-clicking the sidebar background.
The dialog lists its sections on the left. Type in Search settings to filter every section at once by label and description. Esc clears the search.
A change shows at once and saves in the background. If it cannot be saved, for example while the app is offline, a notice says why and the setting goes back to its stored value. Two changes made quickly both save.
What syncs and what does not
Section titled “What syncs and what does not”When sync between devices is on, these settings sync between your devices: Theme, Pane order, Terminal theme, Font size, Option as Meta, Open links from sessions, Show the browser an agent drives, Ask before an agent drives the browser, Browser devices, Agent for new sessions, Ask before an agent messages another session, Open in, Open changes as, Context lines, Worktree location, Settle sessions when their pull request merges and Notification sound. A change on one device shows on the others when their sync service delivers it. If two devices change one setting, the newer change wins.
Each of these rows has a chip beside its label:
- Synced: the setting syncs with your other devices.
- This device: this device keeps its own value. It does not send its changes, and it does not take the values of your other devices.
Click the chip to change it, or run Sync a setting or keep it on this device… from the command palette and pick the setting. Each device has its own list of kept settings, and this list does not sync. When a kept setting syncs again, it takes the newest value from your other devices. If no other device has set it, this device sends its own value.
The other rows describe this machine or its install: Renderer, Sync between devices, Show in menu bar, Update channel and Send crash reports. They show a plain This device label and never sync.
When a device turns on sync for the first time, it takes the settings that your other devices already set. Only the settings that no other device has set keep this device’s value.
Most settings are stored in settings.json in the mocante config directory, ~/.config/mocante by default. The desktop app keeps three rows in its own files instead, in the app’s data directory:
| Setting | File | macOS | Linux |
|---|---|---|---|
| Update channel | updates.json |
~/Library/Application Support/mocante |
~/.config/mocante |
| Send crash reports | crash-reports.json |
~/Library/Application Support/mocante |
~/.config/mocante |
| Show in menu bar | menu-bar.json |
~/Library/Application Support/mocante |
none |
Change these three in the dialog. Editing or deleting settings.json does not change them.
Appearance
Section titled “Appearance”| Setting | What it does | Default |
|---|---|---|
| Theme | Dark, Light or System. System follows the operating system and switches when it does. | Dark |
| Pane order | Drag the rows to set the left to right order of the panes: Terminal, Code, Browser, Dev servers and Shared. Every window lays out its open panes in this order. See panes. | Terminal, Code, Browser, Dev servers, Shared |
| Show in menu bar | macOS desktop app only. Shows the mocante item in the menu bar, with the number of waiting agents and a list to go to each one. The item’s own menu can also hide it. The dock menu keeps the list when the item is hidden. See menu bar and dock menu. | On |
The theme is also in the command palette as Theme: Dark, Theme: Light and Theme: System. The menu bar item is in the command palette as Hide from menu bar or Show in menu bar.
Terminal
Section titled “Terminal”| Setting | What it does | Default |
|---|---|---|
| Renderer | The terminal emulator that draws sessions. xterm.js draws in the page. Ghostty runs its parser on WebAssembly and draws to a canvas. Open sessions reload when you change it, and their scrollback starts over. See terminals. | xterm.js |
| Terminal theme | The colours of session terminals. Follow the app uses light colours when the app is light and dark colours when it is dark. Dark and Light keep one set of colours. A program that is running keeps the colours it chose when it started. See terminals. | Follow the app |
| Font size | The size of terminal text, from 10 to 20 px. Open sessions change size at once and keep their scrollback. | 12 px |
| Option as Meta | macOS only. On: ⌥ plus a key sends Esc and the key, so the Alt shortcuts of terminal programs work. Off: ⌥ types the characters your keyboard layout puts on it, such as @ or { on some layouts. |
Off |
| Open links from sessions | A program in a session that opens a link, with xdg-open or $BROWSER, opens it in this device’s browser, also on a remote host. The window title carries the session’s project, workspace, host and tags, for a browser router such as Finicky. Off leaves the link to the host. See links. |
On |
Editor
Section titled “Editor”| Setting | What it does | Default |
|---|---|---|
| Open in | The desktop editor that the code view’s Open in button and command open a file in: VS Code, VS Code Insiders, Cursor, Windsurf or VSCodium. A file on another host opens over the editor’s own ssh remote, at the line the code view showed. See code view. | VS Code |
| Open changes as | The layout a new code tab shows a changed file in: Unified diff, Side by side or File. File shows the file itself, with the changed lines marked in the gutter. The toolbar changes the layout of one tab. See code view. | Unified diff |
| Context lines | How many unchanged lines a diff shows above and below each change while it folds the others. Open diffs pick it up straight away. See code view. | 3 lines |
| Setting | What it does | Default |
|---|---|---|
| Worktree location | Where a session on a branch gets its worktree. Container folder keeps worktrees in a <repo>-worktrees directory next to the repository, where build tools that scan the repository do not see them. Beside the repo makes a <repo>--<branch> directory next to the repository for each one. |
Container folder |
| Settle sessions when their pull request merges | A session in its own worktree moves to Settled when its pull request merges, if nothing runs in it, it has no star, and it holds no work after the merge. Its agent keeps running. Off leaves every session on the list until you settle it. See settle and snooze. | On |
Under Worktree location there is a path field. Leave it empty to keep worktrees next to each repository. Set a directory to collect every worktree in one place instead, as <directory>/<repo>/<branch>. mocante reads the path on the host that owns the workspace, so the path must be valid on that host. A repository that sets worktree.baseDir in its git config overrides both. See git workflow.
Browser
Section titled “Browser”| Setting | What it does | Default |
|---|---|---|
| Browser devices | The devices that the browser’s Device size menu offers, and that an agent can pick by name. Each has a name, a width and a height in CSS pixels in portrait, a scale, and Mobile for touch input and a mobile user agent. Reset to defaults goes back to the five built-in devices. A project can have its own list. See browser. | Small phone, Phone, Large phone, Tablet and Large tablet |
Agents
Section titled “Agents”| Setting | What it does | Default |
|---|---|---|
| Agent for new sessions | The agent that New session picks for you: Claude Code, Codex, opencode, pi or Plain shell. You can change it in the dialog for one session. See first session. | Claude Code |
| Show the browser an agent drives | The browser pane of a session opens when its agent uses the browser tools. The keyboard stays in the pane you are in. A page captures only while its pane is on screen. Off leaves the pane closed and shows a notice. See browser. | On |
| Ask before an agent drives the browser | An agent’s browser calls wait until you approve them in mocante, once or for the session. Running JavaScript in a page always asks. See agent tools. | Off |
| Ask before an agent messages another session | An agent’s message to, or stop of, an agent in another session on the same host waits until you approve it in mocante, except between a session and one it started. One to another host always asks. See agent tools. | Off |
| Touch ID for risky approvals | In the desktop app on a Mac, allowing a 1Password read or an agent’s call that acts on another host also asks for your fingerprint. A failed or cancelled prompt denies the request, and so does a sensor that locked after failed tries. On a Mac with no sensor to use, the switch is off and cannot be turned on. Turning this on takes back those approvals already given for a session. See 1Password and agent tools. | Off |
Notifications
Section titled “Notifications”| Setting | What it does | Default |
|---|---|---|
| Notification sound | Plays a short tone with each notification, in addition to the desktop notification. See fleet. | Off |
| Notify when an agent finishes | Shows a notification when an agent finishes its turn or stops on an error, unless you are looking at its tab. See fleet. | Off |
| Summarize with the on-device model | On a Mac with macOS 27, a needs-input notification says what the agent wants in one short line from the fm command, and a finish notification what it did or what went wrong. The terminal text stays on this Mac. See fleet. |
Off |
| Setting | What it does | Default |
|---|---|---|
| Sync between devices | Off keeps this device’s configuration to itself. Synced folder replicates projects, hosts, workspaces and the settings marked Synced through a folder that is already synced between your devices. | Off |
| This device | The id that names this machine in synced records and in its file in the sync folder. The copy button puts it on the clipboard. | — |
When you pick Synced folder, a path field opens. Use the same folder on every device. Any folder that is replicated between your devices works: iCloud Drive, Dropbox, Syncthing or a NAS mount. Sync stays off until you set a folder. On macOS, Use iCloud Drive fills in a mocante folder in iCloud Drive. In the desktop app, the folder button beside the field opens the folder in Finder or your file browser. mocante checks that it can write to the folder and shows an error if it cannot. See multi-device.
| Setting | What it does | Default |
|---|---|---|
| Hub mode | Lets paired phones reach this device through a relay. Needs a relay address that starts with wss://; plain ws:// works only for a relay on this computer. Paired phones remember the relay address, so after you change it each phone must pair again. The status line under the address shows the relay connection, or why hub mode could not start. |
Off |
| On-device lines in phone notifications | In the desktop app on a Mac with macOS 27, a paired phone’s needs-input notification says what the agent wants in one short line from the fm command, written on this Mac. The notification then waits up to four seconds for the line. See phone. |
Off |
| Pair a device | Shows a QR code and a link that a phone opens to pair. The code works once, for two minutes. When a phone presents it, this row asks you to Allow or Refuse the phone by its name, and shows a six-digit code. Allow only if the phone shows the same code. | — |
| Paired devices | The phones paired with this device, with when each was last seen. Remove disconnects one at once, and it must pair again. | — |
See your phone.
Updates
Section titled “Updates”The desktop app shows these rows. The web UI has nothing to update, and says so.
| Setting | What it does | Default |
|---|---|---|
| Update channel | Stable gets tagged releases. Beta gets the release candidates before them. A branch build also offers This branch, which follows its branch until the branch is merged and its builds are gone, then returns to stable. | The channel of the build you installed |
| Version | The version you run and the channel it was built for. | — |
| Status | The result of the last check. The button beside it reads Check now, Download v… when an update is available, or Restart to update when it has downloaded. What’s new opens the release notes of an update. | — |
| Send crash reports | Sends errors and crashes, with a sample of performance traces, to the mocante team through Sentry. The change takes effect at the next start. See crash reports. | On |
The app also checks for updates by itself every few hours. The channel is saved for the installed build, so installing a different build starts on that build’s own channel. See updates.
Preferences outside this dialog
Section titled “Preferences outside this dialog”Some choices are saved with the settings above but are set where you use them:
- Sidebar: inbox and Sidebar: project tree in the command palette, or the button at the top of the sidebar, choose how the sidebar lists sessions.
- Group fleet by status and Group fleet by project in the command palette choose how the fleet view groups sessions.
- Show file tree and Hide file tree in the code view show or hide its file tree.
Environment variables
Section titled “Environment variables”Set these in the environment of the process you start. Most matter only when you run mocante from a source checkout with pnpm dev, which is the way to use the web UI from a browser.
| Variable | What it does | Default |
|---|---|---|
MOCANTE_HOST |
Set to 1 to make the web UI dev server listen on the network, not only on localhost. The backend stays on localhost and the web UI reaches it through the dev server. |
Localhost only |
MOCANTE_ALLOWED_HOSTS |
A comma-separated list of hostnames the web UI answers for, such as a VM name or a tailnet name. A leading dot allows a domain and its subdomains, for example .example.ts.net. Setting it implies MOCANTE_HOST. A browser page from a host named here is also trusted like a local page. |
Empty |
MOCANTE_ALLOWED_ORIGINS |
A comma-separated list of exact origins, such as https://box.tailnet.ts.net, that a browser page may come from and still be trusted like a local page. Use it with a reverse proxy when only some schemes or ports must count. |
Empty |
MOCANTE_BIND |
The address the backend listens on. 0.0.0.0 exposes it to the network, where every client must present the machine token. A browser does not need it: the web UI reaches the backend on localhost. |
127.0.0.1 |
MOCANTE_PORT |
The backend port. The desktop app picks a free port at each start and ignores it. | 4124 |
MOCANTE_WEB_PORT |
The web UI dev server port. | 4123 |
MOCANTE_TOKEN |
The machine token that clients from off this machine must present. It overrides the auth-token file. |
Desktop app: a new random token at each start. Source checkout: a random token saved in auth-token |
XDG_CONFIG_HOME |
Moves the config directory to $XDG_CONFIG_HOME/mocante. |
~/.config |
XDG_CACHE_HOME |
Moves the cache directory, which holds dropped and shared files, to $XDG_CACHE_HOME/mocante. |
~/.cache |