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.
- Each token is bound to one device. Your account page → Connected devices lists every paired device with product, OS, app version, and last-seen time.
- 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 is what keeps the “last seen” column fresh.
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 an opaque JSON slot per project (the Cues show, a DJ setlist…), with version numbers for conflict detection and a version history with restore |
| 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-seen fresh |
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.
If a desktop app reports it’s been signed out, the usual cause is a revoked device or licence — re-pair from the app and it’s back.