Client Generator

The BetterDesk Support Generator in the web console builds incoming-only desktop installers from BetterDesk-Client portable templates. Each build injects a server-locked custom.txt (rendezvous, relay, API, public key). End users download from a public hub page — no manual network configuration.

Appearance (logo, colors) is not baked into installers. The desktop client loads branding at runtime from the Console Client Branding API.

What you get

Each Support bundle produces portable artifacts that:

Use BetterDesk-Client desktop binaries (AGPL)
Force incoming-only (conn-type: incoming)
Override server settings via signed or plain custom.txt
Target Windows / Linux / macOS (x64 + ARM64 portable)

Platform	Format
Windows x64 / ARM64	Portable `.zip`
Linux x64 / ARM64	Portable `.tar.gz`
macOS Intel / Apple Silicon	Portable `.tar.gz`

Module install (first run)

Before creating bundles, admins install the betterdesk-support-generator module:

Open Generator
Read the AGPL / incoming-only notice and click Accept terms
Click Install from GitHub — downloads and verifies generator-templates-*.tar.gz from BetterDesk-Client Releases (BETTERDESK_CLIENT_REPO, default UNITRONIX/BetterDesk-Client)
Alternatively choose Install local package and upload the archive downloaded from a Client release
Click Finish installation when status is ready

Module data lives under:

{dataDir}/modules/betterdesk-support-generator/
  state.json
  templates/          # extracted generator-templates layout + manifest.json
  custom-client-signing.seed   # required for production Support builds; from env or file

Signing seed:

Env: BETTERDESK_CUSTOM_CLIENT_SIGNING_SEED (base64 32-byte NaCl seed)
Or file custom-client-signing.seed copied into the module dir

The module refuses to become ready without a valid seed. Every production Support bundle contains a signed base64 custom.txt (Phase B); unsigned plain JSON is available only to debug builds of the client.

Quick start

Log in as admin and finish module install
Open Generator → New Support
Enter bundle name, optional app name, confirm server / relay / API (prefilled from console defaults)
Select platforms and Save
Watch build status; share the download hub link (/d/:slug)

Connection fields

Defaults come from /api/generator/defaults (keyService + clientConfigHost):

Server host / relay host
HTTPS toggle + API port
Server public key (id_ed25519.pub)

The worker writes custom.txt beside the binary (or under Contents/MacOS on macOS) using the Support Agent example shape (override-settings, conn-type: incoming).

Service and autostart

The bundle editor exposes two opt-in settings:

Install Support Agent service — creates the platform service.
Start Support Agent automatically — enables service/startup autostart.

Both are disabled by default. Windows bundles contain PowerShell install/uninstall scripts; Linux bundles contain systemd scripts; macOS bundles contain LaunchDaemon scripts. The scripts request elevation only for the service installation operation.

Generator environment

For native, Docker and Windows installations configure these values in the BetterDesk environment file:

BETTERDESK_CLIENT_REPO=UNITRONIX/BetterDesk-Client
BETTERDESK_CLIENT_RELEASE_TAG=
BETTERDESK_GITHUB_TOKEN=
BETTERDESK_CUSTOM_CLIENT_SIGNING_SEED=
AGENT_ARTIFACT_DIR=<dataDir>/agent-builds
AGENT_BUILD_WORKER=on

The signing seed is secret. The console service account needs read/write access to the module, build cache and artifact directories, while the seed should be readable only by the console service. Do not expose agent-builds or the module directory as a static web directory.

Architecture notes

Piece	Role
`supportGeneratorModule.js`	Terms + GitHub template install gate
`customTxtBuilder.js`	Build / sign `custom.txt` (`tweetnacl`)
`clientTemplateWorker.js`	Queue builds, inject templates, store artifacts in `data/agent-builds/`
`agent_bundles` / `agent_bundle_builds`	Existing DB tables (product_type `betterdesk-support`)

Legacy Go Support Agent (betterdesk-support-agent) and compile-on-console workers are removed. Old product types (support-agent, agent, agent-client, rdclient) normalize to betterdesk-support for compatibility.

Security notes

Bundles do not embed a shared enrollment token
Each install registers independently; managed mode issues a device_token after operator approval
Support clients are inbound-only — end users cannot browse or connect outbound to other devices on your infrastructure
Support clients load company name, colors and logo at runtime from GET /api/branding; branding images are sent through the Client Branding API and are not baked into the bundle.
The server does not push generic heartbeat strategy settings to betterdesk-support devices.
The signing seed on the console must match the public key baked into Client releases.

Start

Console

Ops

Help

Advanced

Source: docs/wiki/

Repository · Issues · Discussions · Releases · Privacy · Sponsors

Wiki source: docs/wiki/ — last sync: 2026-09-06