Canvas and cards

The canvas is an infinite board with a dotted background. Each card has a tab on top with its icon, name and state: “· working” while an agent works and “· waiting for you” when it needs you. The border lights up amber when the agent needs you and green when it finishes.

Step by step

1. Click a card to select it. It lifts a little, gets a light ring and takes the keyboard.
2. The cables between cards are tentacles. Groups show up as islands, with their name on a badge.
3. When the canvas is empty, you see “Empty canvas”: click “New terminal…” or press ⌘TCtrl+Shift+T. You can also bring in sessions already running on a server from the sidebar.

The dark theme is the default. Switch it with the sun or moon at the bottom of the sidebar.

See alsoCard typesAsking for you and DoneAppearance and theme

Everything on the canvas is a card or a drawing. Each type has its own tool in the top bar or a shortcut.

Step by step

1. Terminal: Claude Code, Codex, a Shell or any command, on this computer or on a server. The footer shows the folder (or server:folder) and the microphone. An agent has two faces, terminal or chat: switch with ⌘JCtrl+Shift+J. Badges show “Maestro”, the role or “external”.
2. Note: markdown text, gray by default, with 7 colors. The title follows the first line. A loose .md or .txt on the canvas becomes a note that edits the original file.
3. File: an image, PDF, video, folder or other file, with a preview. Double-click to open it in the system app; “Send to” hands it to an agent.
4. File tree: a folder on your computer or on a server, with the open file, Git and copies.
5. Portal: a browser on the canvas, as desktop or mobile, with your logins.
6. Cloud account: a gcloud account. The icon is green while the session is valid, amber when it's about to expire and red once expired.
7. Draw: an Excalidraw board where you and the linked agents draw.
8. Text: a loose block of text on the canvas.
9. Shapes: rectangle, diamond, ellipse, arrow and line. Arrows and lines stick to cards.
10. Folder: several cards stacked as tabs of a single card.

See alsoNew terminalCreate a noteOpen a file treeOpen a portalThe account cardCreate a DrawFolders

The bar at the top of the canvas creates cards and drawings. With nothing selected, each tool has a letter.

Step by step

1. Click the tool or press its letter: Select V, Hand H (or hold Space), Terminal T, Note N, File tree F, Portal P, Draw X and Text L.
2. Click on the canvas where the card goes, or drag to draw its size. A click without dragging uses the default size.
3. ⌘TCtrl+Shift+T opens “New terminal” directly, without picking a spot.
4. The “Attach files” paperclip picks files that become cards. You can also drag them onto the canvas.
5. The cloud opens the “Cloud accounts” panel (⇧⌘ULeader U).
6. Right-click the Portal globe to open a new portal straight on a shortcut, like Gmail, Google Calendar, Notion or a site of your own.
7. After the tools come the shapes: Rectangle, Diamond, Ellipse, Arrow and Line.
8. Esc goes back to the pointer.

The letters only work with nothing selected, so they never steal what you type in a card.

See alsoShapes and textCanvas tools

Draw rectangles, diamonds, ellipses, arrows and lines and write loose text, like in Excalidraw. Two format bars appear at the top: one for text and one for shapes.

Step by step

1. Pick a shape in the bar or press its letter: Rectangle B or R, Diamond D, Ellipse O or Arrow A. Line has no letter.
2. Drag on the canvas to draw. A click without dragging draws at the default size. With Shift you get squares, circles and lines in 15° steps.
3. Drag an arrow or a line from one card to another: the ends stick to the cards and follow them when they move.
4. Double-click inside a closed shape to write in it.
5. With shapes selected, the format bar changes the stroke color, the fill (“No fill”, “Hatched” or “Filled”, with the fill color), the thickness (thin, medium, thick) and the stroke style (“Solid”, “Dashed”, “Dotted”). With a shape tool active and nothing selected, the same bar applies to the next shapes.
6. To write text, press L and click where you want to write. Double-click a text to edit it; Esc finishes.
7. With a text selected, the text bar picks the font (Aa sans serif, serif or monospaced), the size, from 10 to 96, bold and the color.

An empty shape can only be grabbed by its border. That way, a rectangle drawn around cards leaves the cards clickable.

