Settings

The Settings dialog holds the preferences for this device. 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.

What syncs and what does not

Every setting in this dialog belongs to the device you set it on. Turning on sync between devices replicates your projects, hosts and workspaces, and the order of projects and sessions. It does not copy these settings, so set them on each device.

Most settings are stored in settings.json in the mocante config directory, ~/.config/mocante by default. The desktop app keeps two 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

Change these two in the dialog. Editing or deleting settings.json does not change them.

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

The theme is also in the command palette as Theme: Dark, Theme: Light and Theme: System. The theme is not saved between launches: the app starts in Dark each time.

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

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

Git

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

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.

Notifications

Setting	What it does	Default
Notification sound	Plays a short tone with each needs-input or bell notification, in addition to the desktop notification. See fleet.	Off

Sync

Setting	What it does	Default
Sync between devices	Off keeps this device’s configuration to itself. Synced folder replicates projects, hosts and workspaces 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.

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

Some choices are saved with the settings above but are set where you use them:

• 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

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

Caution

A browser from a hostname in MOCANTE_ALLOWED_HOSTS, or an origin in MOCANTE_ALLOWED_ORIGINS, gets full control of your sessions with no token. With only MOCANTE_HOST, a browser on another machine must present the token. Read security before you set them.