Desktop integration
The desktop apps don’t run a browser login. Instead they pair with your cloud account using a short code — the same pattern as GitHub CLI or a smart TV — and then talk to the cloud over a versioned API. This page covers pairing from the user’s side and what actually syncs.
Pairing a desktop app
Section titled “Pairing a desktop app”- In the desktop app, start the cloud sign-in. It shows a short pairing code (e.g.
WX7K-MN42) and can open your browser for you. - In the browser, go to app.helm.show/pair (sign in with Google if you aren’t already).
- If the desktop opened the link for you, the page already knows the request — you’ll see a consent card: which product, which device, OS and app version, plus the account you’re signed into. Click Authorize (or Deny).
- Coming to
/pairmanually instead, type the code from the desktop app and click Approve & pair. - Back on the desktop: it detects the approval within a few seconds and is signed in.
Tokens and connected devices
Section titled “Tokens and connected devices”Approval issues the desktop a device token, stored in the OS keychain (never in a config file). In user terms:
- Tokens are long-lived — pair once per machine, not per session.
- 90 days unused signs a device out. The token is refused and revoked. Cues shows “Signed out of Helm Cloud after 90 days without use —” with Pair again.
- 600 requests a minute per token. Past it the API answers 429 with
Retry-After. Cues waits and retries up to 3 times. - Each token is bound to one device. Your account page → Connected devices lists every paired device with product, app version and
last used … · signs out after 90 days unused. - Revoke a device there at any point — it’s signed out immediately and must re-pair. Revoking a licence revokes its tokens too.
- Pairing codes themselves expire after ten minutes if unapproved.
While running, each desktop app heartbeats the cloud every few minutes, which keeps the last-used time fresh. Cues sends the open project with it, so the project’s Open now shows the desktop for 15 minutes.
What the v1 API exposes
Section titled “What the v1 API exposes”The desktop apps sync through the public API at app.helm.show/api/v1. What flows over it:
| Surface | Direction | Notes |
|---|---|---|
| Identity & licences | cloud → desktop | Who you are, which products you’re licensed for |
| Projects | both | List/open your projects; create and update them from the desktop |
| Files | both | Upload and download go direct to storage via short-lived signed URLs — the API brokers, it never proxies the bytes. Uploads are de-duplicated by content, so retries are safe |
| Folders | both | The desktop mirrors its folder structure to the cloud so the Assets tab matches what you see locally |
| Per-product project data | both | Each product gets a JSON slot per project (the Cues show, a DJ setlist…), with version numbers for conflict detection and a version history with restore. A Cues show also syncs per track: a stale track is refused alone, and the rest keep syncing. |
| Shows / setlists | cloud → desktop | Cloud-built setlists — Cues pulls them on sync; cloud-only-edited in v1 |
| Annotations | cloud → desktop | Read-only: the desktop can display timestamped comments on its timeline; creating them is web-only |
| Heartbeat | desktop → cloud | Keeps the device’s last use fresh, and names the open project for Open now |
Current status
Section titled “Current status”Helm Cues is the active integration: it pairs, pushes its show data (which powers the Cues panel and track pages), uploads the show’s media, and pulls cloud setlists. Media the show references but hasn’t uploaded yet appears in the cloud as “local only” ghosts until the desktop syncs it.
Helm DJ uses the same pairing flow and API surface; its per-product data slot is reserved and its cloud sync is being brought up against this contract. Until then, DJ shows move between machines via .helm bundles as documented in the DJ docs.
Every list pages at 200 rows by default; the desktop follows the cursor to the end.
If a desktop app reports it’s been signed out, the usual cause is 90 days unused, or a revoked device or licence — re-pair from the app and it’s back.