The window
First launch
- With no daemon running, the window opens one project with one tab and one pane running your shell.
- Start it in a directory other than your home directory, and that directory becomes the project, named after it.
- Start it from a launcher and it opens in your home directory (on a Mac,
/). The project has no root and gets a generated two-word name such asamber-fjord.
- With a daemon already running, the window shows what the daemon has.
- The window opens centred, at the size it had last time, or 1200×800 the first time.
- Each
insensicalprocess has one window. Two processes give you two windows on the same daemon: see Two windows.
Parts
- Sidebar, on the left: a row of tools, the find field, then the project tree under each machine's heading. Shown with
tabs = "sidebar". - Top bar, shown with
tabs = "top": the sidebar button, then where you are (the project's tile and name, a slash, the project's tabs), then+for a new tab. On the right: a settings problem, the update notice, the notice about agents that don't report yet (Agents), the count of panes that need you, and a count and switch for floating panes when the tab has any. - The tab's area: tiled panes with dividers, and floating panes above them.
- Dock, at the bottom, only while the tab has minimized panes.
With tabs down the side, the top bar's things are at the top and bottom of the sidebar.
Tabs run along the top or down the side, never both. The tabs setting chooses. Ctrl+Shift+B hides them, and shows them again in the same place.
tabs | What you get |
|---|---|
"sidebar" (default) | The sidebar lists every tab of every project. Its head has the button that hides it, All and Activity, the bell, the palette and the settings; notices are at its bottom. No top bar. |
"top" | The top bar shows the current project's tabs only. No sidebar. |
| Hidden | Panes get the whole window. Ctrl+Shift+A still goes to the pane that needs you and the palette still lists them. The window opens with tabs hidden next time. |
With nothing open
A project with no tabs shows its name and "Nothing is running here.", over four ways on, each with its keys: New tab, New project, Command palette and Show every key. Click one or press its keys. A window with no project shows the same under the name insensical, and a tab whose panes are all minimized says so over the same four. A setting that couldn't be used shows in red at the foot of the sidebar, or in the top bar; click it to see every such problem.
What resizes terminals and what does not
Terminals resize when their room changes: showing or hiding the sidebar, dragging its edge, the dock appearing, hiding pane headers, or changing sidebar, pane-header, density or pane-gap. Things that float over them (the palette, the overview, search, zoom, the leader's panel, the restart question) don't.
What the window does not remember
The window remembers its size, whether tabs were hidden, the sidebar's width, which projects and tabs you folded or unfolded. It doesn't remember its position, and a new window always opens with its keys unlocked.
Two windows
A pane has one size, so a pane is the size that fits the window you used last. The same goes for a window and isc attach.
- Click or switch to a window and the panes it shows take its size. The other window keeps showing them at that size.
- A pane sized by another window has a "Sized elsewhere" mark in its header. Press it to size the pane for this window.
- A browser page on a wide screen takes the sizes by itself: see "On a wide screen".
- If a pane is larger than its space you see its foot, where the cursor is. Hold Shift and turn the wheel to move across it, or Alt and the wheel to move up and down.
Other machines in the window
One window shows this computer's projects and those of every machine you've added. A pane on another machine works like any other and keeps running if you close the window or the connection drops. It all goes through your own ssh: see Other machines, over ssh.
Adding a machine. Press "Add a machine" under the projects in the sidebar. "Add a machine" in the palette and "Add Remote Host" in the settings sheet do the same.
- Under the field, pick
Your tailnet(your tailnet's machines, those that are on first) orssh configuration(the names in~/.ssh/config). It opens onYour tailnetwhen your tailnet has other machines. - Choose a machine, or type to narrow the list. Anything else you type goes to
sshas it is: a host, oruser@host.Tabmoves between the field and the two tabs, Left and Right switch tabs, Up and Down move through the list. - Press Enter, or
Add. The dialog checks the machine, asisc host checkdoes, and a failing line says what to do. - A machine that's ready is added at once, and its projects appear in the sidebar.
- If
sshhas a question, pressAnswer. That covers a new host, a key or password, and a Tailscale sign-in. It opens a tab on this computer runningisc host answerfor that machine, where you answersshitself; insensical never sees what you type. The button is also under the machine's name in the sidebar and in Remote Hosts. A changed host key has noAnswer: its words say what to find out first. - If insensical is missing or older, one button brings it there, like "Put insensical 0.3.0 on atlas". It does what
isc host putdoes. Where a package or Homebrew owns insensical there, the dialog gives you the command to run on that machine instead. A copy built from source sends itself to a Linux machine, even one with the same version.
In the sidebar, each machine is a heading over its projects: "This computer" first, then the others in your settings' order.
- A heading has the machine's picture, its name and the link's mark. Folded, it counts the panes that need you. Press it to fold the machine. Under the pointer, its
+starts a new project there. A machine with nothing open says "Nothing open there", with "New Project". - The link's mark is three bars: three under 60 ms round trip, two under 200 ms, one beyond. Point at it for the figure. While the machine is out of reach it's a cut plug, and pointing says why.
- A machine with another version of insensical says so under its heading, as in "atlas has insensical 0.2.1, and this computer has 0.3.0". "Update it" offers to put this version there. If the machine has the newer one, update this computer, then press "Try again".
- The filter, going to the pane that needs you, "Next project" and "Previous project" all cover every machine. The overview groups projects under each machine, and the palette says which machine a pane is on.
Which machine you're typing into. A pane on another machine shows the machine's chip (its picture and name) in its header. In a narrow pane the chip is the picture alone.
A machine marked careful has a chip filled in the waiting colour, and a paste of more than one line there asks first, whatever the program asked for. See Pasting.
One machine is in front at a time. Keys and commands go to the machine whose pane, tab or project you last went to.
- A pane, tab or project stays on the machine that runs it.
- "New project" asks which machine once there's more than one.
Alt+Mgoes to the next, and the directories offered are that machine's. - A request meant for one machine is never done on another. If a machine can't be asked, nothing happens and a line says so. Another machine can tell you a pane needs you, but can't take the keyboard.
When the link is lost,
- the machine's panes keep what they last showed, dimmed, with a line at their foot: "Link to atlas lost · trying again";
- nothing you type there is sent, or kept for later. The line beats once so you know the key wasn't taken, and commands that act on that machine do the same. Nothing you typed reaches an agent when the network returns;
- it retries by itself, and coming back to the window retries at once;
- when it's back, the panes say "Connected" for a second. What ran there never noticed.
Settings. The Remote Hosts page of the settings sheet has one card per machine. Press a folded card's row to open it. Open, a card has:
| Control | What it does |
|---|---|
| Icon | A picture of its kind: server, laptop, desktop, mini PC, NAS, board (a small computer such as a Raspberry Pi), container or cloud |
| careful | On or off |
Check | Meets the machine again, as adding it did |
| Pencil | Renames it in its row: Enter keeps, Escape leaves |
Forget | Forgets it. What runs there runs on, and adding it again finds it. |
From the keyboard, Up and Down go between machines and "Add Remote Host", Left and Right go along a machine's controls, and Enter presses the marked one.
The settings a server reads (the shell, scrollback, notifications and so on) and the agents' hooks belong to each machine. In Hub, Terminal, Notifications and Agents, a chooser at the top right says whose you're looking at, and Alt+M goes to the next. Everything else on the sheet is this window's.
Limits:
- A pane or project can't be moved between machines, and two machines' panes can't be shown side by side.
- The interface in a terminal shows one machine at a time. A careful machine is marked in the top row, and a multi-line paste asks first.
- In "Go to a machine", a machine
sshhas a question for saysssh askson its row. Pressaand a tab opens on this computer runningisc host answerfor it. A machine not reached for another reason says why, andadoes nothing there.
When this computer's server stops, only its part of the window says so: its heading gets the struck-through mark and "its server has stopped", and its panes are gone until it starts. Other machines carry on. Press the heading for the way to start it again.
Appearance
- Fonts. The UI uses Inter at 13 pixels, whatever
font-sizeis.interface-fontnames another. If you name the terminal's font, the UI uses it too. - A program is shown as a tile: its own mark (Claude's, Neovim's, Docker's and so on) on a small glossy card in the program's colours, so you can find a pane by colour. Programs without a mark get a terminal's. Tiles appear in the sidebar, pane header, tab strip, dock, overview and palette.
- A tab shows its panes' tiles as a deck: the one that has or last had the keyboard in front, up to two more smaller behind it. Floating and minimized panes count.
- The head of the sidebar has the bell, which counts what finished and lists it when you press it, the command palette (
⌘) and Settings. "This computer" heads the list, even with no other machine, and the+at its right end starts a new project. Show every key and the overview of every tab are in the palette. With the sidebar hidden, Settings, Show every key and the overview are at the right end of the top bar. - A pane, a tab or a project has a menu of what you can do to it: right-click it, or press its
⋯(a row of the sidebar under the pointer, a pane's header). Renaming, clearing, sharing and sleeping a row are there. A pane's menu has its arrangements as a row of signs: split right or down, float, minimize and fill the tab. A key is shown beside a row only for the pane, tab or project in front, since that's the one the key acts on. - Menus take Up and Down, Home and End, Enter, Escape, and a letter to jump to the next row that begins with it.
density = "comfortable"(default) draws each pane as a rounded card with space around it."compact"puts panes edge to edge with a hairline between them.pane-gapsets the space between panes, 0 to 40 pixels. Without it, the gap is 12 when comfortable and 0 when compact. Panes stay 6 pixels from the window's edges whatever the gap, or touch them when compact.- The focused pane has an accent border. Unfocused panes aren't dimmed.
- Motion is small. Sheets and notices fade in, a pane you float or bring back clears from a light wash, a cursor blinks and a working mark turns.
motion = "off"stops all of it."system"(default) follows the desktop's reduced-motion setting, and on macOS Reduce Motion. - A state is never shown by colour alone: each has a mark and a word.
- Screen readers hear the window's chrome: buttons by what they do, tabs, the sidebar as a tree, switches, menus, and each sheet and question by name. Terminal content isn't exposed.
- The keyboard in a sheet or a question.
TabandShift+Tabgo through its controls and round, never out to what's behind.SpaceorEnterpresses the control with the ring, andEscapecloses. When it closes, the keys return to where they were.