# 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.

Source: https://sesh.codes/docs/cloud-server/

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](https://sesh.codes/docs/add-a-machine.md).

## 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 <kbd>Return</kbd> 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:

   ```sh
   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:

   ```sh
   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:

   ```sh
   loginctl enable-linger you
   ```

   bubblewrap, installed above, is what lets Sesh sandbox [Autonomous sessions](https://sesh.codes/docs/approvals-and-autonomous.md).

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:

   ```sh
   ssh you@SERVER_IP
   ```

2. Run the installer:

   ```sh
   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](https://sesh.codes/docs/add-a-machine.md#pair-it-with-sesh).

## 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:

   ```sh
   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:

   ```sh
   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:

   ```sh
   sudo apt install -y gh
   gh auth login
   gh auth setup-git
   ```

3. **Set your git name and email,** for the agents' commits:

   ```sh
   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](https://sesh.codes/docs/secrets-and-variables.md).

Dev servers that agents start on the server open on your Mac like local ones, with no ports to open. See [Dev servers](https://sesh.codes/docs/dev-servers.md).

## 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:

```sh
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](#add-swap-on-a-small-server), 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.
