Skip to main content

Managing Desktop Projects

The home page of the Desktop is used to manage local and cloud workflow projects and quickly return to the most recent running tasks. Select a project mode before you create, import, or install a project.

On first launch, if no project has been created, imported, or installed, Home is empty. Desktop does not automatically add the repository's workspace sample to the project list.

Understand the Home Page​

The home page is divided into the recent task area on the left and the project area on the right:

  • The left column shows the Workflow Code brand at the top, recent tasks for the selected Local or Cloud mode in the middle, and account and Settings controls at the bottom.
  • The project area has a Local or Cloud switch and the number of visible projects. Local mode provides New Project and Import Local. Desktop Cloud mode also provides Join Project and sign in.
  • The project toolbar places a List / Graph switch after search, followed by project-type filters and sorting. Type labels follow the interface language: English uses Workflow, Conversation, and Kanban, while Simplified Chinese uses 工作流, 对话, and 看板. Reset appears only after searching, filtering, or selecting a non-default sort; it changes only the project collection, not recent tasks.

"New Project" is the main operation of the page in local mode; "Import Local" is used to register an existing directory. The home page does not provide a button to manually refresh the project list. After the creation, import, or cloud status change is completed, the corresponding project collection will be updated. During the loading period, the related operations will display the progress and temporarily prohibit repeated triggering.

Local Mode vs. Cloud Mode​

Local mode displays only projects that have been created, imported, or installed on the current device. The cloud mode only displays the server projects that can be accessed by the current login account. Switching to the cloud mode does not download the project source code.

A local replica and a server project can exist for the same project UUID. The local mode uses the local project name, card information, and local actions, and displays the server association status; the cloud mode uses the project name and card information on the server. The Desktop cloud project menu only provides permission-controlled "download to local" and "copy to local project" and is not mixed into local edit, delete, or publish operations.

Desktop saves the last selected Home scope, List or Graph view, and the search, filter, sort, and scroll positions. These interface preferences do not include cloud project source, Knowledge, KV, or run-record bodies.

Clicking the cloud project card will directly open the cloud workspace without creating a local copy or downloading the source code. File, structure, version, run history, repository, and KV are all read from Workflow Server; cloud files and project information are read-only in Desktop.

The cloud workspace can directly initiate a remote streaming run, and supports canceling the run and submitting or canceling the waiting input of the workflow. Cloud sessions and run bodies are authoritatively sourced from the server, and Desktop does not copy them to local SQLite or browser localStorage.

Download or copy a cloud project​

The cloud project's latest version must be published in source mode and the current account must have source-download permission before the menu enables either local-download action. A bundled version does not include original TypeScript or JavaScript and cannot become an editable local project. When no version is published or permission is missing, the menu explains why the action is unavailable.

"Download to Local" reserves the server project UUID and registers the server address and project ID association locally. If the same project as UUID already exists on this machine,Desktop will refuse to overwrite it. "Copy to local project" generates a new UUID from Desktop, clears the server project identity, and gets a separate ordinary user project. Both operations will select or confirm the local directory first, and then download the source code, atomic write and registration. If it fails, no semi-finished products will be left and dependencies will not be installed automatically.

When you switch the server account, API key, or server address,Desktop immediately closes the current cloud project and clears the list of projects, running status, and session memory that only belong to the previous identity. Downloads of cloud projects that have not yet entered the local write phase are also canceled; local projects, running records, and local sessions are not affected.

Join a cloud project by invitation​

Click "Join Project" in cloud mode on the Desktop and paste the invitation link shared by the project administrator. Desktop displays the project name, invitation role, and expiration date first; it does not provide an accept action if the invitation is used, revoked, or expired.

Accepting the invitation requires logging in to the Workflow Server account. Confirm acceptance after login, and the project will be added to the cloud list of the current account. Then you can directly open the cloud workspace. The invitation link is used only in this dialog and is not written to the local project, SQLite, or localStorage.

Search, filter, and sort​

Enter a name in the project toolbar to narrow the project scope in the current mode. Type filtering supports All, Workflow, and Conversation; items are sorted by Recently Edited by default, or you can switch to Name. Reset appears only if there is a search term, type filter, or Name sort; when clicked, it clears the search criteria and restores all types and Recently Edited sorting. On upgrade, the old persisted default Name sort migrates once to Recently Edited; an explicit Name choice made afterward is still remembered.

