Windows and Linux: what changes

Octopus runs on Windows 10 and 11 (x64) and on Linux (Ubuntu 22.04 or later and Debian 12, x64 and arm64). On the Mac, it needs macOS 26 (Tahoe) or later, on Apple Silicon or Intel.

Step by step

1. Windows: Windows 10 or 11, x64.
2. Linux: Ubuntu 22.04 or later, or Debian 12, on x64 or arm64. For other distributions, use the AppImage.
3. The agents are your own: Claude Code and Codex, with your account or your API key.
4. The same license works on all three systems, on up to 2 computers.

See alsoThree systems, two computersInstall on WindowsInstall on Linux

The Windows installer installs Octopus for your user only, without asking for administrator rights. Since the installer doesn't have a Windows code-signing certificate, SmartScreen may show a warning the first time.

Step by step

1. Download Octopus for Windows from the website.
2. Open the installer.
3. If you see “Windows protected your PC”, click “More info” and then “Run anyway”.
4. Octopus opens first-run setup. To open it again later, use “Set Up This Computer…” in the action palette (Ctrl+Shift+P).

Later updates come on their own and are signed by Octopus.

See alsoUpdatesFirst-run setup

On Linux there are two packages: the .deb, for Ubuntu and Debian, and the AppImage, for other distributions. Both exist for x64 and arm64.

Step by step

