mirror of
https://github.com/saphid/frame-control.git
synced 2026-10-06 08:00:32 +02:00
saphidandClaude Opus 5.5
1f6115b789
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>
93 lines
4.9 KiB
Markdown
93 lines
4.9 KiB
Markdown
# 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).
|