Caterm

LINUX / DESKTOP SHARING

Linux desktop sharing

Caterm shares a running X11 desktop. Have an X11 desktop running before enabling sharing. Use Bash on Debian/Ubuntu for these commands. Caterm installation is covered in Getting started.

1. Run doctor

From the desktop's terminal, or your VPS shell:

Bash
caterm desktop doctor

If it passes, continue to Enable sharing. Otherwise, resolve the issues reported by doctor and rerun it.

2. Choose the desktop user

Run the desktop and Caterm under the same account. Caterm accepts both root and ordinary accounts, using that account's OS privileges and its selected DISPLAY / XAUTHORITY. Desktop applications retain their own permission and sandbox requirements.

On a normal computer, use your existing desktop login. On a root-only VPS, you can use root directly. To use a separate account instead, optionally create one and switch to it from the root shell:

Bash
id caterm >/dev/null 2>&1 || useradd --create-home --shell /bin/bash caterm
su - caterm
whoami
printf 'Home: %s\n' "$HOME"

If you create this account, expect caterm and /home/caterm. The account has no password login configured; root can enter it with su - caterm. Run exit to return to root when installing system packages.

When switching accounts, a binary installed in /root/.local/bin and root's saved credential are not available to the new user. Follow Getting started to install Caterm under this account if needed. If only root enrolled the device, enroll again under this user in step 3.

3. Enable sharing

Use the same user and display environment that passed doctor. Stop any Caterm daemon already running under this account:

Bash
caterm stop

If none is running, continue. For a device already enrolled under this user:

Bash
caterm connect --saved --desktop

For a new user, choose Add a device in the web app and append --desktop to the generated command. Simulated example — replace the code with your fresh code:

Bash
caterm connect --server https://caterm.com --enrollment-code 00123456 --desktop

Linux connections run in the background by default. Add -i for a foreground connection; use caterm logs -f for logs. If a previous daemon is still running as root, stop it separately in a root shell with its original Caterm executable.

Open Devices → your device → Desktop, choose View or Control, and connect. Keep the X11 desktop running; disconnecting the viewer leaves it running.

Common fixes

ProblemFix
Account or runtime ownership mismatchUse step 2. Run the desktop, doctor, and connection as the same account with its private runtime directory.
DISPLAY / authorization failureUse the desktop's terminal with its DISPLAY and XAUTHORITY values.
Wayland is not supportedSelect an actual X11/Xorg login session.
Missing runtime directoryRun the command below as the desktop user, then rerun doctor.
Cannot bind private worker socket / socket path too longUse the short runtime directory below and restart Caterm in that shell. Keep DISPLAY and XAUTHORITY unchanged.
Black screenRun xmessage -center 'Caterm desktop check' & in the display environment. If it appears, capture works; check whether your desktop session is running.
Bash
export XDG_RUNTIME_DIR="/tmp/caterm-runtime-$(id -u)"
install -d -m 0700 "$XDG_RUNTIME_DIR"
caterm desktop doctor

Install browsers and other applications yourself. See Daemon & CLI for connection options.