0 Fork 0

mirror of https://github.com/saphid/frame-control.git synced 2026-10-06 04:04:21 +02:00

Files

T

saphidandClaude Opus 5.5 1f6115b789 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>

2026-09-25 15:38:43 +10:00

4.9 KiB

Raw Blame History

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:

Steam Settings → System → Enable Developer Mode (a toggle, no typing).
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.
(Optional, no typing) Note the IP address from Quick Settings or Steam Settings → Internet, in case frame.local doesn't resolve.
(Optional) Check Steam Settings → System → Hostname. Leaving it as frame means the scripts work without any extra setup.

On the Mac:

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, Valve: Steam Frame 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.

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/streaming.md, docs/file-transfer.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).