Back to the Xike blog

Pilot setup · Skill v0.2

Install Xieke Phone on Windows, Mac, or NAS

Connect a 4G modem with a SIM to your host, then test calls and texts in Xieke Phone on an iPhone or iPad. One Skill covers all three setup paths.

Download the setup SkillZIPExplore Xieke Phone

What you need for the pilot

  • A 4G USB modem confirmed to support voice and SMS, a SIM with those services enabled, and a host that can stay online.
  • A pilot account, a configuration supplied separately by your service provider, a trusted SHA-256 for its manifest, and a gateway image that matches your CPU architecture.
  • Access to the Xieke Phone pilot app on your iPhone or iPad. The public ZIP contains preflight tools, guides, and deployment scripts. The app, account, and image are supplied separately.

Waiting for the pilot configuration? You can still run the device checks. Share the platform, CPU architecture, modem model, and blocker. Keep SIM numbers, configuration files, and keys private.

Let WorkBuddy guide the setup

In WorkBuddy, open Skills → Add Skill → Upload Skill and select the ZIP. To use your terminal instead, extract the ZIP and run the commands below from the Skill directory.

Use xieke-phone-gateway to set up this host. The 4G modem is plugged in. Check the platform and device first, and tell me where setup stops if anything is missing.
WorkBuddy import guide

Choose the host your modem is plugged into

Windows

windows-wsl
  1. Plug the modem into a Windows 11 x64 PC and run the PowerShell preflight below. You can also open the pilot EXE in the ZIP to check the host and prepare missing components when prompted.
  2. Set up a dedicated Ubuntu 24.04 WSL 2 distribution with local Docker Engine and the Compose plugin. Use usbipd list to identify the current Bus ID, then follow Microsoft’s instructions to share and attach the idle modem. Use the ID reported by your own host.
  3. Open the Skill directory inside WSL and run the Linux preflight. Confirm the control interface and both audio directions belong to the same modem. Store the pilot configuration on the WSL Linux filesystem.

Windows PowerShell

powershell.exe -NoProfile -File .\scripts\preflight-windows.ps1

Keep a WSL terminal open and identify the idle modem before sharing it. Use the ID shown by usbipd list. The first bind requires administrator privileges.

usbipd list
usbipd bind --busid <BUS-ID>
usbipd attach --wsl --busid <BUS-ID>

Inside the gateway’s Linux environment

python3 scripts/preflight-linux.py --target windows-wsl --json
Microsoft’s USB/IP guide

Mac

macos-vm
  1. Run the Mac preflight below to identify your CPU, modem, and virtualization software. Use an amd64 Linux guest and image on Intel Macs, or arm64 on Apple silicon.
  2. Create a dedicated Ubuntu VM that supports USB passthrough. Attach the entire modem using the VM’s USB menu. Prepare Python 3, Docker Engine, and the Compose plugin inside the guest. Seeing the device on macOS alone is not enough.
  3. Copy the Skill directory into the guest and run the Linux preflight there. Confirm that the modem’s control interface, recording node, and playback node are available. The gateway runs inside the VM.

Mac terminal

python3 scripts/preflight-macos.py --json

Inside the gateway’s Linux environment

python3 scripts/preflight-linux.py --target macos-vm --json
UTM USB passthrough guide

NAS

fnos
  1. Plug the modem into the fnOS or compatible Linux NAS that will run the gateway. Open the Skill directory in a local terminal or an authorized SSH session on that NAS.
  2. Confirm that the NAS can access its local Docker Engine and Compose plugin, then run the preflight below. Seeing the device or the Docker dashboard does not establish that modem control, capture, and playback are available.
  3. Use a gateway image and configuration that match the NAS architecture and modem. Some modems need a dedicated voice integration. Resolve missing interfaces before continuing.

NAS terminal

python3 scripts/preflight-linux.py --target fnos --json
fnOS access and SSH guide

Deploy the gateway with your own configuration

Run these commands inside WSL 2 on Windows, inside the Linux guest on Mac, or directly on the NAS. Store the configuration in a private Linux directory (0700) and set .env to 0600. Replace the example directory, the manifest hash supplied separately by your provider, and the target.

profile_dir="$HOME/xieke-phone-pilot"
manifest_sha256='<trusted-64-character-SHA256>'
target='windows-wsl'  # macos-vm / fnos

python3 scripts/verify-profile.py --profile "$profile_dir" --manifest-sha256 "$manifest_sha256" --target "$target" &&
python3 scripts/deploy-linux.py plan --profile "$profile_dir" --manifest-sha256 "$manifest_sha256" --target "$target"

Verify the configuration and inspect the plan. Check the project name, architecture, and device paths before starting the gateway and checking its status.

python3 scripts/deploy-linux.py apply --profile "$profile_dir" --manifest-sha256 "$manifest_sha256" --target "$target" &&
python3 scripts/deploy-linux.py status --profile "$profile_dir" --manifest-sha256 "$manifest_sha256" --target "$target"

To undo the pilot install, use the same environment and arguments and replace apply with rollback. Rollback keeps the project’s data volumes.

Test these features after the container starts

  • After the app registers, test incoming and outgoing calls to a regular number. Check that both sides can hear each other.
  • During a call with a voice menu, press a key and verify that the menu responds.
  • With the device locked, test incoming calls, answering, and audio. Then test sending and receiving SMS, lock-screen alerts, and message content after unlocking.
  • Unplug and reattach the modem or restart the host, then retest. If device paths have changed, have your provider update the pilot configuration.

This is a pilot setup. Device detection, container status, and app registration are separate checks. Confirm each feature with a real call or message, and validate your specific modem, NAS, and VM combination.