# Add a machine

> Run agents on another Mac or a Linux box, and pair your iPhone and iPad. The code and the agents stay on your machines; Sesh shows you the sessions everywhere.

Source: https://sesh.codes/docs/add-a-machine/

## Before you start

- A shell on the other computer, over SSH or at its own keyboard. It can be a Mac, or Linux on Intel or ARM.
- An internet connection on it. It doesn't need to be on your network: Sesh reaches it from anywhere.
- git on that computer, and a way to push from it, like `gh auth login` or an SSH key.

Starting from a brand-new cloud server? Follow [Run Sesh on a cloud server](https://sesh.codes/docs/cloud-server.md) instead; it covers the extra setup a fresh server needs.

## Install Sesh on the computer

Run this on the other computer:

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

It installs `seshd` and `sesh` in `~/.local/bin`, starts `seshd` as a service that comes back after a restart, and prints a pairing code.

On a Mac with a screen, you can [download Sesh Host](https://sesh.codes/releases/latest/Sesh-Host.pkg) instead. It installs the same thing without printing a code, so run `~/.local/bin/sesh pair` there afterwards to get one.

> **On Linux, two more commands.** `loginctl enable-linger $USER` keeps Sesh running after you log out. Installing `bubblewrap` (for example `sudo apt install bubblewrap`) lets Sesh sandbox Autonomous sessions.

## Pair it with Sesh

The installer printed a pairing code. If it's gone, run `sesh pair` on the computer for a new one:

```sh
$ sesh pair
Pairing code: 7KQ4-M2XD  (works once, for 10 minutes)
Or from another machine with sesh: sesh --id 3f9a…c21d --pair 7KQ4-M2XD list
```

The long ID is the computer's own: Sesh finds it by that from any network, with no address to type and nothing to open in a firewall.

If the window is big enough, it also draws a QR code (it says how big when it isn't). To pair a phone or tablet without a Mac, open Sesh on it, tap **Add Machine**, and scan the code.

Then, on your Mac:

1. Open **Settings › Machines** and click **Add Machine…**.
2. Paste the computer's **ID** from `sesh pair` into **Machine**.
3. Enter the **Pairing code**, give it a **Name** if you like, and click **Pair**.

The computer shows up as **Connected**. Your iPhone and iPad get it too, over iCloud.

> **Encrypted, and direct when it can be.** The ID is the computer's key, so only that computer can answer to it. Sesh connects straight to it whenever the networks allow; otherwise traffic goes through Sesh's relay, which can't read it.

## Pair an iPhone or iPad

An iPhone or iPad signed in to the same Apple ID as your Mac doesn't need this: it gets your Mac and every machine you've added through iCloud. Pair any other device with a code:

1. On your Mac, open **Settings › Machines** and, under **iPhone & iPad**, click **Pair iPhone or iPad…**. Or choose **File › Pair iPhone or iPad…**.
2. On the device, open Sesh, tap **Add Machine**, and scan the code on your Mac.

The code works once. Click **New Code** for another. Paired devices are listed under **iPhone & iPad**, where **Unpair…** disconnects one.

> **Away from home?** Nothing to set up: your phone reaches your machines from any network.

## Start a session there

In **New Session**, choose the computer from the machine menu above the project. Projects in `~/code`, `~/src`, `~/Developer` and similar folders show up on their own. **Clone Repository…** clones into `~/code` on that computer.

Need to log in to something there? Choose **File › New Terminal on** and pick the computer.

## Keep it running

- **Keep Awake While Agents Work** stops the computer from sleeping mid-task. It's on; find it in the machine's **⋯** menu in **Settings › Machines**.
- A sleeping computer can't be reached between tasks. Turn on **Stay Awake Between Tasks** in the same menu. See [Reach your Mac while you're away](#reach-your-mac-while-youre-away).
- **Update Automatically** installs new versions of Sesh on the computer when no agent is working and no terminal is open. It's on; find it in the machine's **Details…**. Otherwise, when a machine says **Needs Update**, click **Update**, or run `seshd update` on the computer.
- To unpair a device, run `sesh clients` on the machine, then `sesh revoke` with its ID. For this Mac, use **Unpair…** under **Paired Devices** in **Details…**.

## Reach your Mac while you're away

Sesh keeps your Mac awake while an agent works. Between tasks, macOS puts it to sleep as usual, and your phone can't reach a sleeping Mac. To start new work from anywhere, keep it awake all the time:

1. Open **Settings › Machines**.
2. Click the machine's **⋯** menu.
3. Turn on **Stay Awake Between Tasks**.

The display still turns off and the screen still locks. Only the Mac stays awake.

### Close the lid

A MacBook goes to sleep when you close its lid, even mid-task. To let Sesh keep it awake with the lid closed:

1. In the machine's **⋯** menu, choose **Allow Staying Awake with the Lid Closed…**.
2. A terminal opens on the Mac. Type the Mac's password and press Return.

You only do this once. It lets Sesh turn sleep off while it keeps the Mac awake, and nothing else. If you installed Sesh with **Sesh-Host.pkg**, it's done already. To undo it, run `sudo seshd keep-awake uninstall` on the Mac.

### On battery

Sesh shows a machine's battery next to it while it's unplugged. At 20% or less, it stops keeping the Mac awake between tasks and lets the lid put it to sleep, until you plug it in. An agent that's working still keeps it awake.

## If something's wrong

**The machine says Offline.** Check that it's on and online, and that `seshd` is running there (`sesh info`). On Linux, did you run `loginctl enable-linger $USER`?

**Your Mac is Offline while you're away.** It's probably asleep. See [Reach your Mac while you're away](#reach-your-mac-while-youre-away).

**The pairing code doesn't work.** Each code works once, for 10 minutes. Run `sesh pair` for a new one.

**Cloning a private repository fails.** Clones use that computer's git login, not your Mac's. Open **File › New Terminal on** the computer and run `gh auth login`.
