Terminal-First Remote Control

Product Documents

• Product design
• Technical design
• iOS to macOS installable MVP implementation
• Feature implementation principles
• External network access design
• Server minimal external security design
• Installable MVP implementation plan
• External network cloud relay plan
• Server minimal external security plan
• Feature delivery tracking
• Feature log
• Cloud relay dev deploy runbook
• Cloud test environment runbook
• External network smoke test runbook
• TestFlight build runbook
• macOS Agent desktop runbook
• Release readiness audit

Local MVP Foundation

This workspace uses pnpm through Corepack. Set it up and install dependencies:

corepack enable
corepack prepare pnpm@9.15.0 --activate
pnpm install

If pnpm --version already reports 9.15.0, the corepack prepare step is optional.

iOS Simulator and Local Development

Start the development server. By default it listens on 127.0.0.1:8787:

pnpm dev:server

Start the macOS Agent:

REMOTE_DEVICE_ID=mac-dev pnpm dev:agent

Or start the Electron desktop Agent shell:

REMOTE_DEVICE_ID=mac-dev pnpm --filter @remote/agent-desktop dev

Start the mobile app:

pnpm dev:mobile

The mobile app defaults to ws://127.0.0.1:8787/ws/mobile, so the iOS simulator works with the local server without extra environment variables.

In the mobile app, tap Connect, type pwd, and tap 发送.

Expected result: terminal output from the macOS Agent appears in the mobile terminal output panel.

For automated simulator smoke testing, start mobile with explicit autoconnect and a marker command:

EXPO_PUBLIC_REMOTE_AUTOCONNECT=1 \
EXPO_PUBLIC_REMOTE_SMOKE_COMMAND='printf "__APP_SIM__%s\n" "$PWD"' \
pnpm --filter @remote/mobile exec expo start --ios --localhost --port 8081

Expected result: the simulator opens a terminal session and prints a marker like __APP_SIM__/Users/<name>.

Physical Device Development

Detailed iPhone steps are in Physical iPhone to Mac Runbook.

Start the server on all network interfaces:

HOST=0.0.0.0 pnpm dev:server

If the Agent runs on the same development machine as the server, keep its server URL local:

REMOTE_SERVER_URL=ws://127.0.0.1:8787/ws/agent REMOTE_DEVICE_ID=mac-dev pnpm dev:agent

If the Agent runs on another machine, point it at the server's LAN address instead:

REMOTE_SERVER_URL=ws://<dev-machine-lan-ip>:8787/ws/agent REMOTE_DEVICE_ID=mac-dev pnpm dev:agent

Start the mobile app with the development machine's LAN address:

EXPO_PUBLIC_REMOTE_WS_URL=ws://<dev-machine-lan-ip>:8787/ws/mobile pnpm dev:mobile

Cloud Test Environment

Use this when testing the default external-network path:

iPhone on cellular -> Cloud Relay -> home macOS Agent

Follow Cloud Test Environment Runbook.

Core environment variables:

export REMOTE_RELAY_HOST="<relay-host>"
export REMOTE_DEV_TOKEN="<secret>"
export REMOTE_DEVICE_ID="home-mac"

Start the Agent:

REMOTE_SERVER_URL="wss://${REMOTE_RELAY_HOST}/ws/agent" \
REMOTE_DEV_TOKEN="${REMOTE_DEV_TOKEN}" \
REMOTE_DEVICE_ID="${REMOTE_DEVICE_ID}" \
pnpm dev:agent

Start the mobile app:

EXPO_PUBLIC_REMOTE_WS_URL="wss://${REMOTE_RELAY_HOST}/ws/mobile" \
EXPO_PUBLIC_REMOTE_API_URL="https://${REMOTE_RELAY_HOST}" \
EXPO_PUBLIC_REMOTE_DEV_TOKEN="${REMOTE_DEV_TOKEN}" \
EXPO_PUBLIC_REMOTE_DEVICE_ID="${REMOTE_DEVICE_ID}" \
pnpm dev:mobile

Optional Agent environment variables:

• REMOTE_SERVER_URL: Agent relay URL. Defaults to ws://127.0.0.1:8787/ws/agent.
• REMOTE_DEVICE_NAME: Display name reported to the relay. Defaults to the machine hostname.
• SHELL: Shell spawned for terminal sessions. Defaults to /bin/zsh when unset.

Local Verification

Run the workspace checks:

pnpm test
pnpm typecheck
pnpm build

Verify the local vertical slice:

1. Start the server:

   pnpm dev:server

   Confirm it listens on 127.0.0.1:8787.

2. In another terminal, check health:

   curl http://127.0.0.1:8787/health

   Expected:

   {"ok":true}

3. Start the macOS Agent:

   REMOTE_DEVICE_ID=mac-dev pnpm dev:agent

   Confirm it registers with the server.

4. Check registered devices:

   curl http://127.0.0.1:8787/devices

   Expected response includes mac-dev, capabilities ["terminal"], and online: true.

5. Verify terminal routing through the current pairing flow:

   • Use the pairing panel in the mobile app to submit the pairing code printed by the Agent.

   • Approve the pairing request in the Agent terminal.

   • Tap Connect in the mobile app.

   • Run:

     printf "__PWD__%s\n" "$PWD"

   Expected output contains __PWD__. The Agent PTY starts in $HOME by default, so the marker commonly prints __PWD__/Users/<name> on macOS.

   Raw WebSocket probes must include a valid sessionToken. A session.open message without sessionToken is rejected by design.

6. Verify the Expo command does not fail immediately:

   pnpm --filter @remote/mobile exec expo --help

Stop the development server and Agent processes when verification is complete.

Troubleshooting Connect Failures

• Confirm the server is running and listening on the right host. Physical devices need HOST=0.0.0.0 pnpm dev:server.
• Confirm the mobile app uses the matching URL: simulator default ws://127.0.0.1:8787/ws/mobile, physical device EXPO_PUBLIC_REMOTE_WS_URL=ws://<dev-machine-lan-ip>:8787/ws/mobile.
• Check curl http://127.0.0.1:8787/devices and confirm the Agent is listed with online: true.
• Confirm the mobile app device ID matches the Agent ID. The default is mac-dev when you start the Agent with REMOTE_DEVICE_ID=mac-dev.