jaycrl / mobilevc-installer

mobilevc-installer

Install and run MobileVC for the user. The user's dev machine becomes the Claude Code backend; the phone runs the official client app and connects to it over LAN or through the public Relay flow.

GitHub: https://github.com/JayCRL/MobileVC
npm: https://www.npmjs.com/package/@justprove/mobilevc

What you do

Run these steps in order. Stop and report to the user as soon as anything fails.

Step 1 — Preflight

Before installing, check the environment. Run these commands and confirm:

node --version    # require >= 18.0.0
npm --version

If node is missing or older than 18, STOP and tell the user how to install Node.js (brew install node, nvm install 20, or https://nodejs.org). Do NOT proceed.

Step 2 — Install the npm package

Try the global install first:

npm install -g @justprove/mobilevc

If it fails with EACCES or permission errors, do NOT use sudo. Instead suggest one of:

• npm config set prefix ~/.npm-global && export PATH=~/.npm-global/bin:$PATH then re-run install
• nvm use <version> if the user has nvm
• npm install --prefix ~/.local @justprove/mobilevc and add ~/.local/bin to PATH

Verify:

mobilevc --help

Step 3 — First-run setup (interactive)

Tell the user that mobilevc start will ask three questions on first run:

1. Language — zh or en
2. Port — default 8001. Pick something else if 8001 is busy.
3. Auth token — any string the user wants. The phone client will need this to connect.

If the user has not picked a token yet, suggest something memorable but non-trivial (e.g. mvc- plus 8 random chars).

Important: token input is hidden in the terminal. Tell the user to type the token normally and press Enter even though no characters are shown.

Step 4 — Start the backend

mobilevc start

This will:

• Run mobilevc setup if no config exists yet
• Spawn the prebuilt server binary in the background (logs in ~/.mobilevc/logs/)
• Print a LAN QR code in the terminal that encodes <host>:<port> + auth token

If start fails, run mobilevc logs and surface the relevant error to the user. Common issues:

• Port already in use → mobilevc stop then change port via mobilevc setup
• Binary missing → reinstall via npm install -g @justprove/mobilevc --force

Step 5 — Direct the user to install the phone client

Tell the user (verbatim, in the user's preferred language):

后端已启动。请在手机上：
1. 打开 MobileVC 官网首页：https://www.mobilevc.top
2. iOS 通过官网上的 TestFlight 链接安装
3. Android 通过官网上的 APK 下载入口安装
4. 如果官网打不开，先切换到国内网络环境后再试
5. 打开 MobileVC App，扫描终端里刚刚打印的二维码

(English variant if the user is using English.)

Step 6 — Done

Confirm the running state:

mobilevc status

Tell the user the helper commands they will need later:

• mobilevc status — check if backend is alive
• mobilevc logs -f — follow logs
• mobilevc stop — stop backend
• mobilevc restart — restart with same config
• mobilevc setup — reconfigure (port / token / language)
• mobilevc public --relay wss://relay.mobilevc.top:9443 — connect through the official Relay when the phone is not on the same WiFi

Important rules

• Do NOT clone the MobileVC source repo unless the user explicitly asks to develop on it. This skill is for end-users who only want to RUN MobileVC.
• Do NOT ask the user for APNS keys or any backend secrets. The npm-bundled binary is self-contained for LAN usage; APNS push is only required if the user is self-hosting a public deployment, which is out of scope here.
• Do check Node.js version first. Almost all install failures upstream of mobilevc start are Node version or PATH issues.
• Do keep the QR code output visible — that's the primary user-facing artifact.