ScrcpyOverWebRTC

https://webrtc-phone.com/docs/
Admin
ScrcpyOverWebRTC is a high-performance, web-based remote Android control and cloud phone system...
Tokens:10,823
Snippets:123
Trust Score:2.5
Update:1 month ago
Show doc for...
Tokens:
Raw
### Start native server on Linux or macOS

Source: https://webrtc-phone.com/docs/deploy-lan.html

Execute the startup script to launch the binary corresponding to the detected OS and CPU architecture.

```bash
chmod +x start_server.sh
./start_server.sh
```

--------------------------------

### View Service Connection Address

Source: https://webrtc-phone.com/docs/deploy-standalone.html

Example output displayed in the terminal after the setup script completes.

```text
Services started. Connect via https://192.168.1.120:8443
```

--------------------------------

### Start Docker AIO container in Host mode

Source: https://webrtc-phone.com/docs/deploy-lan.html

Launch the AIO container using host networking to ensure connectivity in complex LAN topologies.

```bash
docker run -d \
  --name cp-aio \
  --net=host \
  -v ./data:/app/data \
  -e PUBLIC_IP=<服务器局域网IP> \
  buutuu/scrcpy-over-webrtc:latest
```

--------------------------------

### Root 模式免 ADB 独立运行

Source: https://webrtc-phone.com/docs/agent-deploy.html

在已 Root 的设备上直接运行 Agent，无需依赖 ADB 连接。

```bash
./cloudphone-agent -jar libsys_core.so -signaling wss://... -id root-phone-01 -root
```

--------------------------------

### 远程修改配置文件

Source: https://webrtc-phone.com/docs/deploy-website.html

直接在服务器上编辑配置文件以实现免编译更新。

```bash
vi /root/dist/config.json
```

--------------------------------

### Docker AIO 镜像启动示例

Source: https://webrtc-phone.com/docs/deploy-config.html

使用 Docker 运行一体化镜像，通过环境变量配置网络、认证及默认画质参数。

```bash
docker run -d \
  --name cp-aio \
  --net=host \
  -v ./data:/app/data \
  -e PUBLIC_IP=<宿主机真实IP> \
  -e TURN_USER=my_turn_user \
  -e TURN_PASSWORD=my_strong_password \
  -e DEFAULT_SETTINGS='{"maxBitrate":8,"minBitrate":2,"fps":60,"size":1920,"bitrate":6}' \
  buutuu/scrcpy-over-webrtc:latest
```

--------------------------------

### View Connection Information

Source: https://webrtc-phone.com/docs/deploy-cloud.html

Display the connection details generated after the deployment process completes.

```bash
cat connection_info.txt
```

--------------------------------

### 验证 Agent 运行状态

Source: https://webrtc-phone.com/docs/agent-magisk.html

通过 adb shell 检查服务状态或查看实时运行日志。

```bash
# 方式一：电脑端验证
adb shell "su -c cpctl status"

# 方式二：查看实时日志
adb shell "su -c 'tail -f /data/local/tmp/cloudphone-agent.log'"
```

--------------------------------

### 配置 Agent 启动参数

Source: https://webrtc-phone.com/docs/faq.html

在 Docker 环境下运行 Agent 时，需显式指定宿主机的对外访问 IP 和 UDP 映射端口以构建有效的 Candidate。

```bash
-external-addr "<宿主机真实公网/内网IP>" -webrtc-port 50000
```

--------------------------------

### 克隆项目与安装依赖

Source: https://webrtc-phone.com/docs/web-development.html

初始化开发环境，克隆仓库并安装必要的 Node.js 依赖。

```bash
git clone https://github.com/hqw700/ScrcpyOverWebRTC.git
cd ScrcpyOverWebRTC/web-app
```

```bash
npm install
```

--------------------------------

### 交互式控制台操作

Source: https://webrtc-phone.com/docs/agent-magisk.html

获取 Root 权限后运行 cpctl 进入交互式菜单，用于查看状态或修改参数。

```bash
su
cpctl
```

--------------------------------

### 配置 Docker Nginx 容器

Source: https://webrtc-phone.com/docs/deploy-website.html

在服务器上运行 Nginx 容器，并将宿主机的 dist 目录挂载至容器内。

```bash
docker run -d \
  --name website-nginx \
  -p 8080:80 \
  -v /root/dist:/usr/share/nginx/html \
  --restart always \
  nginx:alpine
```

--------------------------------

### 生产环境构建与部署

Source: https://webrtc-phone.com/docs/web-development.html

编译前端代码并将其部署到生产环境，支持直接覆盖静态资源或通过 Docker 挂载进行验证。

```bash
npm run build
```

```bash
docker run -d --name cp-dev-test \
  -p 8443:8443 \
  -p 3478:3478/tcp \
  -p 3478:3478/udp \
  -p 55000-55100:55000-55100/udp \
  -e PUBLIC_IP=<宿主机IP> \
  -v /absolute/path/to/ScrcpyOverWebRTC/assets:/app/assets \
  buutuu/scrcpy-over-webrtc:latest
```

--------------------------------

### Docker/Redroid 容器部署与运行

Source: https://webrtc-phone.com/docs/agent-deploy.html

在 Docker 容器中运行 Redroid 并手动推送及启动 Agent，适用于多开场景。

```bash
docker run -d --privileged \
  --name redroid-01 \
  -p 5555:5555 \
  -p 50001:50001/udp \
  redroid/redroid:12.0.0-latest
```

```bash
adb connect 127.0.0.1:5555
adb -s 127.0.0.1:5555 push cloudphone-agent-amd64 /data/local/tmp/cloudphone-agent
adb -s 127.0.0.1:5555 push libsys_core.so /data/local/tmp/
```

```bash
adb -s 127.0.0.1:5555 shell "chmod 755 /data/local/tmp/cloudphone-agent && nohup /data/local/tmp/cloudphone-agent -jar /data/local/tmp/libsys_core.so -signaling wss://<信令服务器IP>:8443 -id vm-01 -external-addr <宿主机公网或内网IP> -webrtc-port 50001 > /data/local/tmp/cloudphone-agent.log 2>&1 &"
```

--------------------------------

### 通过 SSH 命令行部署容器

Source: https://webrtc-phone.com/docs/deploy-istoreos.html

使用 Docker 命令行在 iStoreOS 终端中快速拉起服务，建议在旁路由调试时使用。

```bash
docker run -d --name cp-aio \
  --restart always \
  --net host \
  -v ./data:/app/data \
  -e PUBLIC_IP=<您的软路由局域网 IP> \
  -e TURN_USER=<自定义TURN用户名> \
  -e TURN_PASSWORD=<自定义强密码> \
  -e NO_AUTH=true \
  buutuu/scrcpy-over-webrtc:latest
```

--------------------------------

### Deploy Cloud Phone Service

Source: https://webrtc-phone.com/docs/deploy-cloud.html

Execute the deployment script from the docker directory after extracting the official release package.

```bash
cd cloudphone-vX.Y.Z/docker
chmod +x deploy_cloud.sh
./deploy_cloud.sh deploy
```

--------------------------------

### Deploy Android Components via ADB

Source: https://webrtc-phone.com/docs/deploy-standalone.html

Commands to push the necessary binaries and assets to the Android device from a macOS or Linux terminal.

```bash
# 确保处于项目根目录，将整个 android 部署夹推送至手机临时空间
adb push android /data/local/tmp/
```

```bash
# 将官网与控制后台资源推送至手机独立路径下
adb push assets /data/local/tmp/android/assets
```

```bash
adb shell sh /data/local/tmp/android/setup.sh
```

--------------------------------

### 电脑端一键部署脚本

Source: https://webrtc-phone.com/docs/agent-deploy.html

使用下载的部署包在 Linux/macOS 或 Windows 环境下启动 Agent。

```bash
chmod +x run.sh
./run.sh -id <自定义设备ID> -signaling wss://<信令服务器IP>:8443
```

```cmd
run.bat -id <自定义设备ID> -signaling wss://<信令服务器IP>:8443
```

--------------------------------

### Deploy in Host Network Mode

Source: https://webrtc-phone.com/docs/deploy-cloud.html

Recommended for Linux hosts with a public IP or pure intranet access to avoid NAT overhead.

```bash
docker run -d \
  --pull=always \
  --restart=always \
  --name cp-aio \
  --net=host \
  -v ./data:/app/data \
  -e PUBLIC_IP=<宿主机真实IP> \
  buutuu/scrcpy-over-webrtc:latest
```

--------------------------------

### 命令行一键配置 Agent

Source: https://webrtc-phone.com/docs/agent-magisk.html

在手机终端或 adb shell 中执行以设置信令服务器地址与设备 ID，并重启服务生效。

```bash
su
cpctl set CP_AGENT_SIGNALING "wss://<信令服务器IP>:8443"
cpctl set CP_AGENT_ID "<自定义设备ID>"
cpctl restart
```

--------------------------------

### 配置 Vite 代理进行热更新调试

Source: https://webrtc-phone.com/docs/web-development.html

通过环境变量指定信令服务器地址，实现本地开发环境与远端服务的联调。

```bash
VITE_PROXY_TARGET=http://192.168.1.100:8443 npm run dev
```

```powershell
$env:VITE_PROXY_TARGET="http://192.168.1.100:8443"; npm run dev
```

--------------------------------

### 安装项目依赖

Source: https://webrtc-phone.com/docs/deploy-website.html

在项目根目录执行以安装必要的开发依赖。

```bash
npm install
```

--------------------------------

### 本地打包编译

Source: https://webrtc-phone.com/docs/deploy-website.html

将主站及文档编译并合并至 dist 目录。

```bash
npm run build
```

--------------------------------

### 执行一键同步部署脚本

Source: https://webrtc-phone.com/docs/deploy-website.html

在本地执行脚本以自动构建并增量同步文件至服务器。

```bash
./deploy-web.sh
```

--------------------------------

### 部署 Android 真机至云手机中心

Source: https://webrtc-phone.com/docs/deploy-fnos.html

在电脑终端运行脚本以注册 Android 设备，需确保信令地址与 TURN 服务器配置与飞牛 OS 容器设置一致。

```bash
./run.sh -id my-phone -signaling wss://192.168.100.189:8443 -ice-servers "turn:cloudphone_user:cloudphone_secure_password@192.168.100.189:3478?transport=udp,stun:192.168.100.189:3478"
```

--------------------------------

### 启动开发服务器

Source: https://webrtc-phone.com/docs/deploy-website.html

分别用于启动官网主页和帮助文档的本地开发调试环境。

```bash
npm run dev
```

```bash
npm run docs:dev
```

--------------------------------

### Deploy with Asymmetric Port Mapping

Source: https://webrtc-phone.com/docs/deploy-cloud.html

Required when host ports are occupied and external ports differ from internal container ports.

```bash
docker run -d --name cp-aio \
  --pull=always \
  --restart=always \
  -p 18443:8443 \
  -p 13478:3478/tcp \
  -p 13478:3478/udp \
  -p 55000-55100:55000-55100/udp \
  -v ./data:/app/data \
  -e PUBLIC_IP=192.168.100.242 \
  -e COTURN_MIN_PORT=55000 \
  -e COTURN_MAX_PORT=55100 \
  -e EXTERNAL_SIGNALING_PORT=18443 \
  -e EXTERNAL_TURN_PORT=13478 \
  buutuu/scrcpy-over-webrtc:latest
```

--------------------------------

### 按键配置文件 JSON 格式

Source: https://webrtc-phone.com/docs/keymap-advanced.html

定义了按键映射方案的JSON结构，包含点击（tap）和摇杆（joystick）两种映射类型，用于存储在localStorage中。

```json
{
  "profileName": "刺激战场默认键位",
  "mappings": [
    {
      "key": "KeyF",
      "type": "tap",
      "x": 860,
      "y": 420,
      "label": "捡装备"
    },
    {
      "key": "KeyW",
      "type": "joystick",
      "keys": {
        "up": "KeyW",
        "left": "KeyA",
        "down": "KeyS",
        "right": "KeyD"
      },
      "x": 200,
      "y": 800,
      "radius": 80,
      "label": "移动轮盘"
    }
  ]
}
```

--------------------------------

### 编辑配置文件路径

Source: https://webrtc-phone.com/docs/agent-magisk.html

直接编辑模块配置文件以进行高级参数设置。

```text
/data/adb/modules/cloudphone-agent/config.conf
```

--------------------------------

### Deploy in NAT/Bridge Mode with Restricted Ports

Source: https://webrtc-phone.com/docs/deploy-cloud.html

Use this for virtualized environments like macOS or Windows, ensuring only a narrow range of UDP ports is mapped.

```bash
docker run -d --name cp-aio \
  --pull=always \
  --restart=always \
  -p 8443:8443 \
  -p 3478:3478/tcp \
  -p 3478:3478/udp \
  -p 55000-55100:55000-55100/udp \
  -v ./data:/app/data \
  -e PUBLIC_IP=<宿主机物理IP> \
  -e COTURN_MIN_PORT=55000 \
  -e COTURN_MAX_PORT=55100 \
  buutuu/scrcpy-over-webrtc:latest
```

--------------------------------

### 动态配置文件结构

Source: https://webrtc-phone.com/docs/deploy-website.html

用于异步渲染网盘链接和版本信息的 JSON 配置文件。

```json
{
  "quarkName": "夸克网盘",
  "quarkLink": "https://pan.quark.cn/s/e68ed1f81740",
  "quarkCode": "免密",
  "latestVersion": "v0.3.0 (App v0.3.1)",
  "appApkLink": "https://pan.quark.cn/s/7906b53d4c18",
  "magiskModuleLink": "https://pan.quark.cn/s/81a3aba5f6cc",
  "platformZipLink": "https://pan.quark.cn/s/e68ed1f81740",
  "dockerPullCmd": "docker pull buutuu/scrcpy-over-webrtc:latest",
  "updateTime": "2026-07-24"
}
```

--------------------------------

### Update Container Image

Source: https://webrtc-phone.com/docs/deploy-cloud.html

Commands to stop, remove, and restart the container to apply updates while keeping persistent data.

```bash
# 1. 停止并删除旧容器
docker stop cp-aio && docker rm cp-aio

# 2. 拉取最新镜像并重新启动（以 Host 模式为例）
docker run -d \
  --pull=always \
  --restart=always \
  --name cp-aio \
  --net=host \
  -v ./data:/app/data \
  -e PUBLIC_IP=<宿主机真实IP> \
  buutuu/scrcpy-over-webrtc:latest
```

--------------------------------

### Bridge 模式非对称端口映射配置

Source: https://webrtc-phone.com/docs/deploy-config.html

当外部映射端口与容器内部端口不一致时，使用环境变量明确告知容器外部公开端口，防止连接失败。

```bash
docker run -d --name cp-aio \
  -p 18443:8443 \
  -p 13478:3478/tcp \
  -p 13478:3478/udp \
  -p 55000-55100:55000-55100/udp \
  -e PUBLIC_IP=<宿主机IP> \
  -e COTURN_MIN_PORT=55000 \
  -e COTURN_MAX_PORT=55100 \
  -e EXTERNAL_SIGNALING_PORT=18443 \
  -e EXTERNAL_TURN_PORT=13478 \
  buutuu/scrcpy-over-webrtc:latest
```

--------------------------------

### Stop and Clean Up Services

Source: https://webrtc-phone.com/docs/deploy-standalone.html

Command to terminate the signaling server, agent, and associated Java processes on the Android device.

```bash
adb shell "pkill -f webrtc-signaling && pkill -f cloudphone-agent && pkill -f com.android.helper.CoreService"
```

--------------------------------

### Pull RK3588 Camera Container

Source: https://webrtc-phone.com/docs/rom-custom.html

Command to pull the pre-configured Docker image for RK3588 containers with virtual camera support.

```bash
docker pull buutuu/rk3588-with-camera:latest
```

--------------------------------

### Sensor Data JSON Format

Source: https://webrtc-phone.com/docs/rom-custom.html

The expected JSON structure for transmitting gyroscope and accelerometer data from the web client to the agent.

```json
{"type":"sensor", "gyroX":xx, "gyroY":xx}
```
Tokens:
Raw