Cockpit app

Install and sign in

Platforms and installers for Orkestia Cockpit, how updates arrive, the browser sign-in with PKCE, where the session is stored, chats-only mode, signing out and switching organization

Platforms

Platform	Package	Notes
macOS (Apple silicon, `darwin-aarch64`)	`.app`	Needs macOS 13 or later. Published from a Mac by the team, not by CI
Windows (x64)	Installer	Installs for the current user, no administrator rights needed. If WebView2 is missing, the installer downloads its bootstrapper
Linux (x64)	AppImage and `.deb`

The app is a native shell (Tauri) around the same web interface as the cockpit. It ships a Dock or taskbar badge, a tray icon, system notifications and a local connector for AI tools.

The installers are not on a public download page. They are sent as links that stay valid for seven days, and after the first install the app updates itself. Ask your Orkestia contact or an organization admin for a link.

Updates

The app looks for a newer version when it starts, every 6 hours while it runs, and when you choose Check for Updates… (app menu on macOS, account menu in the sidebar footer, ⌘K, Settings › About). It reads a signed manifest from a private update store and verifies each package against the update key before installing.

What you see	Meaning
Cockpit 0.1.17 is ready with Install and restart and Later	A newer build is waiting. The row sits under the account footer. Later hides this version until a newer one appears
The update sheet	Opens from Install and restart. Shows your version, the publish date and the release notes, then Not now or Install and restart
Installing 0.1.17, a progress bar	Download percent while the size is known, then "Installing… the app will restart"
Update didn't finish	The download or install failed. The message is the updater's own. Close it and try again
Couldn't check for updates with Retry and Later	The background check failed. Shown once; Later keeps it quiet until a check succeeds
No Updates Available dialog	You asked, and you are on the latest version. Background checks never show this

Background checks are quiet: they record what they found and never open a dialog. Only a check you start opens the sheet or a dialog.

On macOS the update is published separately from Windows and Linux. A Mac can see "no update" for a version the other platforms already have. That is expected until the Mac build of that version is published.

Cockpit signs in on the hosted page at auth.orkestia.dev, in your default browser, with the same account as the web apps. Google, Apple and SSO work as they do on the web. The app never sees your password.

The app creates a one-time PKCE code (S256) and a random state, then starts a listener on this computer only (127.0.0.1). It uses port 5190, or 5174 if that one is taken.

Your browser opens the Orkestia sign-in page. When you finish, it returns to http://localhost:5190/auth/callback and shows Signed in. You can close this tab and return to Orkestia Cockpit.

The app checks and exchanges the code

The app compares the returned state with its own, exchanges the code for tokens, and loads who you are and which organization you work in. The listener waits 5 minutes; after that the attempt ends with sign-in timed out.

You are in

You land on Overview. If your account has no organization, or the organization has no active plan, the app opens onboarding instead of the shell.

Where the session lives

The tokens are stored in the operating system's secure store, one entry per computer under the service name dev.orkestia.cockpit:

OS	Store
macOS	Keychain
Windows	Credential Manager
Linux	Secret Service (GNOME Keyring, KWallet and others)

The access token is renewed automatically shortly before it expires (within two minutes). If the platform refuses the refresh, the app signs you out and says Your session expired. Sign in again. A network error during a refresh does not sign you out.

The app uses the same access token as the web cockpit, so anything you can do there you can do here, no more and no less. An organization role (owner, admin, member) decides what each view lets you change.

Chats-only mode

The sign-in screen offers Not an operator? Use app chats only. It opens the app's chat section without a Cockpit account, for people who only need the chat of an app that uses Orkestia.

You see Chats and nothing else: no decisions, agents, runners or Lumen.
The choice is remembered on this computer. The account footer then reads App chats, Not signed in to Cockpit and offers Sign in to Cockpit….
Signing in to Cockpit leaves chats-only mode.

Sign out

File › Sign Out (macOS), Sign Out in the account menu, ⌘K › Sign Out, or Settings › About › Sign Out.

Sign-out leaves the shell first, then clears the stored session, opens the hosted sign-out page in your browser, and asks the platform to revoke the refresh token. The revoke is best effort and gives up after 8 seconds, so a slow network never keeps you signed in.

Switching organization

The organization name at the top of the sidebar opens a menu of every organization you belong to, with your role in each. Choosing one moves this window to it.

Menu state	Meaning
Organizations listed, one checked	The checked one is where this window works
Checking whether switching works…	The app is asking the platform whether it honours a per-window organization
Switching needs a platform update	The platform does not support it yet. The list is shown but other organizations are disabled
⚠ Data shown comes from …	The window's organization and the organization the workflows run in differ. See Troubleshooting
Reload Organizations	Reads your memberships again

After a switch the app says Working in . The web and MCP keep their own organization. The choice applies to this app on this computer; other apps keep theirs. It is remembered across launches. If you are no longer a member of the remembered organization, the app falls back to your account's own active organization.

Closing the window hides it. The app keeps watching for decisions from the tray (menu bar). Quit from the tray menu (Quit Orkestia Cockpit) or from the app menu.
The tray icon has Open Cockpit, New Chat and Quit Orkestia Cockpit. A left click opens the window. On macOS the Dock icon reopens it.
Only one copy runs. Opening the app again brings the existing window forward.
The app registers itself to start with a --background flag, which starts it hidden in the tray. The app has no setting for launch at login, so whether it starts at login depends on how it was installed on your platform.
orkestia-cockpit://open/<kind>/<id> links open the app and show one thing: a decision, session, chat, app or section. Anything else in a link is ignored, and a link only navigates, it never acts. The AI tools use the same links to show you what they refer to.

Next: First run and onboarding.

App infrastructure

What one app uses — CPU, memory, compute, storage, network and the month's metered usage — in the Infrastructure tab of Apps mode

App files, settings and flags

The Files, Settings and Flags tabs of an app in Apps mode — its stored files, its sign-in settings and the on/off switches for its modules and workflows