Manage API keys and credentials

This guide covers the full credential lifecycle in Wayland: adding a key, rotating it when it expires, removing a provider entirely, and understanding where the app stores the material so you know what to back up and what to protect.

Where credentials are stored

Desktop app (Electron)

On a machine running the Wayland desktop app, every API key and OAuth token is encrypted before it touches disk. The app uses Electron’s safeStorage API, which delegates to the OS secret store on each platform:

• macOS: the system Keychain
• Windows: DPAPI (Data Protection API)
• Linux (desktop): libsecret, backed by gnome-keyring or KWallet

The encrypted ciphertext is then stored in a column of Wayland’s local SQLite database. The plaintext key never appears in that database. If you inspect the SQLite file directly, you see only opaque ciphertext.

Linux without libsecret

On a Linux desktop that lacks libsecret or a running secret service, the OS keychain path is not available. Wayland falls back to the file-based backend described below. Running apt install libsecret-1-0 gnome-keyring and launching a keyring daemon restores the keychain path.

Headless server

When Wayland runs as a server (the wayland start npm package, or the standalone bun runtime), there is no Electron process and therefore no OS keychain. The app uses a file-based AES-256-GCM fallback instead.

The encryption key for this backend is a 32-byte random secret stored at .secret-key inside the data directory, set to mode 0600 (owner-read/write only, no other users). The data directory itself is 0700. The encryption key is derived from that secret via HKDF-SHA256 and is never stored in the database.

This is weaker than an OS keychain: anyone who can read the data directory (for example, a root-level backup process) can potentially access the secret and decrypt the stored credentials. For a single-tenant container behind Tailscale, this trade-off is acceptable and is the same posture as the rest of the 0600 config files on disk.

Back up with care

If you back up the server’s data directory, you are backing up both the encrypted credentials and the key that decrypts them. Treat that backup with the same care as a plaintext key file. The .secret-key file is intentionally excluded from Wayland’s own backup export to prevent the key from traveling alongside its ciphertext.

What is encrypted

All sensitive credential fields are encrypted regardless of backend. The classification covers any field whose name matches (case-insensitively, ignoring underscores and hyphens) one of these patterns: apiKey, token, accessToken, refreshToken, password, appSecret, and similar variants. Encrypted values carry a scheme prefix (enc:v1: for OS keychain, fenc:v1: for the file backend) so the two formats are never confused.

Add or connect a provider

1. Open Settings > Models. The grid lists every provider in the catalog.
2. Find the provider you want and click Manage.
3. Paste your API key into the credential field, or follow the OAuth flow for providers that support keyless sign-in (xAI Grok, ChatGPT).
4. Save. The provider card shows as connected.

For cloud providers (AWS Bedrock, Google Vertex AI, Azure OpenAI), the credential form has multiple fields. Fill them all in before saving.

See Add a Cloud Model Provider for provider-by-provider detail.

Rotate a key

When a key expires or you want to replace it:

1. Open Settings > Models.
2. Find the connected provider and click Manage.
3. Use the Re-key action (sometimes labeled Update key). Enter the new key and confirm.

The old ciphertext is replaced atomically. There is no window where the provider is left uncredentialed during the swap.

If Wayland cannot decrypt the stored credentials (for example, after a keychain reset or a corrupt key file), the provider shows as “undecryptable” and prompts you to re-enter the key. This is the same re-key flow.

Disconnect a provider

Disconnecting removes the provider and its stored credentials from the registry. The deletion cascades: the provider’s model catalog entries and any override rows are removed along with the credentials.

1. Open Settings > Models.
2. Find the connected provider and click Manage.
3. Scroll to the Disconnect section and click Disconnect. Wayland asks for confirmation before proceeding.

You can re-add the provider at any time by returning to the provider grid and supplying a new key.

Disable without removing

If you want to stop using a provider temporarily without deleting its credentials, use the per-provider on/off toggle on the provider’s card. A disabled provider is not offered in model selectors but its credentials remain stored and encrypted. Re-enable it to restore access.

Headless server: rotating keys

On a self-hosted server, the wayland setup command is the fastest way to update a provider key. wayland setup is the interactive configuration command installed alongside the server when you run npm install -g getwayland; it is separate from wayland start (which runs the server). Re-run wayland setup and paste the new key when prompted. Alternatively, use the Settings panel in the web UI if the server is already running.

Next

• Add a Cloud Model Provider
• Settings: Models
• Back Up and Sync