zterm-daemon

ZTerm daemon for macOS. It runs the local WebSocket bridge used by the ZTerm Android app to connect to local tmux sessions, transfer files, and capture remote screenshots through the installed daemon permission owner.

Requirements

• macOS arm64
• Node.js 20+
• tmux available on PATH
• For remote screenshot: grant Screen Recording permission to the installed zterm-daemon native binary when macOS prompts

Install

npm install -g @jsonstudio/zterm-daemon
printf '%s
' "$RELAY_PASSWORD" | zterm-daemon configure-relay \
  --relay-url "$RELAY_BASE_URL" \
  --username "$RELAY_USERNAME" \
  --password-stdin \
  --host-id "$(hostname -s)" \
  --device-id "$(hostname -s)" \
  --device-name "$(hostname)"
zterm-daemon install-service
zterm-daemon service-status

The relay password must come from a local secret manager, shell secret, or CI secret. The configure command only prints passwordSet=true; it must not echo the password.

The installer uses these locations:

• runtime/config/logs: ~/.wterm
• CLI: npm global bin zterm-daemon
• legacy alias: npm global bin wterm
• launch agent: ~/Library/LaunchAgents/com.zterm.android.zterm-daemon.plist

Commands

zterm-daemon run               # run in foreground
zterm-daemon start             # start launchd service
zterm-daemon status            # direct runtime status
zterm-daemon stop              # stop launchd service
zterm-daemon restart           # restart launchd service
zterm-daemon configure-relay   # write ~/.wterm/config.json mobile.relay from secret input
zterm-daemon install-service   # install and start launchd service
zterm-daemon uninstall-service # stop and remove launchd service
zterm-daemon service-status    # launchd service status

wterm daemon <command> is kept as a compatibility alias.

Configuration

Optional config file: ~/.wterm/config.json.

{
  "zterm": {
    "android": {
      "daemon": {
        "host": "0.0.0.0",
        "port": 3333,
        "authToken": "change-me"
      }
    }
  }
}

Relay account configuration should be written through the global CLI, not by hand-editing scattered daemon files. The command shape is zterm-daemon configure-relay --relay-url ... --username ... --password-stdin --host-id ...:

printf '%s
' "$RELAY_PASSWORD" | zterm-daemon configure-relay \
  --relay-url "$RELAY_BASE_URL" \
  --username "$RELAY_USERNAME" \
  --password-stdin \
  --host-id "mac-studio" \
  --device-id "mac-studio" \
  --device-name "Mac Studio"

Successful output contains passwordSet=true and never prints the relay password.

Environment variables override config:

• ZTERM_HOST
• ZTERM_PORT
• ZTERM_AUTH_TOKEN
• ZTERM_DAEMON_SESSION

Android connection

In the ZTerm Android app, create a connection pointing at your Mac host/IP and daemon port, usually 3333. If your Mac and phone are connected by Tailscale, use the Mac Tailscale IP.

Remote screenshot permission

Remote screenshot permission belongs to the installed native zterm-daemon binary, not Node.js and not a separate GUI helper. Install the service once, trigger a screenshot from Android, and approve the macOS Screen Recording prompt for zterm-daemon.