Manage Desktop Settings

Use Settings to confirm the current account, change the appearance, view system AI entitlements, maintain built-in projects, and inspect Desktop version and update state. The account area at the bottom-left of Home also provides sign-in access.

Settings Navigation

Settings has five areas:

Area	Purpose
Profile	Edit account details, review local and cloud project totals, and sign out.
Appearance	Choose the theme and interface language.
Built-in projects	View, install, update, or remove independently released built-in workflows.
System AI configuration	View the current account's subscription plans, quota periods, enabled usage-based configuration, and balance.
System preferences	Manage launch-at-login and inspect Desktop version, automatic-update state, and runtime diagnostics.

The Settings sidebar width and collapsed state reuse Home's local layout preferences. They affect only this device's UI.

Profile

• When signed in, the top row shows the account summary, with the account ID rendered as muted small text beside the name. Select the row to open Edit profile.
• When signed out, it shows an empty state and Sign in.
• The edit dialog manages the avatar, display name, and email. Save becomes available only after valid content changes.
• Account ID uses readable monospaced text that can wrap in full and has no separate copy button.
• Project overview reports Home-visible local projects and cloud projects available to the current account, broken down by Workflow, Conversation, and Kanban.
• The page no longer exposes access-token, sign-in-state, or session-expiry details. Sign-out remains in a separate safety area.
• All five Settings areas use the same content width, so the main surface does not shift horizontally when switching areas.
• Credentials saved after sign-in are used for publishing, pulling, remote runs, Server-history reads, and a local workflow's account-specific server AI configuration.
• An account credential issued by the Desktop initially remains valid for 90 days. Each time the Desktop starts or continues to use it and successfully authenticates with Server, the expiry extends another 90 days from that time and saves the new expiry locally.

Automatic renewal applies only to credentials that have not expired or been revoked. It does not restore an expired, revoked, or disabled-account credential. In that case, Desktop asks you to sign in again rather than edit a token manually.

A Workflow Server administrator key represents server-management authority, not an individual user. It cannot replace Desktop account sign-in when reading a user's subscription or balance AI configuration. A valid saved user session is preferred for those account-level requests.

For local development, set only WORKFLOW_DESKTOP_DEFAULT_SERVER_URL in desktop/.env. At every Desktop launch, the server URL is resolved again: WORKFLOW_SERVER_URL takes precedence, followed by WORKFLOW_DESKTOP_DEFAULT_SERVER_URL. A saved user API key and profile remain, while the server URL follows configuration. Restart the Desktop after a port or domain changes. If the new server rejects the old API key, Desktop asks you to sign in again. Keep WORKFLOW_SERVER_ADMIN_KEY and administrator bootstrap credentials in Server configuration, never in the Desktop.

Built-in Projects

Built-in projects lists independently released workflows with the current compatible version, installed version, installation state, update state, and dependencies. During a download, each project shows a dedicated progress bar with the actual percentage, downloaded and total sizes, and live transfer speed. You can pause, resume, or cancel the transfer; cancelling removes the incomplete files. After the download completes, the UI switches to indeterminate progress and clearly identifies the archive verification and project registration stage.

A current compatible release must satisfy the index's minDesktopVersion plus its exact Core and CLI components. Desktop compares major.minor for each component and accepts every patch on a matching line. It refuses to install a release with missing components, a mismatched line, or package pins that differ from the index. Legacy indexes remain parseable, but new Desktop versions do not select releases without components.

Desktop applies no 60-second or other application-level total deadline to built-in resource downloads, so transfers can continue on slow networks. An install or update never replaces an existing usable version with incomplete content. A failure remains retryable with an inline error in the current interface language and never marks a partial version available. If an update index is temporarily unreachable, an existing installation is marked available offline and continues to run.

Project Assistant and Desktop Control are hidden built-in projects. You can maintain them here, but they do not appear in Home's project list, search, or count. Normally neither needs pre-installation. The first time you open Project Assistant from a normal local user project, Desktop installs or updates its declared OpenCode and Desktop Control dependencies, then registers the assistant. A dependency failure never replaces an existing usable version.

