Sesh Docs
sesh.codes
Guides › Run Sesh on a cloud server

Run Sesh on a cloud server

Rent a Linux server and turn it into a machine your agents can work on around the clock, with nothing to keep awake at home.

About 20 minutes

A cloud server (a VPS) from Hetzner, DigitalOcean, Linode, AWS Lightsail or any other provider makes a good Sesh machine. It’s always on, it’s on a fast network, and agents on it can’t touch the files on your Mac. This guide takes a brand-new server to a paired machine. Pairing itself is the same as for any computer; see Add a machine.

Before you start

  • An account with a cloud provider.
  • An SSH key on your Mac. If ls ~/.ssh/*.pub shows nothing, run ssh-keygen -t ed25519 and press Return at each question.
  • Sesh on your Mac, iPhone or iPad, to pair it with.

Pick a server

  1. Choose Ubuntu 24.04 or Debian 12. Any Linux works, but these are what the commands below use.
  2. Pick a size. Agents themselves are light; your builds and tests are what need room.
    • 2 GB of memory runs an agent on a small project. Add swap (see below).
    • 4 GB is a good start for most projects.
    • 8 GB or more for big builds, or several agents at once.
    • 40 GB of disk or more. Every session gets its own copy of the project.
  3. Intel or ARM both work. ARM servers are often cheaper.
  4. Add your SSH key when the provider asks for one, so you never need a password.
  5. Pick the region closest to you, then create the server and copy its IP address.

You don’t need to open any ports for Sesh, so skip the provider’s firewall settings for now.

Create your user

A new server only has root. Sesh should run as a normal user, so it can’t change the whole system.

  1. Log in from your Mac:

    ssh root@SERVER_IP
  2. Install what Sesh needs, then create a user (use any name in place of you), give it sudo, and copy your SSH key to it:

    apt update && apt install -y git bubblewrap sudo ufw rsync
    adduser you
    usermod -aG sudo you
    rsync --archive --chown=you:you ~/.ssh /home/you

    adduser asks for a password. You’ll need it for sudo, not for logging in.

  3. Let the user’s services keep running when nobody is logged in:

    loginctl enable-linger you

    bubblewrap, installed above, is what lets Sesh sandbox Autonomous sessions.

  4. Type exit to log out.

Log in as the user, don’t switch to it. su you or sudo -u you from root doesn’t start the user’s services, and the installer then fails to start Sesh. Always ssh you@SERVER_IP.

Install Sesh

  1. Log in as your user:

    ssh you@SERVER_IP
  2. Run the installer:

    curl -fsSL https://sesh.codes/install.sh | sh

    It installs seshd and sesh in ~/.local/bin, starts Sesh as a service, and prints a pairing code.

  3. If it says to add ~/.local/bin to your PATH, log out and back in. Ubuntu and Debian add it on login once the folder exists.

Pair it

The installer printed the server’s ID, a pairing code and, if the window is big enough, a QR code. Run sesh pair for a new code any time.

  • On a Mac: Settings › Machines › Add Machine…, paste the ID into Machine, enter the Pairing code, give it a Name, and click Pair.
  • On an iPhone or iPad: tap Add Machine and scan the QR code.

The server shows up as Connected, and your other devices get it over iCloud. More detail is in Add a machine.

Lock it down

Sesh connects out to the internet, so it needs no open ports. Everything coming in except SSH can be blocked.

  1. Turn on the firewall, allowing SSH:

    sudo ufw allow OpenSSH
    sudo ufw enable
  2. Turn off password logins and logging in as root. Check that ssh you@SERVER_IP works from a second terminal first, so you can’t lock yourself out:

    printf 'PasswordAuthentication no\nPermitRootLogin no\n' | sudo tee /etc/ssh/sshd_config.d/90-sesh.conf
    sudo systemctl reload ssh

Faster from home, optionally. When it can’t connect to the server directly, Sesh goes through its relay, which can’t read your traffic but adds a little delay. To let devices connect directly, also run sudo ufw allow 4777/udp, and allow UDP port 4777 in the provider’s firewall if you use one.

Give agents what they need

A server starts empty. Agents can only use what’s installed on it, just as you could.

  1. Get an agent. In Settings › Machines, click Details… next to the server, then Get next to an agent. Sesh installs it, and Node.js if the agent needs it. Then sign in from the agent’s account menu.

  2. Sign in to GitHub, so agents can clone private repositories and push. Choose File › New Terminal on and pick the server, then:

    sudo apt install -y gh
    gh auth login
    gh auth setup-git
  3. Set your git name and email, for the agents’ commits:

    git config --global user.name "Your Name"
    git config --global user.email you@example.com
  4. Install your project’s tools: compilers, package managers, databases. Whatever you’d install to work on it yourself.

  5. Copy your secrets. Your .env files and API keys can go over from your Mac. See Secrets and environment variables.

Dev servers that agents start on the server open on your Mac like local ones, with no ports to open. See Dev servers.

Add swap on a small server

Builds and npm install can run out of memory on a 2 GB server, and the agent’s command dies with no clear error. Swap gives it room to spare. In a terminal on the server:

sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

Keep it running

  • Sesh updates. The server installs new versions of Sesh on its own when no agent is working and no terminal is open (Update Automatically in the machine’s Details…). Otherwise, when it says Needs Update in Sesh, click Update, or run seshd update on the server.
  • System updates. Ubuntu installs security updates on its own. On Debian, run sudo apt install -y unattended-upgrades once.
  • Backups. Your projects, sessions and logins are all in your home folder on the server. Turn on the provider’s backups or snapshots, or push your branches often.
  • Restarts. Sesh starts again on its own after the server reboots. Sessions that were working pick up where they left off.

If something’s wrong

The installer says seshd didn’t start. You probably switched to the user with su instead of logging in as it. Log out, then ssh you@SERVER_IP and run the installer again. Also check that loginctl enable-linger you was run.

The server says Offline after a reboot. Run loginctl show-user you --property=Linger on the server. If it says Linger=no, run sudo loginctl enable-linger you.

Autonomous sessions say they aren’t sandboxed. Install bubblewrap (sudo apt install bubblewrap) and start a new session. Some systems block what bubblewrap needs; the session tells you when it runs without a sandbox.

Builds stop with no error, or say “Killed”. The server ran out of memory. Add swap, or move to a bigger server.

Cloning a private repository fails. Clones use the server’s git login, not your Mac’s. Run gh auth login and gh auth setup-git in a terminal on the server.