D driftstack docs

License activation (GUI client)

The Driftstack desktop GUI client (Tauri 2.x — macOS, Windows, Linux) doesn’t use a separate license-key system. It activates against the same API key you use for SDK calls, and points at either the cloud control plane or your own self-hosted instance.

What you need

  • The desktop app installed. Download links land at driftstack.dev/download once the first signed builds publish.
  • An API key from app.driftstack.dev/api-keys. Same shape as the API key your SDK calls use.
  • Your tier supports GUI client access. Cloud customers on any Manual or API tier (or trial pack) can activate; self-hosted Solo/Pro/Enterprise customers point at their own server URL.

First-run flow

On first launch, the GUI client opens a five-step wizard:

  1. Welcome — brand intro and a one-line value prop.
  2. Deployment mode — radio: Cloud (https://api.driftstack.dev) or Self-hosted (you paste the URL — defaults to http://localhost:7780).
  3. API key — paste the key. The wizard immediately calls GET /v1/account/me to validate. You see one of:
    • ✅ valid — wizard advances.
    • ❌ wrong key — “Authentication failed. Check the value at app.driftstack.dev/api-keys.”
    • ❌ unreachable — “Couldn’t reach the control plane at <url>. Check the URL and your network.”
    • ❌ tier-suspended — “This account is suspended. Email [email protected].”
  4. First profile (skippable) — name + archetype picker. The wizard calls POST /v1/profiles against the validated client.
  5. Done — flag flipped; main app shell takes over.

Where credentials live

  • API key — stored in the OS keychain (keyring-rs): macOS Keychain, Windows Credential Manager, Linux Secret Service / kwallet. The key never lands in settings.json on disk.
  • Base URL — stored in the Tauri settings store (settings.json). Plaintext is fine here; the URL alone confers no access.

If you delete the keychain entry manually, the GUI client treats the next launch as first-run and walks you through the wizard again.

Switching deployments

To re-point the GUI from cloud to self-hosted (or vice versa):

  1. Settings → Account → Sign out. Wipes the keychain entry and settings.json baseUrl.
  2. Restart the app. The first-run wizard shows again.
  3. Pick the new deployment mode and paste the matching API key.

Alternatively, edit settings.json (Tauri’s app data dir) directly to change baseUrl, then re-paste a key in Settings → Account → API key.

Self-hosted activation

For self-hosted deployments (Driftstack Self-Hosted Solo / Pro / Enterprise):

  1. Stand up the control plane on your own hardware per the self-hosted runbook (publishes with the first SH release).
  2. Create an API key against your local control plane (same /v1/api-keys flow — local admin scope).
  3. In the GUI client wizard, choose Self-hosted, paste the URL of your control plane (e.g. https://drift.your-company.internal), paste the key.

The same GUI binary works against any control plane — there is no “self-hosted edition” of the desktop app. The deployment-mode toggle is the only switch.

Cross-platform notes

  • macOS — primary build target. Signed and notarised under the Apple Developer ID program (cert pending — landing pre-launch).
  • Windows — EV cert + Tauri Updater pending pre-launch. Until cert lands, SmartScreen may flag the binary on first launch.
  • Linux — .AppImage and .deb artifacts unsigned; technical operators run them as-is.

Updates

Tauri Updater + GitHub Releases ship updates automatically. The app polls the manifest URL on startup, downloads + signature-verifies new versions in the background, and prompts you on next launch. See the gui-client packaging notes for the full update protocol.

Troubleshooting

  • “Authentication failed” — verify the key in app.driftstack.dev/api-keys. Revoking and reissuing the key is the safest reset.
  • “Couldn’t reach control plane” — for cloud, check status.driftstack.dev. For self-hosted, check your control plane’s /v1/status endpoint directly.
  • Wizard re-fires on every launch — the keychain backend may be unavailable. On Linux, install gnome-keyring or kwallet. On macOS, check that the app has Keychain entitlements (re-install if recently quarantined).
  • Tier-suspended on activation — the account is in a suspended state in billing. Email [email protected] with the account email and we’ll resolve.

Next steps