# 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](/docs/install-chengos) instead.

## Platforms and downloads

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

| Platform | File |
|---|---|
| Windows 10/11, x64 | `ChengFlow_0.2.0_x64_en-US.msi` |
| Linux, amd64 (Debian/Ubuntu) | `ChengFlow_0.2.0_amd64.deb` |

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:

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

| Platform | Data directory |
|---|---|
| Windows | `%ProgramData%\ChengFlow` (shared by every account on the machine; each account keeps its own sign-in session) |
| Linux | `$XDG_DATA_HOME/chengflow`, normally `~/.local/share/chengflow` |

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

| Symptom | Cause |
|---|---|
| "Failed to bind the local API port" | Something else holds `127.0.0.1:19225` — often a native ChengOS install |
| The app says it is already running | Another copy holds the data directory lock |
| Refuses to start on Linux | Launched as `root`; start it as your normal user |
| Data directory not writable (Windows) | The installation is damaged; repair or reinstall the `.msi` |
| Need to ask for help | Use **Copy diagnostics** in the app: versions, ports, and paths, with no passwords or keys |

## Next steps

- [Your First Workflow](/docs/quickstart-first-workflow) — build something in the editor.
- [Installing ChengOS](/docs/install-chengos) — the server installation, for teams.
- [LLM & Model Configuration](/docs/config-llm-models) — connect a model.