Daedalus desktop: connected accounts, the three card states and how to fix each
How the Daedalus desktop companion connects to Google, GitHub, Cloudflare, DigitalOcean, Spotify, Ghost and the Hub; what Connected, Needs you and Disconnected mean; and the fix for each.
Updated Reviewed
On this page
The Daedalus desktop companion (the House) connects to outside services from its Integrations room. Each service has one card and one way in. The full engineering reference lives in the companion repo under docs/integrations/, one page per service.
Where the keys live
Every grant, token and API key is stored in the desktop's secret service (KWallet), found by its attributes (application=daedalus, integration=<id>). Nothing secret is written to a file or a log. config.toml only holds non-secret values such as OAuth client IDs and scopes, and it is read fresh on every connect, so a scope edit counts without restarting the daemon.
The three card states
| State | What it means | What to do |
|---|---|---|
| Connected | A grant exists and its last use worked. The service's tools are available. | Nothing. The card shows the account and, for Google, any scope that was asked for but not granted. |
| Needs you | A grant exists but its token refresh failed for good: revoked, expired, or a Workspace re-authentication policy (invalid_grant, invalid_rapt). The reason shows on the card, and one desktop notification is sent per lapse. | Press Reconnect. For Google it reuses the saved client ID and secret, so it is one consent page with nothing to type. |
| Disconnected | No grant in the wallet. | Press Connect and follow the wizard. |
Reconnect or Change keys
- Reconnect approves again with the keys already saved. It is the fix for Needs you.
- Change keys opens the full wizard. Use it only when the keys themselves changed: a new OAuth client, a rotated token, a revoked API key.
A blank field in the wizard never replaces what is saved. A Google client ID and its secret only work as a pair: Daedalus uses the saved grant's client ID before config.toml's, so the two never get mixed.
Per service
- Google: OAuth with Daedalus's own Desktop app client (PKCE, loopback). After connecting, the Cloud APIs the granted scopes need are enabled in the configured project in one call; a failure there is reported, not fatal. Workspace accounts are asked to re-authenticate on a schedule, which shows as Needs you.
- GitHub: device flow (a code to enter at github.com).
- Cloudflare: a pasted API token, checked with
/user/tokens/verify. It does not refresh: a revoked token means Change keys. - DigitalOcean: OAuth. Refresh tokens are single-use, so refreshes take a file lock to avoid two processes racing.
- Spotify: OAuth. Playback control needs Spotify Premium.
- Ghost (Tea & Madness): a pasted Admin API key.
- Solnyxus Hub: OAuth against the Hub's own server, discovered from its MCP endpoint (
/api/v1/mcp), with single-use refresh tokens.
Common problems
- "Google doesn't accept that client ID and secret": the wizard got an ID from one OAuth client and a secret from another. Press Reconnect, not Change keys, unless the client itself was replaced.
- A tool says it lacks permission after a scope was added: reconnect so Google asks for the new scope, and check the card for scopes that were not granted.
- "API has not been used in project ... or it is disabled": reconnect Google; the connect enables the APIs for the granted scopes. If it still fails, enable it in the Cloud console for the project in
mind.toml. - The card stays on Needs you after reconnecting: check the desktop notification for the reason; a successful refresh clears it.