1. Download the package for your architecture (x64 or arm64) from the website.
2. With the .deb: open the file in the software center or, in the terminal, in the download folder, run sudo apt install ./ followed by the .deb file's name. The package already includes tmux, which keeps this computer's sessions.
3. With the AppImage: in the file manager, right-click › Properties › Permissions and turn on the option to run it as a program (or, in the terminal, chmod +x and the file's name). Then double-click to open it.
4. Octopus opens first-run setup. To open it again, use “Set Up This Computer…” in the action palette (Ctrl+Shift+P).

Updates arrive on their own: with the .deb, installing asks for the administrator password; with the AppImage, the file itself is replaced.

See alsoUpdates

On Windows and Linux, the Mac's ⌘ becomes Ctrl. Since Ctrl with a letter belongs to the terminal, the app's shortcuts use Ctrl+Shift; the ones that still collide go to the Leader key. Octopus never uses Ctrl+Alt (it's AltGr on many keyboards) or the Windows key.

Step by step

1. The app's shortcuts are generally Ctrl+Shift and the same letter as on the Mac: New terminal ⌘TCtrl+Shift+T, sidebar ⌘SCtrl+Shift+S, history ⌘YCtrl+Shift+Y.
2. In the terminal, copy, paste and select all are ⌘CCtrl+Shift+C, ⌘VCtrl+Shift+V and ⌘ACtrl+Shift+A. Ctrl+Insert and Shift+Insert also work. On Windows, Ctrl+V pastes; on Linux, Ctrl+V stays with the program in the terminal (vim, the shell, Claude Code's image pasting).
3. Groups 1 to 9 are ⌃⌘1–9Alt+1–9; terminals 1 to 9, ⌘1–9Ctrl+1–9.
4. Next and previous workspace: ⌘↓Ctrl+Shift+PgDn and ⌘↑Ctrl+Shift+PgUp (also Ctrl+Shift+] and Ctrl+Shift+[). To go to workspace N, tap Ctrl twice and the number.
5. Quitting Octopus is ⌘QCtrl+Shift+Q. Full screen is F11 (on the Mac, the window's green button).
6. Keys work by their position on the keyboard, not by the letter printed on them: the shortcuts work the same on any layout.

The full table, side by side, is on the shortcuts page.

See alsoGeneralThe Leader key

Leader is Ctrl+Shift+Space. You press and release it, then press a single key. It holds the shortcuts that, as Ctrl+Shift+letter, would collide with another app shortcut, with the terminal or with the system.

Step by step

1. Press Ctrl+Shift+Space and release. A hint shows up on screen for a second and a half.
2. Press the action's key, for example D for a new note or ↩ for standard mode.
3. To give up, press Esc or wait for the hint to go away.

The hint only shows J when someone needs you.

See alsoNavigation modeThe Leader key (Windows and Linux)

Leader with an arrow goes to the neighboring card in that direction and leaves you in navigation mode: the arrows alone keep moving from card to card, until Esc or ↩.

Step by step

1. Press Ctrl+Shift+Space and an arrow. The nearest card in that direction gets selected and gets the keyboard.
2. Keep going with just the arrows: each one takes you to the next card. The view glides at the same zoom.
3. In this mode, . and , follow and go back along the card's connection (like Leader . and Leader ,).
4. Press ↩ to stay on the card and type in it, or Esc to leave the mode.

In Tabs, Leader with an arrow goes to the neighboring pane of a split, without entering the mode: the arrows that follow go back to the terminal.

See alsoKeyboard navigationSplitting tabs

Windows and Linux don't have the Mac's menu bar. Instead, the Ctrl+Shift+P palette finds any action by name and shows each one's key.

Step by step

1. Press Ctrl+Shift+P. The field says “Search for an action”.
2. Type part of the name, like “note”, “arrange” or “updates”. The search uses the language of the app.
3. Use ↑ and ↓ to choose and ↩ to run. Esc closes it.
4. Besides the actions with keys, the palette has “Go to workspace X”, “Group: X”, “Align › …”, “Appearance: Light / Dark”, the canvas's “Undo” and “Redo”, “New server…”, “New account”, “Save group…”, “Set Up This Computer…” and “Check for Updates…”.

The palette is the best way to learn the keys: each action shows its own on the right.

See alsoThe Leader keyWindows and Linux only

Closing the window hides Octopus in the system tray, and it keeps running. The window has the Mac's three round buttons at the top of the sidebar.

Step by step

1. Close the window: Octopus goes to the tray, with alerts, the agents' watch and Keep awake still running.
2. Right-click the tray icon (on Windows, a single click opens the window) to “Open Octopus”, change Keep awake or “Quit Octopus”.
3. On a Linux without a tray (GNOME without the AppIndicator extension), Octopus tells you when you close the window: open it again from the applications menu.
4. To move the window, drag it by the top of the sidebar or by the empty strip at the top of the canvas. Double-clicking that strip maximizes it.
5. F11 puts the window in full screen. On the Mac, full screen is the window's green button.

With the window closed, portals don't work: open the window for an agent to use a portal.

See alsoKeep running when the window is closedKeep awake in the tray

Light mode removes the blur behind focus mode and the animations of the cards and the view. It's meant for slower computers and remote desktop.

Step by step

1. Open Settings (Ctrl+,) › General.
2. Under Performance, turn on “Light mode”.

See alsoGeneral

How many agents need you shows on the Octopus icon: in the Windows taskbar and in the Linux launcher. Alerts arrive as system notifications.

Step by step

1. Leave Settings › Alerts › the number on the icon turned on.
2. When an agent asks for you or finishes, the number shows on the icon and the system notification tells you.
3. Click the notification to open the card.

See alsoWhere the alert shows up

Octopus builds the right-click menus that the system provides on the Mac: in a text field, on selected text, on a portal's page and on empty canvas.

Step by step

1. In a text field (a note, the filter, a portal's address, a panel): Cut, Copy, Paste and Select all.
2. On selected text outside a field (the chat, the file viewer, a panel): Copy.
3. On a portal's page: “Open link” and “Copy link” on a link, “Copy image” on an image, and Back, Forward and Reload on the rest of the page.
4. On empty canvas: Undo, Redo and Paste.

See alsoPortal barCopy, paste and undo

An address or a file path in the terminal lights up when you hold Ctrl and opens with Ctrl+click. On Linux, the middle button pastes the selected text, as in the rest of the system.

Step by step

1. Hold Ctrl and hover over an address or a path in the terminal: it lights up.
2. Ctrl+click opens the address in the browser or the file in the system's app. Links that programs mark in the terminal open the same way.
3. On Linux, select some text and click the middle button, without moving, in a terminal: the text is pasted there.

On the Mac, ⌘-click opens links.

See alsoPasting images and files into the terminal

On Windows, this computer's terminals live in an Octopus service; on Linux, in tmux, as on the Mac. Closing the app or updating doesn't kill any terminal. On servers, sessions live in tmux, as always.

Step by step

1. Open terminals and agents on this computer as usual.
2. Quit Octopus or restart to update: the terminals keep running and come back when the app opens.
3. On Windows, Shell opens PowerShell 7 if it's installed; otherwise, Windows PowerShell.
4. On Linux, tmux comes with the .deb. If it's missing, Octopus offers “Install tmux”.

See alsoSessions that don't drop

Almost everything is the same on all three systems. The list below shows the little that changes, so you don't look for something that doesn't exist on yours.

Step by step

1. Mac only: the menu bar (with “Set Up This Mac…”, “Check for Updates…” and the Edit and Window menus) and the “About Octopus” window.
2. Mac only: the number on the Dock, Octopus moving itself to Applications on first use, and the closed lid with the administrator password, with “Restore sleep”.
3. Mac only: the system's Quick Look and “Show in Finder” (on Windows and Linux, Octopus has its own preview and “Show in folder”), and dragging a server file from the tree to Finder to download it.
4. Mac only: sharp text at any zoom on non-Retina displays, and ⌥ with the wheel zooming the canvas even over a selected Draw.
5. Windows and Linux only: the action palette (Ctrl+Shift+P), the Leader key and navigation mode, the tray, Light mode, F11, the text and page menus built by Octopus, right-clicking empty canvas, the closed lid's “Test on this Linux” and the update notice with “Later” and “Restart”.
6. Some names change a little too: “This Mac” becomes “This computer”, and “Same as the Mac” becomes “Same as the system” (in the Windows sidebar globe, “Same as Windows”).

See alsoWith the lid closedUpdatesQuick Look