An installed Project Assistant depends on OpenCode and Desktop Control, so both dependencies' remove actions are disabled with an explanation. Remove Project Assistant first. Removing it does not remove either dependency automatically; projects and sessions using OpenCode directly are unaffected.

On Windows x64, OpenCode uses the native runtime packaged in the built-in project resource and does not depend on system Node or an install-time postinstall. If an older OpenCode built-in project fails with spawn UNKNOWN, it selected the resource's script stub instead. Check for updates here and install the latest OpenCode version; reinstalling the same older version does not change that launcher.

System AI Configuration

System AI configuration reads only the current signed-in account's AI entitlements from Workflow Server. Desktop does not synchronize or persist Sub2API subscriptions, usage, balance, or keys locally.

• A subscribed plan shows its name, platform, expiration, daily/weekly/monthly quotas, and usage progress. An unlimited quota is shown as Unlimited.
• Enabled usage-based configuration shows today's use, use over the last 30 days, and total use.
• The Sub2API account balance appears once at the top and is shared by all enabled usage-based configurations.

Usage preference lists every administrator-enabled AI configuration, including configurations that are currently unsubscribed, disabled, or temporarily unavailable. Move entries up or down to set the complete order, then save it. The preference is stored for the current Workflow Server account; Web at /settings/ai reads the same order. Runtime skips unavailable entries in sequence and returns to their original priority when they recover. When the other client is already open, refresh or reopen the page to retrieve the current order.

Desktop does not subscribe, renew, top up, enable, or disable anything. Manage on Web opens the current Workflow Server's /settings/ai page in a browser. Change entitlements there, then return to Desktop and select Refresh. Preference fallback affects only a new provider selection and never replays a model request already in progress.

Appearance

Desktop supports three themes:

• System follows system appearance automatically.
• Light uses a light-gray background, white surfaces, and dark text.
• Dark uses a black and neutral-gray foundation with readable state colors; success, waiting, and error keep independent semantics.

The theme preference is stored locally and applies consistently to the Desktop shell, dialogs, Run workspace, and editor.

Interface Language

Desktop supports System, Simplified Chinese, and English language preferences. The preference is stored only on the current device. Changes apply immediately to the Desktop interface, localized feedback in local runs, and Desktop release notes.

• System: The Desktop reads the operating system's preferred-language order and uses the first supported Chinese or English language. When there is no Electron host, Web falls back to the browser language.
• Simplified Chinese: Always use the Chinese interface.
• English: Always use the English interface.

After changing the desktop system language, restart Desktop so it can read the updated preferred-language list.

Background Scheduled Runs

Launch at login is off by default. When enabled, Desktop starts with the current system account in --background mode and does not automatically open a window. Electron Main continues to run local Workflow schedules without depending on a renderer window. Desktop uses a single-instance lock: starting it again restores the existing window instead of starting another scheduler. Restore the window from the system tray or explicitly quit Desktop.

Closing every window hides the UI and keeps Desktop in the tray; it is not the same as quitting. Explicit quit, shutdown, or device sleep stops scheduling. Missed fires do not replay after a later start or wake. While Settings saves this preference, the control shows loading and rejects duplicate actions. Failure preserves the original value and shows an error.

Version and Automatic Updates

System Preferences always shows Current version vX.Y.Z. When a new version is found, downloading, or ready to install, it also shows Pending version vX.Y.Z. Desktop, Core, CLI, Server, and Server Web maintain complete history on their own dedicated Docs release-log pages. The global status bar displays Desktop vX.Y.Z and Core vX.Y.Z together. Select the Desktop version to open the Desktop update section in System Preferences; select the Core version to open that Core dependency's release log in a browser. Packaged macOS and Windows x64 Desktop installations check the selected update channel automatically. Development mode and unsupported update platforms show an unavailable explanation.

Each Desktop installer pins exact Core and CLI versions. A project must also pin devDependencies.workflow-code exactly, but runtime compatibility compares only the Core major.minor line. A patch or dated Alpha on the same line runs directly; a major or minor change prompts for a Desktop upgrade before run, resume, scheduling, parameter resolution, or structure inspection. Do not replace the exact project pin with ^, 0.2.x, or another range.

Stable and Alpha channels

Desktop only needs to be installed once. The Update channel segmented control in System Preferences switches between Stable and Alpha without downloading a separate test installer:

