Skip to content

Work together#

Several people can work in the same runtime at once:

  • Notebooks, live: everyone who opens a notebook in JupyterLab edits it at the same time, each cursor with a name and a colour, and runs it on the same kernel.
  • The IDE, live: you share your editor from an IDE environment; the people you let in see your files, edit them with you and follow your cursor.
  • The shared terminal: one terminal that everyone in an environment sees and types in.

The people who can do this are the runtime's people: its owner, the people it is shared with (Share an environment) and the workspace's admins. Each person is shown by the name of their Astralyx account; a name cannot be made up from the browser. The workspace's viewers reach none of it.

Before you begin#

  • The runtime is shared with everyone who will work in it (People → Shared with on its page, or astra env share <env> <e-mail>). The same works for a notebook's runtime: open it from Hesperus → Environments or from the notebook (the runtime chip → its page).
  • For the shared terminal from your computer: the Astralyx CLI, signed in and set to the workspace (astra login, astra use <org>/<workspace>), and OpenSSH's client. See Use ssh, scp and rsync.
  • The runtime's page shows who is in it now, under Work together → In it now: the people with its JupyterLab, its IDE or one of its apps open, and its open SSH sessions.

Edit a notebook together#

JupyterLab opens at the runtime's own address, like the IDE (Addresses of their own).

  1. Open the notebook. When it is connected, select Edit together in its toolbar (save first: JupyterLab opens the notebook as it is on the drive).
  2. JupyterLab opens in a new tab with the notebook. Send the notebook's console link to the others; each selects Edit together too.

Or, from the runtime's page, Work together → Open JupyterLab opens JupyterLab's file browser.

Everyone in the notebook edits the same document: changes appear as they are typed and are saved to the drive. Cells run on the one kernel the notebook has, so variables, outputs and a running cell are everyone's. The people in a notebook are listed in JupyterLab's Collaboration panel.

Keep the notebook closed in the console's own editor while you edit it in JupyterLab: the console's editor saves the whole file, and the last save wins.

The first time a runtime starts, it installs live collaboration onto its drive (JupyterLab's jupyter-collaboration, matched to the JupyterLab its image has, or JupyterLab too when the image has none); it is there at every start after that. An image with a JupyterLab older than 4.4 opens notebooks as before, one person at a time; its run's logs say so.

Read-only

Live rooms have no read-only seat: whoever opens the notebook may edit it. The workspace's viewers cannot open the runtime at all.

Edit together in the IDE#

An IDE environment comes with Open Collaboration Tools (Eclipse), set to Astralyx's collaboration server. When it is not set up for your console, Work together on the environment's page says so.

  1. Open the environment and select Open IDE.
  2. In the IDE, select Open Collaboration in the status bar, then Create Collaboration Session — or run Open Collaboration Tools: Create Collaboration Session from the Command Palette (Ctrl+Shift+P).
  3. The first time, a page of the console opens: check that it shows your account and select Sign in. Only confirm a sign-in you just started from your own IDE: that IDE then shares and joins sessions as you.
  4. Copy the invitation the IDE shows and send it to the people of the environment.
  5. They join from an IDE of their own: an IDE environment of theirs (Open IDE, then Open Collaboration Tools: Join Collaboration Session with the invitation), or VS Code on their computer with the Open Collaboration Tools extension and its server set to the address Work together → Collaborate… shows. They sign in the same way, as themselves.
  6. You accept each person as they ask.

Only the people of an environment you have open can ask to join your session; anyone else is refused before you are asked. Taking someone off the environment's people refuses their next request to join. A sign-in lasts 12 hours; then the IDE asks again.

One editor, one sign-in

An IDE environment's editor is one for everyone who opens it: its settings, extensions — and the collaboration sign-in — are shared. Someone else who opens the same environment's IDE while you are signed in there shares and joins as you. Share from an IDE environment that is yours alone, join from your own, and in an environment several people open, run Open Collaboration Tools: Sign Out when you are done.

The IDE needs to reach the collaboration server over HTTPS from the machine it runs on.

Use the shared terminal#

Every environment has one shared terminal: a tmux session named astra-shared. It keeps running when everyone leaves, with what was running in it. tmux is installed when the environment starts, with the basic tools; with the basic tools turned off, an environment still gets tmux.

In the IDE: Terminal → New Terminal ▾ (the arrow beside +) → Shared terminal (astra-shared). Everyone who opens it from the IDE, or attaches from a computer, is in the same terminal.

$ astra env attach dev --shared

To watch without typing:

$ astra env attach dev --shared --read-only

Without --shared, astra env attach dev attaches to a terminal of your own (tmux session astra) that outlives your connection. Detach with Ctrl+B then D.

--read-only is a courtesy, not a permission: anyone who may connect to the environment may also attach without it. Everyone logs in as the environment's login user, so the shared terminal runs as that user.