Workspaces

A piece of work often spans several sessions: an agent on your laptop, its tests on a build box, a dev server on a Linux machine. A workspace gives that set a name.

A workspace is a record, not a container. It holds its sessions’ addresses (3 on this machine, studio:3 on another), and nothing in it owns a session: forget the workspace, or take a session out of it, and every session carries on. A session may be in several workspaces, or none.

Making one

alto new --workspace web -- npm run dev        # start a session in it, making it if it isn't there
alto --on studio new --workspace web           # a session on studio, added as studio:ID
alto new --in 'os:linux' --workspace web       # wherever it lands
alto workspace new api                         # an empty one
alto workspace add web 4 studio:7              # sessions already running

Seeing it

alto workspace                  # the workspaces kept here, and how many sessions each holds
alto workspace show web         # each session with what it's doing
alto ls --workspace web         # the same, as ls

alto attach web                 # choose one of its sessions, the one needing you first, and attach here

A workspace has a mark, its sessions’ most urgent: needs-you when any of them needs you, else working, done, or idle. alto workspace shows each one’s, and so does show.

alto ls --waiting --workspace web   # only its sessions waiting for you

ls --waiting and alto events name the workspaces each session is in, and a phone’s notification names them after the session (studio · 3 · web).

A session that ended stays listed, as ended, until you take it out. One killed outright or lost to a restart says it can run again. A session on a machine that isn’t answering shows what that machine said last, and says so.

One kept on another machine

alto workspace show studio:web      # a workspace kept on studio, from here
alto ls --workspace studio:web

studio gives the names and addresses; what each session is doing, this machine asks each session’s machine itself, as that machine trusts this one. A session on a machine this one can’t reach is named, with nothing more. A workspace is changed only on the machine that keeps it.

Changing it

alto workspace remove web 4     # take a session out; it keeps running
alto workspace forget web       # forget the workspace; its sessions keep running

Every one of these takes --json.

Where it’s kept

A workspace is kept by the service on the machine it was made on, in its state folder (workspaces/NAME.json). Its name is letters, digits, - and _, with at least one letter, so it’s never mistaken for a session’s id. Names are the same whatever their case.

An agent can make a workspace and change the ones it made. A workspace you made is yours: an agent can’t change it.

In the fleet view

alto fleet’s Overview has a line for each workspace: how many of its sessions are running, and how many need you. Enter on it opens the workspace’s screen: Sessions showing only its members, wherever they run, the ones needing you first; Enter on one attaches. The same is workspace:web typed in any tab’s filter, and Group by → workspace (w, or alto fleet --group-by workspace) shows every workspace at once, a session in two under both. In a script: alto ls --all --group-by workspace.

Coming next

Alto’s window keeps its tabs and splits as a workspace of its own, window-1, which alto workspace lists as the window’s: its sessions are the window’s panes, wherever they run.

Planned · Phase 12 Opening a workspace whole as a window of its own in the app, and as a list on the phone.