Repository navigation
Run macOS apps on a hosting Mac with stim macos --host #2475
Copy link
Copy link
Closed
Description
Track C of #2403. Contracts: contracts comment, sections 4 and 5. Shared types: #2472.
Problem
There is no client command that places a macOS app on an approved hosting Mac. No client code drives the device-host.* protocol at all: hosting.machines and stim doctor --fix only obtain the approval. Desktop and the phone talk only to their local stim-server, so they cannot show a hosted session.
Evidence
packages/stim-cli/src/commands/macos.tsbuilds and launches locally only.- The client connection code to reuse is
BuildConnectioninpackages/stim-cli/src/offload/client.ts: a pinnedwssconnection, hello with the token, and a capability check. Also reusepinnedEndpointinoffload/tailnet.tsandreadDeviceHostMachinesin core/state. - The
HostedMacosPlacement/HostedAgentAccesstypes land in feat: add hosted macOS app contracts #2472.
Fix idea / scope
stim macos --host <machine> [--json], a flag approved for this stack by the maintainer's Offload native macOS builds and host app windows on another Mac #2403 request:- Resolve the approved credential and pinned endpoint. Refuse anything else, and never fall back to a local launch.
- Build locally and stage the bundle with its base
CFBundleIdentifier. - Attach to the session recorded in workspace state, or reserve one with a fresh attempt. Wait for
ready. - Offer the manifest, upload the missing chunks, launch, and poll
app.attach. - Record
macos.hostand print the contract payload. Write agent files only from a non-nonegrant.
stim statusandstim stop/worktree removecover hosted placements. Stop sendsdevice-host.stopand removes the agent files.- A client stim-server relay: for
frames.subscribe,control.*andinput.*on{ workspace, platform: 'macos' }withmacos.host, the local server opens the pinned device-host connection and relays. Desktop needs only the existing macOS viewer route. The phone gets the same route through its paired server, if cheap. - Update the guide (
stim guide agentrouting plus the macOS topic) and website docs. Agents stop usingmini-desktop.shonce Host prebuilt macOS apps in owned device-host sessions #2473, Stream and control hosted macOS apps #2474 and Run macOS apps on a hosting Mac with stim macos --host #2475 land.
Acceptance
- Unit tests with a fake host connection: reserve, deliver, launch and stop; an unapproved or changed node is refused; JSON stdout stays a single payload.
- A real two-Mac run (MacBook client, mini host, tailnet only, no SSH): build, launch, view in Desktop, click, stop.
Out of scope
Remote builds (#2476) and the agent driver (#2477).
Depends on #2473 for the end-to-end run. CLI and relay plumbing can start now against the contracts with a fake host.
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
No labels
Activity
janicduplessis commentedon Oct 5, 2026
Claimed: feat/2475-hosted-macos-client
janicduplessis commentedon Oct 7, 2026
Backlog triage: the CLI placement flow landed in 9a2b135 (#2481), the Desktop/phone relay in 90fdda5 (#2483), and host streaming/control in 3db30ee (#2485). The current flag is
--remote(renamed by b9a1d91).Recorded real two-Mac evidence in #2483 covers tailnet-only build/launch, live Desktop frames, relayed click/typing, and stop: #2483 . #2477 additionally records hosted fixture and Desktop app operation and teardown. On 43395b6,
pnpm test packages/stim-cli/src/__tests__/hosted-agent-driver.test.ts packages/stim-cli/src/__tests__/hosted-macos-client.test.tspassed 50 tests. Closing the completed issue; real phone/macOS-control acceptance remains separately tracked in #2410.