Run the desktop client

This guide installs the PySide6 desktop client on a workstation and signs in to a Cluster ERP server. It covers the desktop install extra, the start command, the sign-in dialog, and the most common start-up failures. Background is on the desktop client overview. Starting the server itself is described on server start-up and app factory.

Prerequisites¶

• Python 3.12 or later (pyproject.toml:9).
• A reachable Cluster ERP server. The client reads its address from the setting api_url and uses a local default when the setting is empty (src/cluster_erp/desktop/main.py:167).
• A user account on that server. The client signs in with a user name and a password (src/cluster_erp/desktop/core/api_client.py:134-140).

Steps¶

1. Install the package with the desktop extra from the repository root. The comment in pyproject.toml:68-71 names this form for a workstation; the extra adds PySide6 (pyproject.toml:72-74).

powershell pip install -e .[desktop]

2. If you choose a PySide6 version yourself, use 6.8.3. The comment in pyproject.toml:70-71 names 6.8.3 as known-good on Windows and 6.11.0 as failing with a DLL error. CI checks the client against 6.8.3 (.github/workflows/ci.yml:50).

3. Start the client. main() runs when the module is executed (src/cluster_erp/desktop/main.py:243-244). The same function is installed as the console script cluster-erp-desktop (pyproject.toml:88).

powershell python -m cluster_erp.desktop.main

4. In the sign-in dialog, check the Server field (src/cluster_erp/desktop/i18n/en.json key auth.server). It is an editable list of the last ten addresses that signed in successfully, and it starts with the client's current address (src/cluster_erp/desktop/widgets/login_dialog.py:108-124, src/cluster_erp/desktop/widgets/login_dialog.py:274-283). Type the API base address of your server, for example https://erp.example.com/api/v1.

5. Optionally pick the interface language and open Accessibility (key accessibility.title) from the bottom row of the dialog (src/cluster_erp/desktop/widgets/login_dialog.py:214-240).

6. Enter the user name and the password, then select Sign In (key auth.login_button). The client sends the request in a worker thread (src/cluster_erp/desktop/widgets/login_dialog.py:287-309). On success it stores the server address in the settings server_urls and api_url and closes the dialog (src/cluster_erp/desktop/widgets/login_dialog.py:311-314).

7. If you later need another server, change Server URL (key settings.api_url) in Preferences (key settings.title) and restart the client. The dialog saves the value and asks for a restart when it changed (src/cluster_erp/desktop/widgets/preferences_dialog.py:117-133).

Verify the result¶

• The main window opens with a sidebar, a welcome tab, and a status bar (src/cluster_erp/desktop/widgets/main_window.py:69-137).
• The status bar shows Connected (key app.connected) when GET /health on the server root answers 200 (src/cluster_erp/desktop/widgets/status_bar.py:56-88, src/cluster_erp/desktop/core/api_client.py:326-333). It checks every 15 seconds (src/cluster_erp/desktop/widgets/status_bar.py:49-51).
• The sidebar lists only sections that the server metadata declares, that the user may read, and whose apps the user may use (src/cluster_erp/desktop/widgets/sidebar.py:159-240). See metadata store and foreign-key cache.

Troubleshooting¶

Terms introduced¶

Related pages¶

• Desktop client
• Desktop client overview
• Languages, themes, and accessibility
• Local development setup

Verified against commit 92f8051 on 2026-11-13.