In Graph view, Desktop reads each project's workflowCode.projectInfo.relatedProjects from the current Local / Cloud scope and connects visible related projects with lines. Connected components flow from left to right; reciprocal relationships using aliases such as parent / child / grandchild retain their parent, child, and grandchild hierarchy. Components continue downward when space runs out, and projects or ordinary folders without relationships are arranged below them. Click a card to open its project or folder, or right-click it to open the same actions available from its More button. You can pan, zoom, or fit the graph to the canvas. A search keeps the complete relationship chain around every true match and highlights the matching nodes. Projects from the other scope, hidden projects, and projects unavailable to the current account do not reappear through a relationship.

When you return to the home page after opening a project,Desktop retains the previous search criteria, sort method, and list position. When there are no matching items, the page displays the current filter criteria and provides a reset entry; this is separate from the first-use state where no items have been created.

Identify Project Cards​

The project card uses the project name as its primary information and displays the current-interface-language result verbatim. Names such as @workflow-code/gitlab-webhook are not split into an organization and short name. Built-in items are clearly identified and can still be independently associated with server state.

Project cards do not show their UUID by default. A project saved only on the current device does not repeatedly label itself as a local copy. Desktop checks local source: a project calling workflow.getServerLLMCredentials() shows Sign-in required, indicating that runtime needs the current Workflow Server account. Cards show server association, local modification, or exception state when useful and provide the relevant recovery action. Each card's More menu remains available for project-level actions.

Server Web​

Server Web is a server administration interface separate from the Desktop. It connects only to Server and manages server projects, versions, run history, environment variables, schedules, Webhooks, and public Embeds. It does not host the Desktop renderer or read local project directories.

To publish a local project, bind and upload it from the Desktop or use CLI workspace upload / workspace publish. The Desktop and CLI select text and binary files with the project-root .workflowignore; .gitignore does not participate in upload selection.

Create New Project​

Click New Project

On the home page, click New Project, choose a Workflow or Conversation project type, select a sample, and enter a project name. Workflow currently includes a minimal sample that outputs only Hello; Conversation includes a sample that outputs Round i output for each turn without calling an LLM. Desktop Main generates a UUID and immediately writes it to package.json.id, explicitly writes workflowCode.projectInfo.dataStorage.mode: "both", and generates a high-contrast icon and background color pair for every new project. A local project and its cloud application created together use the same UUID, colors, and complete projectInfo. More project types and samples can be added over time.

Select item storage location as required

The project storage location can be left unselected. In this case, Desktop will use the default project directory maintained uniformly. When a custom location is required, a parent directory is selected through the system directory selector, which does not need to be empty. Desktop will create a subdirectory named after the project name under the parent directory. If the directory with the same name already exists, it will stop creating and prompt to modify the project name or storage location. The existing content will not be overwritten or the time suffix will be automatically appended.

Create cloud apps by login status

Whether signed in or out, package.json.id already contains a valid UUID when local file creation finishes, so the project can run locally and access allowed local data immediately. Desktop does not create a cloud application while signed out. When signed in, it uses the same UUID to atomically create a private cloud application after creating the local files, submitting the name, type, card metadata, and complete projectInfo in one request without uploading source. A cloud failure does not delete local files; retry later from the project menu or Information view.

Open Project

After the project creation and cloud binding are complete,Desktop opens the new project workspace directly and reads the file tree, structure information, and local environment variables. When the cloud application fails to be created, you can try again in the prompt or directly open the local project that has been created.

Clone Local Project​

Choose Clone Project from a local project's More menu. Cloning preserves the source project's code, project type, and card metadata. Enter a name for the copy and, optionally, choose where to store it; you do not need to choose the project type or sample again.

The project name is used for both the package.json.name and folder name of the replica. When no storage location is selected,Desktop uses the default project directory; when a custom location is selected,Desktop creates a subdirectory with the same name under the selected parent directory. Cloning is stopped when the target directory already exists, and the content is not overwritten or the suffix is automatically appended.

Every local copy immediately receives a new UUID distinct from its source and writes it to package.json.id, whether signed in or out. When signed in, Desktop uses that new UUID to create a private cloud application containing only project metadata after the local copy completes; source code is not uploaded. A cloud-creation failure does not delete the local copy, which can be retried or opened directly. Desktop enters the copied workspace when the flow finishes.

When a project imported or cloned from an older version has no workflowCode.projectInfo.dataStorage.mode, Desktop's New Tab catalog exposes only Information, Browser, Files, and Open Project. Select Local only, Server only, or Local and Server in an Information tab, then save. Desktop updates the project's exact Core and CLI dependencies to 0.2.0 and exposes other tools according to the declaration. It does not migrate existing KV, Knowledge, or PersistentValue data.

Import an existing directory​

Click Import Local

Select an existing Workflow, Conversation, Kanban, or other local folder. You can also drop one or more projects and folders onto Home; Desktop registers every available top-level directory in order. Every import, including reimporting the same path, refreshes the project's or ordinary folder's recent-edit time to the current time, so it moves to the front under the default sort. Importing neither copies the directory nor downloads source from Server.

Confirm the import classification

Workflow and Conversation use the root package.json and index.ts. Kanban uses workflowCode.projectType: "kanban" and its configured HTML entry, defaulting to root index.html when workflowCode.kanban is absent. New projects should use a UUID in package.json.id; a legacy empty-ID project receives a stable registry ID for migration. Obsolete fields, damaged structure, or another project-validation failure no longer block the first open: Desktop registers that directory as an ordinary folder and keeps Files, Terminal, and Developer Assistant available for direct repairs. Ordinary files, unavailable paths, and filesystem roots are not registered. Canceling the directory picker does not show an error.

Check Item Card

The project card displays the name, type, and last update time; when there is a server association, local modification, or exception, the corresponding status is supplemented.

Enter the workspace

Click the card to open the project. The import process does not automatically install dependencies; you need to manually install dependencies in the project directory before running. You can then continue to edit the file, run workflow, or publish to Workflow Server after logging in.

Remote Association​

A local project is associated with its server project through the UUID in package.json.id. Projects created or cloned by Desktop use that UUID from the moment they are written; only a manually imported legacy project may remain empty temporarily. Create Cloud Application uses the existing package UUID, or the stable registry UUID for a legacy empty-ID project and writes it to package.json.id; Server does not allocate another ID. If binding is interrupted, Desktop keeps the pending UUID. Retrying on the same server recovers that same-UUID binding instead of creating a second application, and migration errors in unrelated local projects do not block it.

Creating a cloud application synchronizes only the name, type, card metadata, and complete project declaration. Source is uploaded and a new version created only when you choose Publish. Importing a project never downloads or overwrites server source automatically.

Home's Cloud mode shows only server projects with at least one published version. Creating a cloud application registers project metadata but does not publish it. Before the first publication, the project remains editable and publishable under Local, but it is omitted from the cloud collection, search results, relationship graph, and count. It appears in Cloud automatically after publication succeeds.

Use Home tool docks​

The far right of Home Topbar provides Bottom panel and Right panel icon toggles. Both panels are hidden by default. Local and Cloud Home modes share their tabs and dimensions, while this state remains isolated from every project workspace dock. The Recent Tasks rail keeps its width. Developer Assistant, terminal, and browser instances stay alive while you visit a project or Settings and resume when you return Home.

Home New Tab exposes only Developer Assistant, Terminal, Browser, and Open Project. Files, Run, Information, Knowledge Base, KV, Logs, and Diagram are not direct Home tools. Home Terminal and Developer Assistant always use the current operating-system user's home directory and do not offer a path picker; Developer Assistant cannot access paths outside that home. Open Project can select a local project, cloud project, or available ordinary folder. Local and cloud project rows show Local or Cloud at the far right, and project-specific tools appear only after you explicitly select a target.

View Recent Tasks​

The most recent tasks on the left side of the home page follow the "local/cloud" mode switch:

  • Local mode reads the local run history in the current device SQLite and merges the running tasks that have not been persisted. The same scheduled plan of the same project is merged into one plan record before paging, and the ordinary manual operation is still displayed one by one.
  • The cloud mode reads the running logs initiated by the Desktop on the current server, and does not display local SQLite records, and does not display CLI, Webhook, Embed, or run initiated by other clients.

Switching modes resets pagination, loading, and error state so tasks from the previous mode never flash briefly. Cloud mode requires sign-in. When you are signed out, there are no matching records, or a read fails, Recent Tasks shows its own message and recovery action.

The recent task title is fixed at the top of the list, and the tasks are in a compact single-line list without the use of independent cards. Ordinary tasks and scheduled schedules are arranged in reverse order according to their latest running time, and priorities are not adjusted according to the running results. The number of pages is calculated according to the combined display records, and the underlying running history is not deleted. When the list title is attached, it will be close to the bottom edge of the nearest task title, and the account entry will be fixed at the bottom of the sidebar.

