Skip to content
Termivoa Docs

Install on Linux

Termivoa installs on Ubuntu (desktop, server or WSL) as one file, pterm, with an install script that runs pterm setup.

Requirements

Section titled “Requirements”
  • Ubuntu 22.04 or 24.04, on x86_64 or arm64.
  • Tailscale on the computer and the phone, signed in to the same account.
  • The GitHub CLI (gh), signed in with gh auth login. You need an invite to the private repository.
  • A normal user, not root. The install script refuses root.

No extra packages or Node.js are needed.

Install

Section titled “Install”

On arm64, use pterm-linux-arm64 in both commands:

Terminal window
gh release download v0.1.0-beta.3 -R intojhanurag/Termivoa -p pterm-linux-amd64 -p install-linux.sh
sh install-linux.sh ./pterm-linux-amd64

The script installs ~/.local/bin/pterm and starts setup. If this terminal does not find pterm yet, the last lines of setup give the command to fix it:

`pterm` is not on your PATH in this terminal yet. To use it here, run this now:
  export PATH="/home/you/.local/bin:$PATH"
New logins have it already: your ~/.profile adds ~/.local/bin when it exists.

With zsh, the last line says to add the export line to ~/.zshrc. Until then, you can also type ~/.local/bin/pterm.

To check the download, get the release’s SHA256SUMS file and run shasum -a 256 -c SHA256SUMS --ignore-missing.

Then follow Pair your phone. If Termivoa is already on your phone (this is your second computer), answer 2 when setup asks “Is Termivoa already on your phone?”, then pick the computer you first paired. See Use several computers.

What if I am logged in as root?

Section titled “What if I am logged in as root?”

The script and pterm setup refuse root: your phone would get root’s shell. A new VPS often has only root. The script then prints the commands that make a normal user with sudo rights (the wheel group on Fedora), give it your SSH key, and copy the two files to it:

Terminal window
adduser <name>
usermod -aG sudo <name>
install -d -m 700 -o <name> -g <name> /home/<name>/.ssh && install -m 600 -o <name> -g <name> ~/.ssh/authorized_keys /home/<name>/.ssh/
install -m 644 -o <name> -g <name> install-linux.sh ./pterm-linux-amd64 /home/<name>/

Then log in as that user (ssh <name>@<server>) and run the install again. If you ran it with sudo, run it again without sudo.

How does it start at login?

Section titled “How does it start at login?”

pterm setup adds two systemd user services that run as you, not as root:

  • phone-terminal-broker.service: the broker, which owns your sessions.
  • phone-terminal-gateway.service: the gateway, which serves the phone page on this computer only (127.0.0.1:8787).

Setup lists this in a short plan before it asks. pterm setup --verbose also shows the unit files and every systemctl --user command. If a service crashes, systemd restarts it after 5 seconds.

Keep sessions running on a server or VPS

Section titled “Keep sessions running on a server or VPS”

On a server or VPS you reach only by SSH, answer y to this setup question:

This runs: loginctl enable-linger <user> [y/N]

Without linger, systemd stops your services, and all sessions, when your last SSH login closes. With linger on, Termivoa starts at boot and sessions survive logout. If the system refuses, setup prints the sudo command to run; pterm never uses sudo itself.

Why does setup skip the Tailscale questions?

Section titled “Why does setup skip the Tailscale questions?”

On Linux, only root or the Tailscale operator may share the page. To become the operator, run this once, then run pterm setup again:

Terminal window
sudo tailscale set --operator=$USER

Until then your phone cannot reach the computer, so setup does not pair a phone. The plan and the last line of setup say so:

Setup is done, but your phone cannot reach this computer yet: on Linux only root or the Tailscale operator may share it on port 443. Run this once: sudo tailscale set --operator=$USER, then run `pterm setup` again.

Install in WSL (Windows Subsystem for Linux)

Section titled “Install in WSL (Windows Subsystem for Linux)”

Windows stops the WSL virtual machine about a minute after the last WSL window closes, ending all sessions.

  • Recommended: follow Install on Windows and use its WSL bash shell.

  • Or: install the Linux version and turn on systemd. Add these lines to /etc/wsl.conf, run wsl --shutdown in Windows, open WSL again, and run pterm setup:

    [boot]
    systemd=true

Without systemd, nothing starts Termivoa at login. Setup starts it once in the background; run pterm launch after each restart.

Where does pterm put its files?

Section titled “Where does pterm put its files?”
What Where
Program ~/.local/bin/pterm
Data ~/.local/share/phone-terminal
Logs ~/.local/state/phone-terminal/logs
Sockets /run/user/<uid>/phone-terminal
Startup units ~/.config/systemd/user

All are private to your user.

Keep the computer awake

Section titled “Keep the computer awake”

On an Ubuntu desktop, turn off Settings → Power → Automatic Suspend.