Tabs on other machines

A tab on a server over your own ssh, whose shells stay there when the connection drops, and taking the agent into a shell you reached yourself.

Two ways to work on another machine

A tab on another machinessh in an ordinary tab, with the agent taken in
How≡ menu → New tab on another machine…type ssh (or sudo -s, docker exec…) as usual, then click take the agent in
Where the shells liveon the other machine, kept by Astrum's program therein the connection: when it drops, they end
A dropped connectionloses nothing; Astrum reconnects by itselfends the shell there
Splitsopen on the same machineopen on this machine
The agent's toolsall of them: commands, and reading, searching and changing files with a diff to approvethe shell only
Needs on the other machinea build of Astrum there (Astrum offers to put one there)bash, zsh or fish; nothing installed

The first is the fuller way, wherever there is a build of Astrum for the other machine. The second works almost anywhere you can reach a shell.

Opening a tab on another machine

Do thisWith the mouseWith the keyboard
New tab on another machine≡ menu → New tab on another machine…Ctrl+B R, or /ssh host in the agent panel

Astrum asks for the machine, as you would name it to ssh:

web-3
deploy@web-3
-p 2222 web-3
-J jump web-3

A name from ~/.ssh/config works, and so do options before the name. Press Enter to open the tab, or Esc to cancel. /ssh web-3 in the agent panel opens it straight away.

Astrum runs your own ssh to get there, so your keys, your jump hosts and your ~/.ssh/config apply as they are. Whatever ssh asks (a password, a new host's fingerprint, a second factor) is shown in the pane, and you answer it there as you would anywhere.

Two tabs, the second named build-box: a shell on another machine showing a service's status and its log, and a status bar that says the shell is ada@build-boxTwo tabs, the second named build-box: a shell on another machine showing a service's status and its log, and a status bar that says the shell is ada@build-box
A tab on another machine: the tab bar and the status bar say where it is

What makes it different

The shells of an ordinary ssh live in the connection: when it goes, they go. A tab on another machine is not like that. Astrum's own program runs on the other machine and keeps the shells there, the way the session server keeps your shells here. The connection only carries what they show and what you type.

A dropped connection loses nothing

When the connection drops (the network goes, the laptop is closed), the pane says the connection was lost; the shell there and whatever runs in it carry on. Astrum reconnects by itself, after 1, 3, 8 and 20 seconds, then every minute. To try again at once, click Try again on the pane, or press Enter in it.

When the connection is back, what the shells wrote in the meantime is there. After a short absence the pane simply carries on: the last 4 MB each shell wrote is kept for that. After a longer one, the screen and its history are shown as they now stand.

So does restarting this machine

The tab is saved with the session, and finds its shells again when the session next starts, after a crash or a reboot here included. astrum kill ends them, as it ends the shells here; the tab still comes back, in a new shell in the same directory, under what the old one had shown. See Sessions that come back.

It is an ordinary tab

The agent has everything there that it has here

The agent's commands run in the shell there, where you watch them. Reading and searching files, and changing them with a diff for you to approve first, are carried out there by Astrum's program. An AGENTS.md in the project there is read along with your own rules from here, and the agent is offered your own skills. The model, your API keys and the conversation stay on your machine. See The agent.

If Astrum is not on the other machine

The first time you open a tab on a machine without Astrum, the pane says so and asks before doing anything:

That is one file in your home folder there: no root, no package manager, and the other machine needs no way out to the internet, because the file comes over your ssh. On the machine, Astrum looks for ~/.local/bin/astrum first and then for an astrum on the PATH, so a copy you installed there yourself is used as it is.

The build comes from the release on GitHub the first time, and is kept on your machine for the next one, in ~/.local/share/astrum/builds/.

Taking the build from somewhere else

download_base in the config file names a mirror, or a folder on your machine, to take the build from instead of GitHub, exactly as ASTRUM_DOWNLOAD_BASE does for the install script:

download_base = "file:///Users/me/astrum-release"

It is an https:// address, or file:/// and a folder. Either way it must hold the release file for that machine (astrum-linux-amd64, say) and a SHA256SUMS that lists it; the checksum is checked as always, and a file that does not match is not copied. The environment variable ASTRUM_DOWNLOAD_BASE, set before the session starts, does the same and takes precedence over the config file.

A development build of Astrum, one built from source between releases, has no release to copy. Put Astrum on the other machine yourself, or build it for that machine and point download_base at a folder holding it and a SHA256SUMS for it.

Two versions of Astrum

The two sides do not have to be the same version. Each says which number of their common language it speaks, a number that changes far less often than the version does, and any two versions with the same number work together.

Logging out of the other machine

The program that keeps the shells there is started as one of its own, which the connection closing does not take with it. On most systems that is enough to outlast a logout too.

A Linux system set to end a user's programs at logout (KillUserProcesses=yes in systemd's login settings) needs lingering turned on there, the same switch the login service relies on:

loginctl enable-linger

With it on, the program runs under your own systemd there and stays. Astrum tells you when a machine is set to end your programs and lingering is off.

The program stops by itself twenty seconds after its last shell has ended. A restart of that machine ends its shells, as it would anywhere; the tab comes back in a new one.

Where a tab on another machine cannot be used

On these, running ssh in an ordinary tab and taking the agent in still works:

Things to know about tabs on other machines

Taking the agent into a shell you reached

This is for a shell you reached yourself, from an ordinary tab: ssh to a server, docker exec into a container, sudo -s, a shell on the far side of a jump host. The agent works in the shell Astrum started in the pane; when that shell has taken you somewhere else, the agent can come with you.

Do thisWith the mouseWith the keyboard
Take the agent inclick take the agent in on the status bar, or ≡ menu → Take the agent into this shell (ssh, sudo…)Ctrl+B i, or /here in the agent panel

The status bar offers take the agent in by itself while the pane is running a program that usually ends in another shell: ssh, mosh, autossh, sshpass, et, telnet, docker, podman, kubectl, oc, nsenter, lxc, incus, machinectl, toolbox, distrobox, vagrant, sudo, su, doas, nix-shell, chroot, or a bash, zsh or fish started inside the pane's own. For anything else that ends at a shell prompt, use the menu entry or the key.

What happens

Astrum types a couple of lines into the shell you have reached, which set up there what it set up in your own shell: the marks that say where each command starts, how it ended, and which directory the shell is in. The lines are cleared from the pane once they have done their work. Astrum then says the agent works in that shell, and the status bar shows whose shell it is and its directory there (⇢ deploy@web-3 /srv/app).

From then on the agent's commands run in that shell, where you watch them as always, and it is told it is on another machine and which. The model, your API keys and Astrum itself stay on your own machine. Leave the shell (exit, or the connection dropping) and the agent is back in your own. It works a second level in too: taken into a server, then into a container on it.

Things to know about taking the agent in

If Astrum says nothing there answered, the shell you reached did not answer the line it typed: it is not at a prompt, or it is not a shell (a database console, a pager). The line may still be sitting there; clear it with Ctrl+U or Ctrl+C. See Troubleshooting.