Skip to main content
Cortex Code runs in your browser, in the Cortex desktop app and in the Cortex CLI. The desktop app is the surface that can put a session on a machine you own: next to Cloud it offers This PC, which is the app’s label for your own computer, and SSH, which is a remote host you have registered. In the browser a session runs on Cloud, plus a registered team runner when the deployment has one, and nothing else. Two things in Code are called Desktop, and this page is about one of them. The Cortex desktop app is the application you install and sign into. A session’s Desktop tab is something else entirely: it carries the badge Soon and there is nothing behind it, because a Cloud guest is headless and there is no screen inside a Code runtime. Everything below is about the application.

​
Where each runtime is offered

Web Code is Cloud-only on purpose: the browser has no way to run tools on your disk. For the same reason, the browser’s Machines page lists Cloud occupancy and team runners only, and never your desktop hosts. A session binds one runtime per turn and there is no quiet fallback: if the runtime you chose is not usable, the turn refuses and tells you what to do rather than running somewhere else.

​
Screens in the desktop app

The app is not a wrapper around this site. It has its own screens, and they are the same vocabulary you already know from the browser:
  • A first-launch splash, then Code Home with the composer.
  • An Inbox of your sessions, and a session detail with its plan, its permission prompts, its terminal and its changes.
  • Automations, Review, Usage and Notifications.
  • Settings, which holds Providers, workspace defaults and a remote host, with Integrations under it.
  • Connect a server, which is where a remote host is registered.
Those are screens inside the application, not pages on this site. Downloading and updating the app is covered under the desktop app.

​
Run a session on This PC

1

Choose This PC on Code Home

The runtime row on the desktop app offers Cloud, This PC and SSH. Picking This PC means the tools a turn calls act on a folder you nominate.
2

Pick the folder in the native folder picker

The app opens your operating system’s own folder picker. There is no workspace-name field to fill in, and pressing Cancel leaves no session behind and invents no path: nothing falls back to whatever directory the app happens to be running in.
3

Work from the folder's name

Afterwards the session identifies the folder by its name rather than its full path, and it uses that name exactly as it is, trailing spaces included.
A This PC start never silently becomes a Cloud session. If the host behind a session goes away, the follow-up box is disabled and says so: This session runs on This PC, and no host is connected. Pair one from the Host pane and the composer comes back. This PC is not a Cortex Bot host. It is Code’s own local runtime, and the SSH screens never borrow that name either: SSH stays SSH.

​
Run a session over SSH

SSH runs the tools on a machine you already operate. There is no screen on that host, it is a shell, which makes it a good fit for a build box or a server with access your laptop does not have. Register one with Connect a server in the desktop app: keys stay server-side, and the browser never receives SSH keys or host keys. See SSH hosts for the rest.
Treat local and SSH execution as unfinished. The desktop app offers the choice and the screens described here, but Cortex does not promise a complete run of the tools on This PC or on an SSH host today. When you need a run you can rely on end to end, use Cloud. See Cloud runtimes.

​
Approvals on a desktop session

Nothing about the desktop app makes a turn quieter. A command that needs a decision stops the turn and asks, with Allow, Always and Deny, and file writes and shell commands are never silent. The two gates stay separate here exactly as they do in the browser. A command is decided on the prompt; a file write is not on that rail at all, it waits under Changes for a person to approve it, and a session-level always never covers a write. There is no undo, no checkpoint and no revert anywhere in Code, so a pending change is the moment to refuse. See Permissions and approvals and Changes and diffs.

​
Signed out, and where credentials live

Signed out, desktop Code Home stays visible: This PC, SSH and Cloud are still shown, and so are Ask, Plan and Agent. Pressing start raises the sign-in dialog instead of failing. Automations, Review, Usage, Cloud and SSH also stay visible, and stay locked. Provider credentials are entered under Settings → Providers, and the form never reads a key back to you. Code has no Secrets destination on any surface, and nothing in Code asks you to paste a token.

​
The host status the app reports

The app shows one status for the host behind your work, and it is worth knowing what each one means. The order is deliberate. A session waiting on Allow, Always or Deny is shown ahead of whether your own machine is up, then a running Cloud session, then a failed wake, then connecting, and only then connected or Cloud only. That is why a session running in Cortex cloud reads Cloud session running even while the local side is down: what matters is the work, not the laptop.

​
The same choice from the terminal

The Cortex CLI drives the same sessions and makes the same runtime choice, on Cloud by default with This PC and SSH by opt-in. Both of those need an already connected Code session; the CLI will not create one on the fly and will not substitute Cloud without telling you. The switches themselves are documented with the CLI, in environment variables, and the vocabulary map between Code words and CLI words is on Code in the terminal.