Channel	Desktop update feed	Default Workflow Server	Purpose
Stable	https://wfupdates.yuhe.space/desktop/stable/	https://wfapi.yuhe.space	The default channel for formal releases.
Alpha	https://wfupdates.yuhe.space/desktop/alpha/	https://wfalpha.yuhe.space	Early validation between dev and the formal release.

The selection is stored on the current device. After a switch, Desktop immediately changes both the update feed and Server URL, revalidates the connection, and checks for updates while preserving the account API key. Alpha and stable Server share accounts, projects, and business data, so a second account is not required, but Alpha code can contain changes that have not reached stable. The channel cannot be changed while an update is being checked, downloaded, or waiting to install.

Alpha versions use X.Y.Z-YYYYMMDDNNN. The date uses the Shanghai time zone, and the final three digits are an independent daily sequence starting at 001. The feed retains only the newest three Alpha artifacts; an older Alpha installation can still update directly to the latest available version. When switching back to stable, Desktop follows the stable feed and may install its current version when needed.

Current and pending versions both provide View release notes. It opens a dialog in Desktop with the complete Markdown for that version and a Full release history action that opens the matching anchor in the Desktop release log in the current interface language. Installers include both Chinese CHANGELOG.md and English CHANGELOG.en.md, so current-version notes work offline in the selected language. Pending notes come from releaseNotes.localizations in the selected update feed. An older feed without localizations falls back to releaseNotes.body. If the feed has no notes at all, Desktop still shows the pending version and explicitly states that release notes are unavailable.

When a new version is found, the status bar presents the target version with a highlighted Quick update action. Selecting it starts download immediately; both the Settings action and status bar keep showing download activity and progress. Once download completes, the same action becomes installation; confirm that current work is saved before restarting to install.

The first launch after installation shows the full current-version notes once. Desktop records the viewed version on the current device, so closing the same version does not show it again. You can still open current-version notes manually from System Preferences. Post-install notes reuse the history bundled in Desktop rather than maintaining a second copy.

Update state is always explicit:

• Checking: the control shows loading and disables duplicate actions.
• Update available: shows the available version and lets you begin download.
• Downloading: shows a progress bar, percentage, and downloaded size.
• Ready to install: after download, choose Restart and install and confirm.
• Up to date: does not download or install a downgrade again.
• Check failed: shows a readable error.

macOS automatic updates require Workflow Code.app to be in a writable /Applications or ~/Applications. If it is still in Downloads, a browser-unpacked directory, a DMG, or another read-only mounted volume, download and install are disabled and Desktop tells you to move it first.

Windows x64 automatic update uses latest.yml and the NSIS installer. Update check, download, and restart-and-install share the same Settings area as macOS. If system policy or security software blocks installation, download the installer manually from Desktop Downloads and install it over the existing Desktop.

Diagnostics

Settings no longer offers an Open Diagram automatically after run switch. Workflow and Conversation runs remain in the main Run view. Open Trace or Logs manually from Output, a message action, or a diagnostic action.

Relationship to the Local Workspace

Electron Desktop strictly derives the locations a project can access from workflowCode.projectInfo.dataStorage.mode. local allows only local ordinary KV, PersistentValue, and Knowledge and can run offline without sign-in. server allows only server storage and requires sign-in plus a same-UUID cloud binding. both lets code and the interface select either location explicitly and requires sign-in only when server data is actually accessed. A forbidden access fails directly; it never falls back to, copies, merges, or deletes data at the other location.

The Knowledge Base and KV Data workspaces remember their selections independently. local shows only the teal Local entry with a hard-drive icon. server shows only the information-blue Server entry with a cloud icon. both shows both segmented entries. Switching changes only the data set being viewed or edited and never uploads, downloads, merges, or synchronizes data automatically.

The first Server selection from a local both or server project opens sign-in. After successful sign-in, Desktop creates or recovers the same-UUID cloud binding, synchronizes the complete project declaration, and continues the switch. A sign-in, binding, or synchronization failure keeps the original source and clears server cache. A legacy project with no dataStorage.mode can open only Information until the declaration is saved. Saving also updates exact Core and CLI dependencies to 0.2.0, but does not migrate existing data.