See alsoToolbarDeleting and closing cards

A click selects a card and gives it the keyboard. You move it by its tab, resize it from any side and can snap a card to its neighbor.

Step by step

1. Click a card to select it. Shift-click adds others to the selection.
2. Drag on empty space to select several with a rectangle. Esc clears the selection.
3. Drag by the tab to move. Cards stop on a 10-point grid.
4. Hold ⌘Ctrl while dragging to use the magnet: the card snaps to one side of its neighbor (or of a row of them) and fills the free space up to the next one, with the edges aligned.
5. Hold ⌥Alt while dragging to duplicate: the copies move and the originals stay.
6. Resize by pulling any side of the card. With ⌘Ctrl, the moving edge snaps to the neighbor's.
7. Drop a card on another card's tabs to put both in a folder.

The mouse wheel scrolls inside a card only when that card is selected. That way, moving the canvas over the cards never gets stuck on one of them.

See alsoFoldersZoom and mouse wheel

Zoom is only a lens: it zooms in and out without changing anything inside the cards. At 100%, text is as sharp as in any regular app, and the zoom stops exactly at 100% when it passes through it.

Step by step

1. Zoom in with ⌘=Ctrl+= and out with ⌘-Ctrl+-, 10% at a time.
2. ⌘0Ctrl+0 frames everything (“Show all”); ⌥⌘0Leader 0 goes back to 100% (“Actual size”).
3. On the trackpad, two fingers move the canvas and pinching zooms. Two fingers with ⌘ or ⌥ (on Windows and Linux, with Alt) zoom too.
4. The mouse wheel follows Settings › General › “Mouse wheel on the canvas”: “Zooms, like pinching” or “Pans the canvas”. On the Mac, with ⌘ or ⌥ the wheel does the other one. On Windows and Linux, in zoom mode Alt pans; in pan mode, Ctrl or Alt zoom.
5. Shift+wheel moves the canvas sideways.
6. To move the canvas, hold Space and drag, drag with the middle mouse button or use the Hand H.
7. When you pass 100% with the wheel, a pinch or the buttons, the zoom stops at 100%. A pinch released near 100% settles on it.

On the Mac, on a regular (non-Retina) monitor, text in terminals, chats and files stays sharp at any zoom, and you don't lose your place while reading.

See alsoThe zoom cornerGeneralMouse and trackpad

In the bottom right corner you find the voice octopus, “Show all” and the zoom. With something selected, the selection buttons show up too.

Step by step

1. Click the octopus to dictate by voice into the selected card.
2. With cards selected, you get “Group” (⌘GCtrl+Shift+G) or “Ungroup” (⇧⌘GLeader G) and “Standard mode for the selection” (⌃⌘↩Leader ↩).
3. “Show all” frames every item (⌘0Ctrl+0).
4. The − and + zoom out and in by 10%. Click the percentage to go back to 100%.

See alsoGroupsStandard modeWhere to dictate

Standard mode fits the cards on screen, ready to read and type, without covering the other cards. One card sits in the middle; two, always side by side; three, one large and two stacked; four, in a 2×2 grid. Do it again and everything goes back to how it was.

Step by step

