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/*.pubshows nothing, runssh-keygen -t ed25519and press Return at each question. - Sesh on your Mac, iPhone or iPad, to pair it with.
Pick a server
- Choose Ubuntu 24.04 or Debian 12. Any Linux works, but these are what the commands below use.
- 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.
- Intel or ARM both work. ARM servers are often cheaper.
- Add your SSH key when the provider asks for one, so you never need a password.
- 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.
-
Log in from your Mac:
ssh root@SERVER_IP -
Install what Sesh needs, then create a user (use any name in place of
you), give itsudo, 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/youadduserasks for a password. You’ll need it forsudo, not for logging in. -
Let the user’s services keep running when nobody is logged in:
loginctl enable-linger yoububblewrap, installed above, is what lets Sesh sandbox Autonomous sessions.
-
Type
exitto log out.
Log in as the user, don’t switch to it.
su youorsudo -u youfrom root doesn’t start the user’s services, and the installer then fails to start Sesh. Alwaysssh you@SERVER_IP.
Install Sesh
-
Log in as your user:
ssh you@SERVER_IP -
Run the installer:
curl -fsSL https://sesh.codes/install.sh | shIt installs
seshdandseshin~/.local/bin, starts Sesh as a service, and prints a pairing code. -
If it says to add
~/.local/binto 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.
-
Turn on the firewall, allowing SSH:
sudo ufw allow OpenSSH sudo ufw enable -
Turn off password logins and logging in as root. Check that
ssh you@SERVER_IPworks 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.
-
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.
-
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 -
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 -
Install your project’s tools: compilers, package managers, databases. Whatever you’d install to work on it yourself.
-
Copy your secrets. Your
.envfiles 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 updateon the server. - System updates. Ubuntu installs security updates on its own. On Debian, run
sudo apt install -y unattended-upgradesonce. - 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.