Metadata-Version: 2.5
Name: sleap-connect
Version: 0.0.8
Summary: Remote SLEAP training and inference: run sleap-nn on a GPU machine from sleap-app
License-File: LICENSE
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: aiortc
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: boto3
Requires-Dist: cryptography>=41.0.0
Requires-Dist: iroh>=1.1.0
Requires-Dist: jsonpickle
Requires-Dist: loguru
Requires-Dist: opencv-python-headless>=4.12.0.88
Requires-Dist: prompt-toolkit>=3.0.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: pycrdt>=0.8.0
Requires-Dist: pyjwt>=2.8.0
Requires-Dist: pyotp>=2.9.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: pyzmq
Requires-Dist: requests
Requires-Dist: rich-click>=1.7.0
Requires-Dist: textual>=0.50.0
Requires-Dist: tomli-w>=1.2.0
Requires-Dist: websockets
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: pyqt5; (sys_platform != 'win32') and extra == 'dev'
Requires-Dist: pyqt6; (sys_platform == 'win32') and extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: pytest-timeout; extra == 'dev'
Requires-Dist: pyyaml; extra == 'dev'
Requires-Dist: qtpy; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: sleap-io; extra == 'dev'
Provides-Extra: nn
Requires-Dist: sleap-nn[torch]<0.4.0,>=0.3.3; extra == 'nn'
Description-Content-Type: text/markdown

# SLEAP Connect