1. Double-click a card's header (or footer), or ⌘Ctrl-double-click anywhere on it.
2. Or select the card and press ⌃⌘↩Leader ↩. With several selected, the shortcut and the “Standard mode for the selection” button fit them all together.
3. For a whole group, click its name badge and use the same shortcut, or choose “Group standard mode” in the name's menu. Double-clicking the group in the group bar does the same.
4. The first card (the one you clicked, or the group's Maestro) takes the large spot.
5. A terminal or a chat on its own fills the free view. A tree with an open file or a portal as desktop also use the full width.
6. Repeat the gesture to go back. If the view or a card changed in the meantime, the cards stay where they are.
7. Up to 16 cards fit; with more, Octopus uses “Arrange for reading”.

When the cards fit, standard mode stays exactly at 100%, with sharp text. The screen decides how many fit side by side. On a small screen, the zoom backs off a little (down to 75%) to keep text readable; on a large screen, a terminal or chat next to others is never wider than 1400 points, and a card on its own goes up to 1800.

See alsoGroup work tableFocus modeGroup bar

In standard mode for a whole group with 3 cards or more (and something to work on: an agent, a tree with an open file or a portal), Octopus sets up a work table instead of shrinking everything. Nothing gets smaller than you can read.

Step by step

1. Click the group's name badge and press ⌃⌘↩Leader ↩, or double-click the group in the group bar.
2. On the stage, in the middle, goes the card you used last.
3. Next to it on the stage goes its partner: of the cards linked to it, the one you used last. If none was used and it's an agent, the partner is what it works on: a tree with an open file or a portal.
4. On the left, a shelf with what you read now and then: notes, images, PDFs, files. On the right, a column with the tools: shells and trees listing files.
5. Every other agent in the group gets its own table, on the right. Whatever doesn't fit on screen stays next to it on the canvas, one drag away.
6. Repeat the gesture to go back to how it was.

If you haven't used any card in the group yet, the one that needs you goes to the stage; if none does, the one that is working; otherwise, the Maestro.

See alsoStandard modeGroups

Focus mode lifts a card into a panel over the canvas, which blurs behind it. Dragged to the edge of the window, the panel becomes a fixed column, and the canvas keeps moving underneath.

Step by step

1. Select the card and press ⇧⌘↩Ctrl+Shift+↩, or click “Focus mode” in the card's bar or in its menu.
2. Where the card was, the canvas shows an outline that says “Lifted”.
3. Drag the panel by its header to the left or right edge of the window: it docks there as a column as tall as the window, and its spot on the canvas now says “Docked”.
4. To go back, press Esc (outside the terminal), click the background, double-click the header or use “Return to canvas” in the card's menu.
5. Only one card is lifted in the middle at a time: lifting another one returns the first.

The panel shows the card at 100%, whatever the canvas zoom, with sharp text.

See alsoStandard mode

You can get around the canvas without the mouse: from card to card, along the cables, by number or by group. The card you land on is selected and has the keyboard.

Step by step

1. ⌃⌘←Leader ← (and the other arrows) goes to the nearest card in that direction. The view slides at the same zoom, and the card keeps its size.
2. On Windows and Linux, after Leader + arrow, the arrows alone keep moving until Esc or ↩.
3. ⌃⇥Ctrl+Tab and ⌃⇧⇥Ctrl+Shift+Tab select the next and the previous one, in reading order (top to bottom, left to right).
4. ⌥⌘→Leader . follows a cable to a linked card; ⌥⌘←Leader , goes back. The same key always takes you to the same neighbor.
5. ⌘1Ctrl+1 to ⌘9Ctrl+9 open terminals 1 to 9, in reading order, ready to type.
6. ⌃⌘1Alt+1 to ⌃⌘9Alt+9 go to groups 1 to 9 in the group bar.
7. ⌘\Leader E shows the whole selected card, up to 100%, with the keyboard on it (“Focus” in the card's menu does the same). ⌥⌘\Leader Z frames the whole selection.

See alsoThe Leader key (Windows and Linux)Navigate

A tentacle links two cards. Linked agents talk to each other and use the linked cards: they read and write the note, control the portal, run commands in the shell, draw in the Draw. Who linked whom doesn't matter: the conversation goes both ways.

Step by step

1. Select a card and drag the link button from the bar to the other card. Or click the button and then the other card.
2. From the keyboard: select the card, press ⌘LCtrl+Shift+L and click the target.
3. The number on the link button counts the card's cables. A cable turns coral when one of its cards is selected.
4. To unlink, click the cable and press Delete, or right-click it and choose “Unlink”. The card's menu also has “Link to ▸” and “Unlink from ▸”, with “All”.
5. Portal, Draw and cloud account only link to terminals: it's the terminal's agent that uses them. A file tree only links to a terminal on the same machine.
6. A new card with no group joins the group of the card you link it to; linked to two groups, it stays without a group. What the Maestro creates joins its group, and a duplicated terminal joins the original's group.

See alsoAgents that talk over cablesGroupsKeyboard navigation

A group gathers cards into an island with a name. You select and move the group only by its name badge; clicking a card selects only that card.

Step by step

1. Select the cards and press ⌘GCtrl+Shift+G, or click “Group” in the zoom corner.
2. Click the name badge to select the whole group; drag the badge to move everything together.
3. Double-click the badge to rename the group.
4. With the group selected by its name, the bar shows the name, “N cards”, “Save group” and “Move the group to another workspace”. It works even for a group with a single card.
5. Right-click the badge to open the group's menu.
6. To undo the group, select it and press ⇧⌘GLeader G, or use “Ungroup” in the menu.
7. When you move the view to another group, whatever was selected outside it is no longer selected.

Groups also form on their own through cables: a new card linked to a group joins it.

See alsoGroup menuNo groupGroup barSave a group

Right-clicking the group's name badge brings together what you can do with the whole group.

Step by step

1. Right-click the name badge.
2. “Save group…” keeps the group in the workspace's saved groups. If it came from a saved group, the item says which one it will update.
3. “Move group to ▸” takes the whole group, with its sessions running, to another workspace.
4. “Gather into folder” shows up with 2 cards or more; if the group is already a folder, the item is “Spread out”.

See alsoGroupsMoving cards and groups between workspaces

Cards that aren't in any group show up together as “No group”: last in the group bar, in the sidebar's “Groups” folder and in Tabs.

Step by step

1. Click “No group” in the group bar (or in the “Groups” folder) to take the view to those cards, without selecting any.
2. Double-clicking puts those cards in standard mode.
3. In Tabs, “No group” shows those cards' tabs. To send a card there, use “Remove from group” or “Move to group ▸ › No group” in the tab's menu.
4. “No group” isn't a real group: it can't be saved or moved to another workspace as a group.

See alsoGroup barGroups without the canvas

A folder stacks several cards as tabs of a single card. Tabs that aren't open keep running, with their alerts. A folder never creates a group: it stays in the open card's group, or in none.

Step by step

1. Select two cards or more and press ⌥⌘GLeader P, or click “Gather into folder” in the selection bar. The card you used last stays open.
2. Or drag a card and drop it on another card's tabs.
3. Click a tab to show that card.
4. Drag a tab out to take the card out of the folder, or use “Take out of folder” in the card's menu.
5. The “+” after the tabs creates a new card in the folder: a terminal like the tab's (same server, folder and program), “Shell in the same folder” or “Note”.
6. To undo it, select the folder and press ⌥⌘GLeader P, or click “Spread out”: the cards go back where they were, all selected.

When you drag with the magnet (⌘ on the Mac, Ctrl on Windows and Linux), the card doesn't go into another card's tabs. Deleting a selected folder closes all its tabs; the “×” on a tab closes only that card.

See alsoSelect, move and resize

“Arrange” puts the selection in an aligned grid. “Arrange for reading” gives each card its reading size at 100%. Cards in the way don't move: the block goes to a free space nearby.

Step by step

1. Select the cards and press ⇧⌘TLeader T: they become a grid. Notes, attachments, the Maestro and whatever is linked to a terminal get their own spots.
2. Press it again, with the same selection, to arrange for reading.
3. Or press ⌥⇧⌘TLeader R to go straight to reading. Each card gets its reading size at 100% (a terminal, the size of the view). With several, the view shows them all; with just one, it sits at 100% in the middle of the view.
4. With the mouse: “Arrange for reading” in the card's menu and, with several selected, “Arrange”.

See alsoAlignStandard mode

With several cards selected, “Align” lines their edges up or spreads the space between them evenly.

Step by step

1. Select two cards or more.
2. Right-click one of them and open “Align ▸”.
3. On the Mac, the same is in the Canvas › Align menu. On Windows and Linux, in the action palette —Ctrl+Shift+P, as “Align › …”.

See alsoArrange and Arrange for reading

Blur hides a card's contents behind a closed eye. Use it to share your screen without showing what's in the card.

Step by step

1. Right-click the card and choose “Blur”. With several selected, it applies to all of them.
2. To show it again, click the eye (“Show contents”) or choose “Unblur”.
3. On the Mac, also from the Canvas › “Blur / Unblur” menu. On Windows and Linux, from the action palette —Ctrl+Shift+P.

Canvas steps can be undone and redone. Copied cards bring along the cables between them.

Step by step

1. ⌘ZCtrl+Z undoes a canvas step; ⇧⌘ZCtrl+Shift+Z or Ctrl+Y redoes it.
2. ⌘CCtrl+C copies the selected cards, with the cables between them. ⌘VCtrl+V pastes them in the middle of the view; pasted terminals open new sessions.
3. With an image or files copied (a screenshot, an image from a web page, files copied in Finder or, on Windows and Linux, in the file manager), ⌘VCtrl+V on the canvas creates cards in the middle of the view.
4. Right after moving cards to another workspace, ⌘ZCtrl+Z undoes the move while the notice is showing.
5. On Windows and Linux, right-clicking empty canvas has “Undo”, “Redo” and “Paste”.

In a terminal or a text field, these keys belong to the terminal or the field; on the canvas, they belong to the canvas.

See alsoMoving cards and groups between workspaces

Drag files from Finder (or from your file manager) into Octopus. Where you drop them decides what happens.

Step by step

1. Drop on empty canvas: each file becomes a card. A .md or .txt becomes a note that edits the original file.
2. Drop on a terminal: the path is typed. If the terminal runs on a server, the file is uploaded there first.
3. Drop on a chat: it becomes an attachment to the message.
4. Drop on a Draw: the image goes into the drawing.
5. Drag from the file tree to the canvas: files become cards and folders become trees. On a terminal, the path is typed.
6. Double-click a file card to open it in the system app.

See alsoDrop and paste filesPasting images and files into the terminalCopy, paste and undo

Delete closes what is selected. Terminals go to the workspace's history, to reopen in the same place; nothing disappears without your confirmation.

Step by step

1. Select and press Delete (or Backspace), ⌘WCtrl+Shift+W, or click “Delete” in the bar. The “×” on the card's tab does the same for that card.
2. Idle terminals go straight to history, with “Undo” in the notice.
3. If an agent is still working, Octopus asks: “Archive and stop”, “Archive and let them finish”, “Delete permanently” or “Cancel”. Shells don't stay in history: once closed, they disappear from the canvas, and “let them finish” keeps the session in the server's list.
4. Notes go to the Trash, and a portal clears its cookies and site data. Octopus asks first.
5. Shapes and text go right away, without asking.
6. With a cable selected, Delete unlinks the cable.

See alsoClosing is archivingTentacles (cables)

With something selected, a bar appears below the toolbar with what you can do there. It changes with what you selected.

Step by step

1. A terminal: “Rename”, link (with the number of cables), “View as chat” or “View as terminal” (⌘JCtrl+Shift+J) or “Convert”, “Duplicate” (⌘DCtrl+Shift+D), the folder's file tree (⇧⌘ECtrl+Shift+E), “Shell beside” (⌥⌘TLeader S), the editor (VS Code or Cursor; on a server, through Remote-SSH), “Make Maestro”, the folder, “Focus mode”, “Reconnect” and “Delete”.
2. A group selected by its name: the name, “N cards”, “Save group”, “Move the group to another workspace”, the folder, “Standard mode for the selection”, “Reconnect” and “Delete”.
3. Several cards: “N selected”, “Move the cards to another workspace”, “Gather into folder”, “Standard mode for the selection”, “Reconnect” and “Delete”.
4. A note, a text or shapes show their format bars.

See alsoCard menuShell besideTurning on the Maestro

Right-clicking a card opens everything it does, with the same icons as the bar. With several selected, the menu acts on all of them.

Step by step

1. Right-click the card.
2. The items change with the type. An agent opened outside Octopus has “Convert…”; a shell has “Agent commands ▸” (Free, Ask, Blocked); a file, “Send to ▸”; a note, “Format ▸”; a portal, “Reload” and “View as mobile” or “View as desktop”.
3. With several selected, you also get “Standard mode”, “Arrange”, “Align ▸” and “Move N cards to workspace ▸”.
4. “Focus” shows the whole card, with the keyboard on it.

See alsoSelection barTab menuThe “Agent commands” lockRole… by hand