Install ChengFlow Desktop

Applies to: ChengOS v0.2.0+ ｜ Last verified: 2026-09-26 ｜ Source: chengflow-ui/src-tauri/tauri.conf.json, chengflow-ui/src-tauri/src/paths.rs, chengflow-ui/src-tauri/src/server.rs, .github/workflows/desktop.yml

ChengFlow Desktop runs the visual workflow editor and its execution engine on your own computer, with an embedded PostgreSQL database. There is no server to deploy and no account to create. It is the quickest way to try ChengFlow alone; for a shared or always-on system, use a server installation instead.

Platforms and downloads

The v0.2.0 release ships two desktop installers on the GitHub release page:

macOS is not available: it needs a signing identity and notarization first. Files named ChengApp_… on the same page are the separate ChengApp client, not ChengFlow Desktop.

Install

Windows — run the .msi. The program goes to C:\Program Files\ChengFlow, which stays read-only. The installer also creates the data directory %ProgramData%\ChengFlow and grants your users write access to it, so the first launch never has to ask where to put anything.

Linux — install the package with your package manager:

sudo apt install ./ChengFlow_0.2.0_amd64.deb

Start ChengFlow from your applications menu as your normal user. It refuses to run as root, because the embedded PostgreSQL will not run under a privileged account.

First launch

The first start takes longer than later ones. In order, the app:

1. takes a lock on its data directory, so two copies can never share one database;
2. initializes and starts the embedded PostgreSQL;
3. writes config/.env from a template and applies database migrations;
4. starts the ChengFlow API on 127.0.0.1:19225 — loopback only, never on the network;
5. opens the editor window.

You are signed in automatically: the desktop build always runs in single-user mode, so it works offline.

Port 19225 must be free. The port is fixed so other local apps can find the engine. A native ChengOS server on the same machine uses the same default port; stop it before starting the desktop app.

Where your data lives

Inside it: pg-data (the database), config (your .env), logs, backups, and webview (the window's browser profile, including the session).

To move everything elsewhere, set the environment variable CHENGFLOW_DATA_DIR before starting the app. A location that cannot be used is an error at startup, never a silent fallback to somewhere else.

Configuration

Settings live in config/.env inside the data directory. It is created on first launch with every setting commented out; uncomment what you need and restart. Updates never overwrite your edits — they only append settings that did not exist before.

The desktop shell manages a few settings itself, and they have no effect in this file: DATABASE_URL, JWT_SECRET, CREDENTIAL_MASTER_KEY_1, REDIS_URL, RUN_MIGRATIONS, CHENG_AUTH_MODE, CORS_PERMISSIVE, and the log and env-file paths. Workspace and skill directories default to the data directory but can be changed here.

Updates and uninstalling

Install a newer release over the old one. When a new version is about to change the database schema, the app first takes a cold copy of the database into backups, before PostgreSQL starts, so a failed upgrade has a restore point. Only a few backups are kept.

Uninstalling (Windows Apps & features, or removing the package on Linux) keeps your data by design. To remove it as well, use Uninstall and remove data — the Settings option inside the app, or the matching shortcut on Windows. That deletes the database, configuration, logs, and the stored session. The shared sign-in store under ~/.config/cheng/auth, which the cheng CLI and the ChengApp client also use, is reported but not deleted.

Troubleshooting

Next steps

• Your First Workflow — build something in the editor.
• Installing ChengOS — the server installation, for teams.
• LLM & Model Configuration — connect a model.