Passwork desktop application

Passwork Desktop application lets users work with Passwork without a browser. It is suitable for teams that prefer a standalone app window or work in environments where browser usage is restricted or unavailable. The app connects to your Passwork server using the backend URL. Its functionality is equivalent to the web version.

• How Desktop download and updates work
• Update server and air-gapped networks

---

Overview and capabilities

The application provides access to all Passwork functionality in a dedicated window, just like the web interface. Business logic and access rights are still defined by the Passwork server.

How it works:

• Browser-based sign-in. The first sign-in (or sign-in after changing server/account) happens on the Passwork page in a browser. After successful authentication, the browser returns a one-time token to the app, and the app creates a local session. This supports all server-configured authentication methods: login/password, LDAP, SSO, 2FA, and passkeys.
• Client-side encryption. If client-side encryption is enabled on the server, the app also requests the master password. The master key is stored locally in encrypted form using OS-level security mechanisms.
• Local data storage. The server URL, tokens, and session state are stored on the workstation.

Platforms: Windows (x64), macOS, Linux (AppImage, .deb, .rpm).

Local application storage

Passwork Desktop service data (server URL, access/refresh tokens, session metadata, scenario flags, and if client-side encryption is enabled, the master key) is stored on the user side.

• Database file. All records are stored in a single local database file app-data.db (NeDB) in the application data directory (userData):
  • Windows: %APPDATA%\Passwork\app-data.db;
  • macOS: ~/Library/Application Support/Passwork/app-data.db;
  • Linux: ~/.config/Passwork/app-data.db (or a path from XDG_CONFIG_HOME).
• Plain vs encrypted fields.
  • Plaintext: technical settings (for example, server URL, window size).
  • Encrypted: tokens, master key, and other sensitive fields.
• How data is encrypted.
  • Sensitive fields use safeStorage, a wrapper around the OS secret storage:
    • Windows: DPAPI / Credential Manager tied to the user account;
    • macOS: Keychain;
    • Linux: compatible Secret Service providers (GNOME Keyring, KWallet, etc.).
  • Encryption keys are not stored in app files; they are managed by the operating system. Only encrypted values (base64 strings) are stored in app-data.db.

Connecting to a server

Connection has two stages: entering the server address and authenticating. The app session is created using a one-time token received after login in the web interface.

Host selection

On the sign-in screen, the user enters the Passwork server URL (for example, passwork.company.com). The app checks that the server is reachable and responding. After a successful check, the login flow continues in the browser.

When changing server or account, the same screen is used again: you can provide a new URL and reauthenticate. A single Desktop installation can connect to different servers one after another (for example, test and production), but only one server is active at a time.

Browser-based sign-in flow

1. In the app, the user clicks Sign in via browser. This opens the Passwork web interface at <server_url>/desktop.
2. In the browser, the user signs in as usual: login/password, LDAP, SSO, 2FA, or Passkey, depending on server settings.
3. After successful login, the web interface creates a one-time Desktop token and redirects the browser to a URL like passwork://login?desktopToken=<token>.
4. The operating system passes this URL to Passwork Desktop. The app receives the token, exchanges it for a session, and stores the session locally.
5. If client-side encryption is enabled on the server, the app asks for the master password.

If the app does not open after redirect or does not receive the token, verify that the app is installed and the passwork:// scheme is not blocked.

Connection diagram

    [Desktop] -> enter host -> access check -> browser <host>/desktop
    -> [Browser] login (credentials, 2FA, SSO...) -> passwork://login?desktopToken=...
    -> [Desktop] token-to-session exchange -> (if needed) master password -> home screen

Environment requirements

• The Passwork server must be reachable over HTTPS from the computer where the app is installed.
• The <server_url>/desktop page and API requests must not be blocked by firewalls, proxies, or corporate policies.
• Passwork Desktop must be installed; installation registers the passwork:// scheme handler.

passwork:// scheme

passwork:// is a custom URL scheme handled by Passwork Desktop, not the browser. In documentation and settings this is often called a deep link.

Where it is used: to return users from browser login back to Desktop after the /desktop flow (the browser redirects to passwork://login?desktopToken=..., the OS passes the link to the app, and the app finalizes sign-in with that token).

During installation, Passwork registers the passwork scheme handler in the OS. If the app is already running, a new passwork:// link is passed to the same window instead of opening another one.

For administrators: if custom URL schemes are blocked or intercepted in your environment, passwork:// redirects will fail, and users will not return from browser login to the app. Allow passwork:// links to open in Passwork Desktop or add it to exclusions.

Updates and version compatibility

Passwork Desktop is always updated to a version compatible with your Passwork server. The server selects the suitable Desktop branch and offers users installation or update.

• In internet-connected networks, Desktop installers are available directly in the Passwork web interface.
• In air-gapped networks, installers and updates are distributed through a dedicated update server or corporate deployment tools.

LLM version