The scheduled-plan record shows a Scheduled marker before the plan name, along with its project, latest run time, retained local run count, and failure count. Select it to open the plan's latest run; the complete result of each trigger remains available in a Schedules dock tab for the project.

Each task retains a status ID:

  • running is displayed as running. Tasks that have just started and have not yet been written to local history are also displayed immediately.
  • waiting_for_input appears to request user approval.
  • failed, timed_out, success, aborted, and other finished states display the corresponding run results.

A Workflow task shows workflow name and the actual entry-point title and ID. An old record without an entry-point snapshot shows Default / legacy entry point. A local Conversation task shows its session title and workflow. Selecting a local task opens the local project and run; selecting a cloud task opens the server project and corresponding server run without falling back to a same-UUID local log. Tasks with a conversation ID also identify the session.

Display and window status​

Home supports both light and dark themes. In addition to color, the project status will be expressed by icons or text. During keyboard operation, search, filter, project card, task and menu will display clear focus indication.

As the window narrows, project cards adapt from multiple columns to two or one column. The project toolbar may wrap but never forces horizontal page scrolling. Recent Tasks can collapse and be restored from the sidebar.

Closing the last window does not exit Desktop: the main process continues to reside in the system tray for local Workflow scheduled tasks. The main window can be restored from the tray; only selecting Exit Workflow Code stops scheduling, cancels runs still held by Desktop, and frees local resources. The same closing semantics are maintained when no local schedule is configured.

The project list and recent tasks show the loaded, empty, and error status, respectively. Loading or failure of one 1 area does not prevent the use of another 1 area; when it fails, Desktop will try to keep the content of the last successful load and provide recovery feedback near the corresponding operation.

Built-in project​

Sample projects are not automatically imported when the release is first opened. Built-in projects are managed separately in "settings> built-in projects": lightweight projects such as Conversation can be installed directly, and projects with larger runtime such as Codex and OpenCode will download corresponding resource packages according to the current system and CPU architecture.

Project Assistant and its Desktop Control dependency are hidden built-in projects, so neither appears in the Home project collection, search results, or project count. Project Assistant supports only the user home directory, editable local user projects, and available ordinary folders. Cloud projects, built-in projects, and read-only local projects omit the entry. On first open, Desktop ensures OpenCode and Desktop Control are installed, then installs and registers Project Assistant. The tab shows download or installation progress and provides an in-place retry after failure. It defaults to the right dock and can be sorted or moved to the bottom. Hiding a dock or navigating away retains the tab and session; explicitly closing the tab releases that view instance. Project Assistant and Conversation projects in a Dock always retain the conversation picker and new-conversation action at the top, even when the panel is resized wider. A user-home assistant task is labeled User home directory in Recent Tasks and returns to its matching Home tab and conversation.

The installation process displays the download and installation status. Desktop will verify the resource size and SHA-256, and then switch to the new version atomically. If the download, verification, or decompression fails, the available version will continue to be retained. Installing or updating built-in projects does not require a native installation of Node, pnpm, or other package managers.

When the built-in items are installed or removed, the list of home items is automatically updated.

Codex, Conversation, OpenCode, and the assistant all use the system AI configuration of the current login account. They do not read the login status of the local agent and do not require the upstream key to be saved in the project environment. Codex only supports OpenAI Responses, and limits the optional models to the built-in compatibility list, which uses gpt-5.6-terra and high inference strength by default. OpenCode supports OpenAI Responses and Anthropic, and gpt-5.6-terra and claude-sonnet-5 are preferred respectively. OpenAI models also use the compatibility list. Conversation uses these two preferred models by protocol, but retains the other models that are currently open to Provider; model options show visual, networking, inference, and tool invocation information in the Server capabilities catalog, and enable search only when the current model declares networking capabilities. All four items re-validate the selected configuration and model before each turn. The composer combines Model and Effort into one quick summary trigger; opening it still exposes Provider, permission, sandbox, and every other quick parameter, plus one reset-to-defaults action. When opening OpenCode directly, you can still select read-only, workspace automatic approval or OpenCode --auto in the conversation shortcut options. Project Assistant uses workspace auto-approval and denies access outside the authorized user home directory, editable local project, or ordinary folder scope.

