Account & Login

Kunobi uses a secure OAuth2 login to provide personalized features and connect to Kunobi cloud services. Your credentials are stored in your operating system's native keychain — never in browser storage or plain files.

Signing In

When you launch Kunobi for the first time (or after signing out), you'll be prompted to sign in.

1. Click Sign In on the login screen
2. Your browser opens to the Kunobi authentication page
3. Sign in with your account credentials
4. After authorizing, the browser redirects back to Kunobi automatically

OAuth2 / PKCE Flow

Kunobi uses the PKCE (Proof Key for Code Exchange) OAuth2 flow — the most secure option for desktop applications. This means:

• No client secret is stored in the app
• Authorization codes are one-time-use and short-lived
• Your password is never seen or stored by Kunobi

The authentication callback is handled via deep linking — the browser redirects to kunobi:// which the desktop app intercepts and processes.

Credential Storage

Authentication tokens are stored in your OS native keychain:

• macOS — Keychain Access
• Windows — Windows Credential Manager
• Linux — Secret Service (e.g., GNOME Keyring / KWallet)

Tokens are automatically refreshed before they expire so you stay signed in without re-authenticating.

Viewing Your Account

Navigate to Account in the left sidebar to see your profile information:

• Email — Your account email address
• Username — Your Kunobi username
• Full Name — Your display name

Note: Additional account management features (billing, team management, etc.) are coming soon. Full account functionality will be available in a future release.

Signing Out

To sign out of Kunobi:

1. Navigate to the Account page
2. Click Sign Out at the bottom of the page

Signing out clears your tokens from the keychain. You'll need to sign in again to use Kunobi.

Troubleshooting

Sign-in Page Doesn't Open

If the browser doesn't open automatically:

1. Check that your browser is set as the default browser
2. Try clicking Sign In again
3. If the issue persists, copy the URL from the app's error message and paste it directly in your browser

Deep Link Callback Fails

If the browser opens but Kunobi doesn't receive the callback:

1. Ensure Kunobi is registered as the handler for kunobi:// links
2. On macOS, this is registered automatically during installation
3. On Linux, you may need to register the kunobi:// URI scheme manually — check the troubleshooting guide or the feedback channels

Token Refresh Fails

If Kunobi shows an authentication error while you're already signed in, your refresh token may have expired. Sign out and sign in again to resolve this.