Remote training and inference for [SLEAP](https://sleap.ai): run `sleap-nn` on a GPU machine
from [sleap-app](https://app.sleap.ai), with no account or server in between.

> Formerly `sleap-rtc` (PyPI `sleap-rtc` stops at 0.0.7). The `sleap-rtc` command still works as an
> alias. An existing `~/.sleap-rtc`
> folder (paired devices, shared folders, jobs) moves to `~/.sleap-connect` the first time you run `sleap-connect`.

## Quick start

**1. Install on the GPU machine.** The `nn` extra installs [sleap-nn](https://nn.sleap.ai), which runs
the training and inference jobs, along with the worker; `--torch-backend auto` picks the PyTorch build
for your GPU:

```bash
uv tool install --python 3.11 "sleap-connect[nn]" --torch-backend auto
```

Check the machine is ready with `sleap-connect doctor`: it shows the GPU, and whether sleap-nn can start.

**2. Start the worker in your data folder.**

```bash
cd /path/to/your/data
sleap-connect serve
```

Or name the folder instead of `cd`-ing into it: `sleap-connect serve /path/to/your/data` (handy with
`uv run`). The first time, it asks whether to share this folder with the devices you pair. Answer **y**:
they can then browse it, and their jobs can read and write inside it. The answer is remembered.

The worker then runs in the background: you get your prompt back, and it keeps running after you
close the terminal or log out. Check on it with `sleap-connect status` and stop it with
`sleap-connect serve --stop`. So you don't forget it's running, new terminals show a one-line
reminder while it is (`sleap-connect shell-hook uninstall` removes it). Use `--foreground` to keep it
attached to the terminal instead.

**3. Get a pairing code.**

```bash
sleap-connect pair
```

It prints a one-line code starting with `sleap1`. It works once and expires after a few minutes.

**4. Pair from sleap-app.** In [app.sleap.ai](https://app.sleap.ai) or the desktop app, open
**Connect → Pair a worker** and paste the code. Then train or run inference from the Training
panel or the Connect window.

The full guide (connection routes, the Connect window, troubleshooting) is in the
[sleap-app docs](https://app.sleap.ai/docs/main/guides/remote-compute/).

## Commands

| Command | What it does |
|---|---|
| `sleap-connect serve [FOLDER]` | Start the worker in the background, sharing FOLDER (default: the current folder). `--stop` stops it; `--foreground` keeps it attached to the terminal (Ctrl-C to stop). |
| `sleap-connect status` | Show whether the worker is running: PID, uptime, address, shared folders, paired devices, jobs. |
| `sleap-connect pair` | Print a one-time pairing code for a new device. |
| `sleap-connect folders` | List the folders shared with paired devices. |
| `sleap-connect add-folder [FOLDER]` | Share another folder (relative paths are fine). |
| `sleap-connect remove-folder FOLDER` | Stop sharing a folder (by path or label). |
| `sleap-connect clients` | List paired devices: name, app, when paired, last seen. |
| `sleap-connect clients remove NAME` | Unpair a device (by name or ID prefix). `--all` unpairs every device and cancels unused pairing codes. |
| `sleap-connect doctor` | Check this machine is ready to run a worker: Python, dependencies, GPU, sleap-nn. |
| `sleap-connect shell-hook uninstall` | Remove the new-terminal reminder (`install` adds it back; set `SLEAP_CONNECT_NO_SHELL_HOOK=1` to never add it). |
| `sleap-connect legacy …` | The older signaling-server workflow (accounts, rooms, `train`/`track`), being retired. The old top-level names still work. |

## How it works

- **The worker is the server.** `serve` listens for the app directly: a WebSocket on port 9631,
  result downloads on 9632, and an [iroh](https://iroh.computer) endpoint. There's no signaling
  server, room, or login.
- **Pairing decides who gets in.** A pairing code carries the worker's ID, its addresses and a
  one-time secret. The app claims it once; after that the worker trusts that device's key, and
  every connection proves it. Remove a device with `sleap-connect clients remove`.
- **Two ways to connect.** On the same network or over a VPN such as Tailscale, the app connects
  to `ws://<worker>:9631`. The desktop app can also connect over iroh, which goes through a relay
  first and then switches to a direct connection when it can, so it works across networks.
  Relays only see encrypted traffic.
- **Shared folders.** Paired devices can only browse the folders the worker shares: the one
  `serve` started in, plus any added with `add-folder`. The worker's own settings folder
  (`~/.sleap-connect`) is never shared.
- **Jobs live on the worker.** Jobs queue and keep running if the app disconnects or the worker
  restarts; the app catches up on progress when it reconnects.

## Installation options

Pick a PyTorch build explicitly instead of `--torch-backend auto`:

```bash
# CUDA GPU (here CUDA 12.8)
uv tool install --python 3.11 "sleap-connect[nn]" --torch-backend cu128

# CPU only
uv tool install --python 3.11 "sleap-connect[nn]" --torch-backend cpu
```

Already have sleap-nn installed on its own (`uv tool install sleap-nn`)? Install the worker without the
extra, `uv tool install sleap-connect`, and it runs the `sleap-nn` on your PATH. One installed with the
worker is used first.

The latest development version, from `main`:

```bash
uv tool install --python 3.11 "sleap-connect[nn] @ git+https://github.com/talmolab/sleap-connect" \
  --torch-backend auto
```

To update, run the same command again with `--reinstall`. Upgrading from `sleap-rtc` 0.0.7 or
earlier? Remove it first (`uv tool uninstall sleap-rtc`): both install the same commands. Your paired
devices, shared folders and jobs are kept. On a fresh Linux container, sleap-nn may
also need system libraries: `apt-get install -y libegl1 libgl1 libfontconfig1` (`sleap-connect
doctor` names the one that's missing).

## Legacy: rooms, dashboard and SLEAP GUI

The older workflow connects through a signaling server with GitHub login and rooms, over WebRTC.
It's still used by the [dashboard](https://talmolab.github.io/sleap-rtc/dashboard/index.html), the
SLEAP GUI's Remote Training dialog, and the `sleap-connect legacy train` / `sleap-connect legacy track` commands. It
will be retired; sleap-app uses the pairing workflow above.

<details>
<summary>Legacy setup</summary>

**Dashboard**

1. **Login** — Go to the [dashboard](https://talmolab.github.io/sleap-rtc/dashboard/index.html) and log in with GitHub.
2. **Create a room** — Click **Rooms** → **Create Room**.
3. **Generate an account key** — Go to **Account Keys** and create one. Copy it for the worker.
4. **Deploy a worker** — On your GPU machine:

   ```bash
   sleap-connect legacy login
   sleap-connect legacy config add-mount /path/to/your/data
   sleap-connect legacy worker --room <room-id>
   ```

5. **Submit a job** — In the dashboard, click **Submit Job** on your room card, select the worker, upload a config, and submit.

**CLI**

```bash
sleap-connect legacy login                       # GitHub login (opens browser)
sleap-connect legacy config add-mount /path/to/your/data
sleap-connect legacy worker --room <room-id>     # on the GPU machine
sleap-connect legacy train --room <room-id> ...  # from your machine
sleap-connect legacy track --room <room-id> ...
```

**Docker**

```bash
docker run --gpus all \
  -e SLEAP_RTC_ACCOUNT_KEY=<your-account-key> \
  -v /path/to/data:/app/shared_data \
  ghcr.io/talmolab/sleap-rtc:latest \
  worker --room <room-id>
```

</details>

## Links

- [SLEAP](https://sleap.ai) — pose estimation framework
- [sleap-nn](https://nn.sleap.ai) — neural network backend
- [sleap-app](https://app.sleap.ai) — SLEAP in the browser and on the desktop
- [Remote compute guide](https://app.sleap.ai/docs/main/guides/remote-compute/) — pairing, connection routes, troubleshooting
- [Dashboard](https://talmolab.github.io/sleap-rtc/dashboard/index.html) — legacy rooms and jobs
