Drıftstack docs
Docs

License activation (desktop app)

You don’t need to find or buy a license key. The Driftstack desktop app defaults to secure browser sign-in: authorize the device in the dashboard and the app automatically stores its restricted device credential. You do not need to create or paste a customer API key. A cloud customer key or a key created on your self-hosted Driftstack server remains available as a fallback. On a self-hosted server, browser sign-in works only when your server has it set up; if it does not, paste a key created on that server.

What you need

  • The desktop app, a free download from driftstack.io/download (the Driftstack releases page). Do not install builds from anywhere else.
  • A Driftstack dashboard account for the default browser sign-in flow.
  • Any cloud plan, the free trial included, can activate the desktop app; self-hosted Solo/Pro/Enterprise customers point at their own server URL.
  • Only if using the fallback: a ds_live_… customer key from any plan with API access (not the earlier Free plan), or a key created on your own self-hosted server.

First-run flow

On first launch, the desktop app opens a three-step wizard, then a Done screen:

  1. Welcome — a “Welcome to Driftstack” screen with a short description of the app.
  2. Hosting — radio: Cloud (https://api.driftstack.dev) or Self-hosted (you paste the URL of your own Driftstack server).
  3. Sign in — use Sign in with browser by default. After you approve the device (the app shows a short code to enter in the browser), the wizard checks the returned credential with the server and then stores it. There is nothing to copy from the API-key page. Have an API key? Paste it instead is the cloud/self-hosted fallback. You see one of:
    • ✅ valid — wizard advances.
    • ❌ wrong fallback key — the message is deployment-aware. Cloud mode: “This API key wasn’t accepted. Double-check it, or create a new one at app.driftstack.io/api-keys.” Self-hosted mode explains that the key must be created on your own server’s dashboard — a cloud key will not authenticate against a self-hosted server.
    • ❌ unreachable — the message starts with “Couldn’t reach <url>.” and gives URL, connection, firewall, VPN, and self-hosted-server guidance. A server that does not answer within 10 seconds shows “The request took too long. Check your connection and try again.”
    • ❌ not permitted — the privacy-safe fixed message is “You do not have permission to perform this action.” Check the account status and team access in the dashboard; the app does not show the server’s reason.

Then the Done screen says “You’re connected.” Choose Open the starter guide to add a proxy and create your first profile step by step, or Skip to the app.

Where credentials live

  • Device credential or fallback API key — stored in your computer’s secure credential store: the Keychain on macOS, Credential Manager on Windows, the Secret Service on Linux. It never lands in settings.json on disk.
  • Base URL — stored in the app’s settings.json file. Plaintext is fine here; the URL alone confers no access.

If you delete that stored entry manually, the desktop app 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. Sign out (in Settings, the Connected panel; or the sidebar; or ⌘ Shift L). It removes the current deployment’s credential from the credential store without revoking it on the server, and clears this computer’s copy of the account’s data after you confirm; the non-secret base URL and other preferences remain in settings.json. On a server that does not keep AI chats on the account, signing out deletes this computer’s chats for good.
  2. The first-run wizard reappears immediately. Pick the new deployment mode.
  3. Use browser sign-in (on a self-hosted server, when your server has it set up), or paste the matching cloud or self-hosted fallback key.

Alternatively, open Settings → API & connection, choose Cloud or Self-hosted, enter the server address and that server’s key, and choose Save. The app checks the key and remembers one key per server.

Self-hosted activation

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

  1. Our team installs and sets up the Driftstack server on your own Macs with you (Self-hosted).
  2. Create an API key in your own server’s dashboard, the same way as on cloud.
  3. In the desktop app wizard, choose Self-hosted, paste the URL of your server (e.g. https://drift.your-company.internal), then use Sign in with browser if your server has it set up, or choose Have an API key? Paste it instead and paste the key.

The same desktop app works with cloud or self-hosted — there is no separate “self-hosted edition”. The deployment-mode toggle is the only switch.

Platform support

  • The desktop app supports macOS, Windows and Linux. Every release builds a .dmg for macOS 12 or later, a -setup.exe installer (NSIS) for 64-bit Windows, and an .AppImage and a .deb for 64-bit Linux. Installers are published as GitHub Releases from a gui-v* tag.
  • Builds are not Apple Developer ID code-signed, hardened-runtime, or notarised. macOS therefore shows an unidentified-developer warning the first time you launch the app: right-click it in Applications, choose Open, and confirm. The release artifacts are signed with our Tauri updater key, which is what the update check below verifies — that signature proves an update came from us, and is a different thing from Apple code signing.
  • The Windows installer is not code-signed either, so Windows SmartScreen may stop it the first time: choose More info, then Run anyway.
  • On Linux, the .AppImage runs without installing; the .deb installs on Debian and Ubuntu.

Updates

Tauri Updater checks the signed GitHub Releases manifest when the app opens and every few hours while it stays open. By default the app installs a newer version on its own: the updater downloads the bundle, verifies its signature against the embedded public key, installs it, and relaunches the app. It never installs while a session is running, because the relaunch would end it; the app shows a non-blocking in-app banner naming the new version instead, and you choose when to install. To be asked before every update, turn off Install updates without asking in Settings → Updates.

Troubleshooting

  • “This API key wasn’t accepted” — retry cloud browser sign-in first. If you chose the fallback, verify that the key belongs to the selected deployment. In self-hosted mode, a cloud key never works against your own server (and vice-versa). Settings re-validates credentials and shows the same guidance.
  • “Couldn’t reach …” — for cloud, check status.driftstack.io. For self-hosted, check your server’s /v1/status endpoint directly.
  • The setup wizard appears on every launch — the app could not reach your computer’s credential store to save its credential. Reinstall the official build if your copy was modified or quarantined.
  • “You do not have permission” on activation — sign in to the dashboard and check the account status and selected team. If the account is active and access still fails, email [email protected].

Next steps