Skip to main content
Orkestral runs local-first on your machine, so you can use it fully without an account. Signing in to Orkestral Cloud connects the desktop app to your web account so your name and email flow into the app automatically. This page explains how sign in and sign up work, how the callback brings your profile back into the desktop app, and exactly what stays local versus what lives in the cloud.

Local-first by default

Your workspaces, sources, issues, and chats live in ~/.orkestral on disk. No account is required to work.

Cloud connects your profile

Signing in brings your account email and name into the app so greetings, settings, and prompts reflect who you are.

​
What is local versus cloud

The desktop app never receives your access or refresh tokens in its UI layer. Only your email and name cross into the interface. The tokens stay in the background, encrypted at rest.
  • All workspaces, sources (repos and folders), issues, epics, and goals.
  • Your chat history with agents.
  • Your local profile (email and name) in Settings, General.
  • Cloud session tokens, stored encrypted on disk through the operating system secure storage.
When you sign in, Orkestral reads your identity from the signed session, saves the encrypted session, and syncs your local profile to match. Your name is optional: if your web account has no name yet, your existing local name is kept.

​
How sign in works

Orkestral uses the native-app sign in pattern described in RFC 8252. Instead of embedding a login form, the app opens your real browser, you authenticate there, and the result is handed back to the running desktop app. There are two return paths. The app prefers the loopback path because it works the same in development and production. If the loopback listener does not answer, the website falls back to a deep link.
1

You start sign in from the app

The app opens a tiny local listener on 127.0.0.1 (loopback) and then opens https://orkestral.pro/login?next=desktop in your default browser.
2

You authenticate on the web

You sign in or sign up on the Orkestral Cloud website. All credential handling stays in the browser.
3

The web hands tokens back

The website first posts your session to the loopback listener. If that does not respond, it falls back to the orkestral://auth?... deep link (packaged app only).
4

The app verifies and syncs

The app decodes the session to read your user id, email, and name. It saves the encrypted session, syncs your local profile, focuses the main window, and updates the UI.

​
The loopback callback

The loopback path is the primary route and runs in both development and production.
When you start sign in, the app brings up an HTTP listener bound to 127.0.0.1 on a fixed port (38427 by default). The website is built to send your session to this exact address, so the browser and the app meet on the same loopback channel.
The listener answers requests on /auth and reads access_token and refresh_token from the query string. Any other path returns a not found response.
Because the request travels from the secure Cloud origin to 127.0.0.1, the listener sends a permissive cross origin header so your browser is allowed to deliver the response and the website learns the app received it.
The listener stays open for up to five minutes while it waits for your browser. Clicking sign in again refreshes that window. Once a valid session arrives, the listener shuts down right away.
If the loopback listener cannot answer (for example in a packaged app where the listener did not bind), the website falls back to the custom protocol orkestral://auth?....
The packaged app registers itself as the handler for the orkestral:// scheme so the operating system can route the deep link back to the running app.
On macOS in development, the app does not register the protocol. Doing so would point the scheme at the generic Electron binary inside node_modules, and the operating system would launch an empty Electron instead of your running app. In development the loopback path handles the return, and the deep link is reserved for the packaged app.
On Windows and Linux during development, the deep link is registered against the Electron binary plus your project path, and the link is detected from the launch arguments.
A deep link or loopback callback is only accepted when it carries both access_token and refresh_token. A callback missing either token is ignored, and you stay signed out.

​
What happens after you sign in

Once the session is verified, three things happen in the app.

Session saved

Your account id, email, name, and the two tokens are stored encrypted on disk so the session survives restarts.

Profile synced

Your local profile is updated with your email (always) and your name (when present), so the app reflects your account without re-typing.

UI updated

The main window comes to the front and the interface refreshes to show you as signed in.
After signing in, open Settings, General to confirm your email and name. Your name is what agents use in greetings and prompts, so set it here if your web account does not have one.

​
Sign up for a new account

You do not create an account inside the desktop app. Sign up happens on the website during the same flow.
1

Start sign in from the app

Click the Cloud sign in action. The browser opens the Orkestral Cloud login page.
2

Choose to create an account

On the web page, switch to sign up and create your account there.
3

Return to the app

After your account is created and you are signed in on the web, the session is handed back through loopback or the deep link, and the desktop app picks up your new identity.
Because sign up runs in your browser, you get the full web experience for account creation, including any verification steps, before the app ever sees your identity.

​
Sign out

Signing out clears the stored session from the app and marks the app as signed out in the UI. Your local data is untouched: workspaces, sources, issues, and chats all remain on disk in ~/.orkestral. Your local profile name and email in Settings, General also stay as they are.
Signing out only removes the local session. It does not sign you out of the Orkestral Cloud website in your browser. Sign out there separately if you are on a shared machine.

​
Troubleshooting

The loopback listener waits up to five minutes. If too much time passed, return to the app and start sign in again to reopen the listener, then retry in the browser.
The callback only completes when it carries both tokens. Start sign in again from the app so a fresh listener is ready, then complete the login on the web in the same session.
This is the development-on-macOS deep link case. In that setup the loopback path is the one that returns your session. Make sure you started sign in from the running app so the loopback listener is active.

​
What to do next

Set your profile

Confirm your name and email in Settings so agents address you correctly.

Create a workspace

Start organizing your repositories and folders into a workspace.