Terminal

Run graphical Linux applications

Launch Wayland and X11 applications, switch their windows, and connect terminals or notebooks to the graphical session.

Run Linux graphical applications in CoCalc

These instructions require a Linux project with the graphical support tools. Automatic dependency installation uses Ubuntu/Debian package tools and requires permitted sudo access. Local CoCalc Plus uses the host operating system; it does not turn a native macOS or Windows installation into a Linux project.

Open or create a file ending in .x11 to start the graphical applications workspace. CoCalc uses Blit to provide a terminal and a headless Wayland compositor inside the project. Applications that use Wayland connect directly; X11 applications connect through Xwayland.

The application and its files still run in your project. Blit sends the application windows to your browser and sends keyboard, pointer, and clipboard input back to the project.

One shared session per project

All .x11 files in a project connect to the same graphical session. The file name is an access point, not the name of an independent desktop. Opening a.x11 and experiment.x11 therefore shows the same terminals, application windows, and previews.

Multiple collaborators and multiple browsers can open .x11 files at the same time. They all see and can control the shared session, including the same terminal input, pointer, clipboard, and application windows. Coordinate with collaborators before typing into or closing a window that somebody else may be using.

This project-wide model keeps graphical applications easy to find and avoids running several hidden compositors and display servers in one project.

Start an application

Use either of these methods:

The embedded terminal already has the Wayland and X11 environment variables for this graphical session. You do not need to set DISPLAY there.

The X11 RootFS includes every launcher application, Python and Jupyter, IDLE, Tkinter, pygame, application audio, and basic LaTeX for TeXstudio. Other RootFS images can install the graphical prerequisites and individual launcher applications on demand.

Chromium needs additional flags in a project container. The Chromium launcher adds them automatically. To start it from the embedded terminal, run:

chromium --ozone-platform=wayland --no-sandbox --disable-gpu

The --no-sandbox flag is necessary because project containers prohibit the nested namespaces used by Chromium's Linux sandbox. This removes Chromium's renderer-level security boundary: a compromised web page could access files and processes available to your project user. Only open sites you trust. The project container remains isolated from other projects and the project host.

Play application audio

Blit sends application audio to the browser through a private PipeWire sound server inside the project. Applications launched from the embedded terminal or from a launcher button inherit the required PulseAudio and PipeWire settings. This works with applications such as Chromium and pygame without access to an audio device on the project host.

Browser autoplay rules require sound to start muted. Click the musical-note control in Blit's status bar and enable Desktop sound to hear it. The control also lets you mute the session again and select an output device when the browser supports output selection.

For example, after installing pygame in the project, run this in the embedded graphical terminal:

python3 -m pygame.examples.aliens

If graphical support was installed or upgraded while a session was running, CoCalc restarts the shared graphical session so the new audio service is available. This closes applications from the old session.

Select an application window

Each application window first appears as a small surface preview in the column on the right. Click its preview to show that window at full size in the middle of the workspace. Click another preview to switch windows.

Closing a preview closes that application window. An application can have several previews when it opens several windows.

Shut down the graphical session

Choose Shut down at the right side of the launcher toolbar when you are finished. Confirming stops the Blit server and closes every graphical terminal and application window in the shared project session.

Shutdown affects every open .x11 file and every connected browser, not only the current view. The stopped view offers a button to start a fresh session.

Find popup and dialog windows

Popup windows and modal dialogs also appear as new previews in the right-hand column. They do not automatically replace the main window in the middle.

If the main application suddenly stops responding, look for a new preview on the right. The application may be waiting for you to answer a file chooser, warning, confirmation, or other modal dialog. Click that preview, respond to the dialog, and then select the main application again.

Launch X11 applications from another terminal or notebook

The embedded graphical terminal receives DISPLAY automatically. A regular CoCalc terminal or a Jupyter kernel does not, because it was started outside the graphical session.

Blit normally claims display :20. In the embedded graphical terminal, run this to confirm the actual value:

echo "$DISPLAY"

Blit tries the next available display if :20 is already occupied. Use the value printed above in a regular terminal. For the normal :20 case:

export DISPLAY=:20
xclock

In a Jupyter notebook:

import os
import subprocess

os.environ["DISPLAY"] = ":20"  # Replace this if the graphical terminal differs.
subprocess.Popen(["xclock"])

Keep the .x11 workspace running while using that display. Do not set DISPLAY=:20 globally for every project process: without a running graphical session it points applications at a display that does not exist, and a session may occasionally use a different display number.

Current limitations