Steam Frame from a Mac: research docs and helper scripts

README with the minimum-typing checklist (Developer Mode toggle + Set User
Password; the rest runs from the Mac), docs for SSH, streaming, file
transfer, and open questions with sourced confidence levels, plus Mac-side
zsh helpers and a fallback headset bootstrap.

Scripts are UNTESTED against hardware: checked with zsh -n / bash -n /
shellcheck only. Two SWE-2 Max read-only review passes (devin -p --model
swe-2-max); verified findings fixed.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

README.md

@@ -0,0 +1,92 @@
+# Steam Frame ↔ Mac
+
+This repo holds notes and Mac-side helpers for controlling a Valve Steam Frame
+(standalone VR headset: SteamOS 3, Arch-based, arm64, Snapdragon 8 Gen 3) from
+this Mac, with as little typing on the headset's virtual keyboard as possible.
+
+Status: research written 2026-09-25. **None of the scripts have been run
+against a real Frame yet.** Treat them as untested until the checklist below has
+been done once.
+
+## Minimum typing on the headset
+
+Valve's own developer docs say SSH, ADB, and RDP are all turned on through a
+**UI toggle**. You don't need a terminal, `passwd`, or `systemctl`. The only
+thing you type on the headset is a password you choose.
+
+On the Frame:
+
+1. **Steam Settings → System → Enable Developer Mode** (a toggle, no typing).
+2. Scroll down to the **Developer** section and click **Set User Password**.
+   Type a password. **This is the only thing you type on the headset.** Pick
+   something short, because you'll type it once more on the Mac and then
+   never again.
+3. (Optional, no typing) Note the IP address from **Quick Settings** or
+   **Steam Settings → Internet**, in case `frame.local` doesn't resolve.
+4. (Optional) Check **Steam Settings → System → Hostname**. Leaving it as
+   `frame` means the scripts work without any extra setup.
+
+On the Mac:
+
+```sh
+cd ~/projects/steam-frame
+./scripts/connect.sh              # or: ./scripts/connect.sh 192.168.1.50
+ssh frame                          # passwordless from now on
+```
+
+`connect.sh` does four things:
+
+- finds the headset (`frame.local`, then `frame`, or the IP/host you pass in)
+- creates a dedicated key (`~/.ssh/id_ed25519_frame`)
+- adds a `Host frame` block to `~/.ssh/config`
+- runs `ssh-copy-id`, which asks for the Developer Mode password once
+
+Run `./scripts/connect.sh --harden` later if you want to turn off SSH password
+logins.
+
+Sources: [Valve: Setting up your Steam Frame for development](https://partner.steamgames.com/doc/steamhardware/steamframe/setup),
+[Valve: Steam Frame Debugging](https://partner.steamgames.com/doc/steamhardware/steamframe/debugging)
+(both **confirmed on Steam Frame**, Valve official).
+
+**Fallback, only if the Developer Mode toggle doesn't give you SSH.** From the
+Mac, run `./scripts/serve-bootstrap.sh`. It prints a one-liner of about 30
+characters, like `curl -fsS mac.local:8765|bash`, to type into Konsole on the
+Frame's Linux desktop. The script it serves installs your Mac's public key and
+enables `sshd`. See [docs/ssh.md](docs/ssh.md#fallback-bootstrap-one-liner).
+
+## Recommended options
+
+| Goal | Recommended | Confidence |
+|---|---|---|
+| Shell on the Frame | `ssh frame` (user `steamos`) | Confirmed (Valve docs) |
+| **See/control the Frame from the Mac** | **Steam Link for macOS → connect to `frame`** (Valve names this). Alternatives: RDP to `xrdp` with Microsoft *Windows App* for the Linux desktop, or `adb`/`scrcpy` for the Android (Lepton) layer only | Steam Link and xrdp confirmed on Frame; the Mac RDP client is inferred |
+| **Show the Mac's desktop inside the Frame** | **macOS Screen Sharing (built-in VNC) → Remmina (Flatpak, aarch64) on the Frame's Linux desktop**, installed over SSH | Inferred: each piece is documented, but the combination hasn't been tested on a Frame |
+| File transfer | `scp` / `rsync` over the `frame` alias (`scripts/push.sh`) | Inferred from confirmed SSH |
+| Paste Mac clipboard into the headset | `scripts/paste-to-frame.sh` (`pbpaste` → `ssh` → `wl-copy`), or the clipboard sync in an RDP session | Inferred / untested |
+
+Details: [docs/ssh.md](docs/ssh.md), [docs/streaming.md](docs/streaming.md),
+[docs/file-transfer.md](docs/file-transfer.md),
+[docs/open-questions.md](docs/open-questions.md).
+
+## Scripts (all untested against hardware)
+
+| Script | Runs on | Purpose |
+|---|---|---|
+| `scripts/connect.sh` | Mac | Discover, set up key and `~/.ssh/config`, copy key, optional `--harden` |
+| `scripts/install-apps.sh` | Mac → Frame | Install Flatpaks (Remmina, Moonlight, …) on the Frame over SSH as `--user` |
+| `scripts/paste-to-frame.sh` | Mac → Frame | Send the Mac clipboard (or stdin) to the Frame clipboard |
+| `scripts/push.sh` | Mac → Frame | `rsync` files to `~/Downloads` (or a given path) on the Frame |
+| `scripts/serve-bootstrap.sh` | Mac | Fallback: serve `bootstrap-on-frame.sh` with your public key embedded |
+| `scripts/bootstrap-on-frame.sh` | Frame | Fallback: install the key and enable `sshd` |
+
+## Security notes
+
+- With Developer Mode on, `sshd`, ADB (Wi-Fi, port 5555, while a Lepton
+  session is running), and xrdp are all reachable on your LAN. Use trusted
+  networks only. Turn Developer Mode off when you don't need it.
+- `steamos` has `sudo`, protected by the same Developer Mode password. Once
+  you've switched to key auth, a short password still protects `sudo` and
+  RDP, so pick one that isn't trivially guessable.
+- Don't port-forward 22, 3389, or 5555 from your router. For remote access,
+  use Tailscale (Flatpak/package availability for the Frame hasn't been
+  checked).