Settings

Open Settings with Ctrl+, on Windows and Linux, or Cmd+, on macOS. You can also open it from the command palette with Mod+P.

Zync saves normal settings through its managed settings service. Changes are applied optimistically and written atomically, so a failed save can be rolled back without leaving a partial JSON file.

Settings sections

Section	Use it for
General	Privacy display choices, data and log locations, update checks, and the default editor provider
Terminal	Local shell selection, GPU rendering, idle host PTY suspension, and ghost suggestions
Appearance	App and terminal typography, color theme, accent, opacity, vibrancy, and compact mode
Status Bar	Connection latency display
File Manager	Hidden files, delete confirmation, default download folder, view, click behavior, zoom, sorting, and date format
Shortcuts	Application, terminal, tab, view, and File Manager bindings
Plugins	Installed extensions, marketplace, developer installs, and restart actions
AI	Provider, model, Ollama URL, feature toggle, and cloud API keys
Feedback	Optional product feedback
About	Version, updates, and app information

Vault management is available from the Local Vault surface in the app. AI key storage and sync boundaries are described in AI command bar.

Notification position, Do Not Disturb, and sound are configured from the gear control inside the notification center rather than from a full Settings section. See Notifications.

Global settings and file locations

The active settings file is the global user settings file:

Platform	Path
Windows	%APPDATA%/Zync/User/settings.json
Linux	~/.config/Zync/User/settings.json
macOS	~/Library/Application Support/Zync/User/settings.json

The exact location can be affected by the app’s configured data path. Use the path shown in Settings > General when troubleshooting or making a backup.

Zync currently has one global settings scope. A workspace-level settings.json overlay is planned but is not active, so do not expect local settings files to override the global file.

Caution

Editing settings by hand can make the app configuration invalid. Prefer the Settings UI. If you use the built-in JSON editor, keep a valid JSON copy and use its Save, Reload, and Restore actions.

Built-in JSON editor

The Settings sidebar includes a settings.json editor for advanced changes:

1. Open Settings and select settings.json near the bottom of the section list.
2. Edit the full JSON document in the in-app editor.
3. Press Ctrl+S or Cmd+S to save.
4. Use Reload to discard the editor buffer and read the file again.
5. Use Restore to recover from settings.last-known-good.json when a previous valid backup exists.

The backend validates raw writes, uses a temporary file followed by rename for atomicity, and detects conflicting external changes before saving. Invalid patch input is rejected before it reaches the backend. Validation logs contain metadata only, not the raw patch contents.

General

General settings cover the parts of Zync that apply across the workspace:

• Show host addresses in lists controls whether lists display user@host or safer display names and tags. Connection details still contain the endpoint.
• Default editor provider chooses the in-app editor used for local and remote files. CodeMirror is the default lightweight provider, with a built-in fallback and optional provider plugins.
• Data location changes where Zync stores its local workspace data.
• Log location changes where application logs are written.
• Automatic update checks controls whether Zync checks for a newer release.
• Clear all connections removes the local connection list. Treat this as a destructive action and confirm the dialog carefully.

Terminal and local shells

In Settings > Terminal, configure the local Windows shell when applicable: Default, PowerShell, Command Prompt, Git Bash, WSL, or a detected WSL distribution. New panes or tabs use the selection.

Terminal rendering options include GPU acceleration through WebGL, font and viewport controls under Appearance, and background-host PTY suspension. When suspension is enabled, quiet background host PTYs preserve scrollback and resume when you return. A host that is still producing output remains active.

Ghost suggestions can be enabled inline or in the terminal context menu. Their providers are independently configurable for command history and filesystem paths. Remote shell history import is off by default and, when enabled, reads the selected host’s shell history once on connect.

See Keyboard shortcuts for the terminal focus policy and keys that remain PTY input.

Appearance

Appearance has separate App and Terminal views. Configure:

• the color theme and its light or dark mode
• an optional accent color
• global font family and size
• terminal font family, size, weight, ligatures, cursor style, line height, and padding
• window opacity, vibrancy, and compact mode
• the active file icon theme

Selecting a theme resets the explicit accent to the theme’s default. You can then choose a custom accent. Color themes and file icon themes are separate systems. See Themes for the plugin contracts and current built-ins.

Local Vault

The Local Vault stores encrypted credentials on this device. Unlock it when a feature needs a protected secret, then lock it again when you are finished. Vault credentials use a separate encrypted store from normal settings. Optional sync and backup flows have their own scope rules, so review the restore preview before applying one.

AI provider API keys are vault records with a local-only policy. They are not included in credential sync or full Vault backup exports. See AI command bar and the security guide for details.

AI

The AI section enables or disables AI features and selects one of six providers: Ollama, Gemini, OpenAI, Claude, Groq, or Mistral. It also stores the Ollama URL and the selected model. Open the AI sidebar to change the active model from the provider’s available model list.

Ollama needs no key. Saving a cloud key requires the Local Vault to be unlocked. Keys are encrypted in the vault, excluded from sync and backup, and migrated from known legacy locations when possible. Read the AI guide before sending terminal or file context to a cloud provider.

Plugins

The Plugins section has Installed, Marketplace, and Developer views. Enable or disable installed extensions, install a marketplace package, or load a local development package. Some plugin changes display Restart Required because workers and editor providers are initialized during app startup.

Read Plugins and extensions for packaging, sandbox, manifest, and provider details.

Notifications

Notification preferences are available from the notification center’s gear control. They are persisted in the global settings object:

• notification position
• Do Not Disturb
• notification sound

The notification inbox itself is not in settings.json. It is a local browser storage history with bounded retention. See Notifications for expiry and action behavior.

Migration and recovery

If the canonical settings file is missing, Zync can migrate from legacy app-data or ~/.zync candidates. A bundle identity migration also copies data from legacy zync and com.zync.desktop directories when the new default directory is empty. A user-selected dataPath is respected and is not moved automatically.

If a managed update fails, the UI reports the error and restores the affected in-memory values. If a raw JSON edit is invalid, reload or restore the last-known-good file instead of deleting the settings directory.