When started with pnpm dev from the Desktop repository root, the Desktop automatically loads the sibling build-in-conversation, build-in-codex, build-in-opencode, build-in-desktop-control, and build-in-developer-assistant repositories, runs them directly from their source directories, and watches for file changes without installing or copying versioned directories. Set WORKFLOW_BUILTIN_PROJECTS_SOURCE_ROOT to use another parent directory containing those repositories. Subsequent reads and runs use saved source changes immediately and do not access the download service. pnpm dev and pnpm dev:shared-electron, which reuses an existing Electron binary, use the isolated workflow-code-dev and workflow-code-dev-shared-electron development data directories respectively; neither reads the other or the installed Desktop's data. Set WORKFLOW_CODE_ELECTRON_USER_DATA_DIR to use another temporary directory. Built-in project installation and maintenance are enabled only in packaged Desktop builds, which check https://wfupdates.yuhe.space/builtin-projects by default. Each built-in project is released independently with its own index.json; every release atomically declares minDesktopVersion and exact Core/CLI components. Desktop selects the newest release whose Desktop minimum is met and whose two components share the host's respective major.minor lines, then requires the downloaded package pins to match the index exactly. Patch and dated Alpha ordering within a line does not affect selection. Desktop revalidates mutable indexes on every check, while versioned resources protected by hash verification can be cached long term. Downloads have no fixed application-level total deadline. Platform archives stream into a staging directory and are verified against the size and SHA-256 in the index. Validation, extraction, or registration failures preserve the previous usable version, and an installed version remains available offline when its index is temporarily unreachable. Private deployments can set WORKFLOW_BUILTIN_PROJECTS_URL to a complete resource root that provides each project's index.json and referenced platform archives. manifest.json remains only for older Desktop compatibility and is not used for new version selection.

Built-in projects can run and create copies, but cannot directly edit, rename, publish, or delete their built-in source code. Creating a copy will generate a new project UUID. The copy becomes a local project of an ordinary user and can be maintained according to its own dependency and publishing process.

Codex, Conversation, OpenCode, and Project Assistant now pin Core/CLI 0.2.0 and explicitly declare dataStorage.mode: "both". They require Desktop 0.1.22 or newer: Desktop/CLI select local data, Server Web selects server data for the same project UUID, and neither location falls back to, copies, or synchronizes with the other.

Modify Item Card​

Edit Desktop Information in the item menu updates the workflowCode.projectCard of the local package.json:

{
  "workflowCode": {
    "projectCard": {
      "icon": "message-circle",
      "iconColor": "#f8fafc",
      "iconBackgroundColor": "#0f766e"
    }
  }
}
  • Item type does not belong to card metadata. Desktop derives from workflow.defineExecutor({ projectType }) in the source code and displays only workflow or conversation.
  • icon Use the Desktop built-in icon token.
  • iconUrl The WebP address that Desktop writes to the server after uploading the custom image. http:// or https:// addresses already in the old project can still be displayed, but Desktop does not provide manual entry.
  • iconColor Use #RRGGBB to control the built-in icon color; use white when the old project is not configured.
  • iconBackgroundColor Use #RRGGBB.

Click "Edit Icon" in the project information to focus on adjusting custom images, built-in icons, icon colors, and background colors. Custom pictures support PNG, JPEG and WebP. After selection, you can preview, crop and zoom at a ratio of 1:1. Desktop will generate 512x512 WebP and upload it to Workflow Server bound to the current project when saving the project information. When the project has not created a cloud application, or the current connection is not bound to the server, the built-in icon can still be used, but custom images cannot be uploaded. If the upload or synchronization fails, the cropped draft will be retained and can be retried directly.

The preset color scheme applies both the icon color and the background color; Random Color only generates color combinations with opposite light and dark directions and a contrast of at least 4.5:1.

Saving application information does not change the project type, project ID, or run history. If the old project still contains workflowCode.projectCard.kind, you need to delete the field and complete projectType on executor before you can import or run again.

Login status​

The lower left corner of the home page shows the current account status:

StatusWhat you can do
Not logged inCreate, import, and edit projects; projects declared as local or both can use local data and run offline.
Login expiredContinue publishing, pulling, and reading server history after logging back in.
Logged inAccess server data allowed by the declaration and, after same-UUID binding, publish, pull, run remotely, and read server history.

Local editing does not require sign-in. Only local and both declarations allow local storage. A server declaration requires sign-in and same-UUID cloud binding. A both project requires a valid account only when it actually accesses server data, publishes, pulls, runs remotely, or reads server history.

Next step​