Skip to content

Run macOS apps on a hosting Mac with stim macos --host #2475

Closed

Description

@janicduplessis

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.ts builds and launches locally only.
  • The client connection code to reuse is BuildConnection in packages/stim-cli/src/offload/client.ts: a pinned wss connection, hello with the token, and a capability check. Also reuse pinnedEndpoint in offload/tailnet.ts and readDeviceHostMachines in core/state.
  • The HostedMacosPlacement / HostedAgentAccess types land in feat: add hosted macOS app contracts #2472.

Fix idea / scope

  1. 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.host and print the contract payload. Write agent files only from a non-none grant.
  2. stim status and stim stop / worktree remove cover hosted placements. Stop sends device-host.stop and removes the agent files.
  3. A client stim-server relay: for frames.subscribe, control.* and input.* on { workspace, platform: 'macos' } with macos.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.
  4. Update the guide (stim guide agent routing plus the macOS topic) and website docs. Agents stop using mini-desktop.sh once 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.

Activity

  1. janicduplessis commented on Oct 5, 2026

    @janicduplessis
    CollaboratorAuthor

    Claimed: feat/2475-hosted-macos-client

  2. janicduplessis commented on Oct 7, 2026

    @janicduplessis
    CollaboratorAuthor

    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.ts passed 50 tests. Closing the completed issue; real phone/macOS-control acceptance remains separately tracked in #2410.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions