# remote-coder

**Repository Path**: mjsz/remote-coder

## Basic Information

- **Project Name**: remote-coder
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-04
- **Last Updated**: 2026-08-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WebPTY — Remote Terminal System

浏览器/手机上远程操作本地终端，支持 Claude、OpenCode 等 TUI Agent。

## 安装

```bash
# 从 npm
npm install -g webpty

# 或从源码
git clone <repo> && cd webpty && npm install && npm install -g .
```

安装后四个命令：

| 命令 | 作用 |
|------|------|
| `webpty server` | 启动云端服务器 |
| `webpty agent` | 启动本地 Agent，连接服务器 |
| `webpty local` | 启动本地 Web 终端（局域网，不依赖服务器） |
| `webpty coturn` | 一键安装配置 Coturn (STUN/TURN) |

---

## 快速开始

### 1. VPS 上启动服务器

```bash
webpty server --port 4000
```

### 2. 本地启动 Agent

```bash
webpty agent -u myname -p mypass -c claude,opencode -s ws://VPS_IP:4000/ws
```

### 3. 浏览器访问

`http://VPS_IP:4000` → 注册/登录 → 看到 Agent → 点命令按钮

---

## 传输模式

WebPTY 支持两种传输，自动择优：

```
优先 P2P：  Browser ←──WebRTC Data Channel──→ Agent    （STUN 直连，服务器不承载流量）
降级转发：  Browser ←──WS──→ Server ←──WS──→ Agent     （无 P2P 条件时自动兜底）
```

- Agent 有 `node-datachannel` 时启用 P2P，没有时走转发
- 前端 8 秒超时自动降级，对用户透明
- STUN 默认用 Google 免费服务器，也可自建

---

## 命令参考

### `webpty server`

```
-p, --port <port>      端口 (默认 4000)
--stun <url>           STUN 地址 (默认 Google STUN)
--turn <url>           TURN 地址 (可选)
--turn-user <user>     TURN 用户名
--turn-pass <pass>     TURN 密码
```

### `webpty agent`

```
-u, --user <name>      用户名 (必填)
-p, --passwd <pass>    密码 (必填)
-c, --cmd <cmds>       可用命令，逗号分隔 (必填)
-s, --server <url>     服务器地址 (默认 ws://localhost:4000/ws)
-b, --base <dir>       工作目录 (默认当前目录)
```

### `webpty local`

```
-p, --port <port>      端口 (默认 3456)
```

### `webpty coturn`

```bash
# 在 VPS 上一键安装 Coturn，自动配置、启动、开放防火墙
webpty coturn

# 仅 STUN，不做 TURN 中继
webpty coturn --stun-only
```

输出示例：

```
╔══════════════════════════════════════════════╗
║   ✅ Coturn is ready!                       ║
╠══════════════════════════════════════════════╣
║  STUN:  stun:1.2.3.4:3478                   ║
║  TURN:  turn:1.2.3.4:3478                   ║
║  User:  webpty                               ║
║  Pass:  abc123def456...                     ║
╠══════════════════════════════════════════════╣
║  webpty server --stun stun:1.2.3.4:3478 \   ║
║    --turn turn:1.2.3.4:3478 \               ║
║    --turn-user webpty \                     ║
║    --turn-pass abc123def456...              ║
╚══════════════════════════════════════════════╝
```

---

## 信令与认证

| 机制 | 说明 |
|------|------|
| HTTP Session Token | 24h TTL，过期自动清理 |
| Agent 心跳 | 25s 一次，60s 无心跳标离线 |
| Browser WS ping | 30s 一次，断线 3s 重连 |

---

## 一键部署到 VPS

```bash
# 安装 Node.js
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# 安装 WebPTY
npm install -g webpty

# 安装 Coturn (可选，启用 P2P)
webpty coturn

# 启动服务器（systemd 保活）
sudo tee /etc/systemd/system/webpty.service << 'EOF'
[Unit]
Description=WebPTY Cloud Server
After=network.target

[Service]
Type=simple
ExecStart=/usr/bin/webpty server --port 4000
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable webpty --now
```

---

## 卸载

```bash
npm uninstall -g webpty
```