← 返回列表

agent-remote-让你的agent操作远程设备

单站 漏洞推送 发布 Tue, 20 Oct 2026 16:31:00 +0800 入库 2026-11-18T07:14:02

漏洞推送 2026-10-20 16:31 浙江

agent-remote-让你的agent操作远程设备

agent-remote是一个适配本地 pi/codex/claude等agent,具备操作远程homelab或者vps能力的服务,不依赖于rdp、ssh等正向连接服务。即使目标机器没有公网ip并且在有防火墙的情况下,也能实现远程连接。

项目地址: https://github.com/lanyi1998/agent-remote

aremote 支持两种连接方式:

•正向连接:在目标机器上运行 server,Pi 直接连接目标机器。•反向连接:在 本机运行 server,目标机器以 worker 身份主动连接,适用于目标机器有防火墙,连接无法入站的情况。

Pi 扩展会接管 read、bash、edit、write、文件补全和交互式 ! Bash 命令。

对于codex/claudecode/opencode等agent,提供cli和mcp两者方式进行接入。

将扩展复制到 Pi 的自动加载目录:

mkdir -p ~/.pi/agent/extensions/agent-remote

cp pi-extension/index.ts ~/.pi/agent/extensions/agent-remote/index.ts

Gateway 和 Worker 必须使用相同的 Token,Token 长度至少为 8 个字符。

通过 /remote connect 在 Pi 中输入 Token,首次连接成功后会自动保存。

在目标机器上启动 Gateway:

./aremote-linux-amd64 server --token 'replace-with-a-long-random-token'
Pi 内连接:

/remote connect http://TARGET_IP:8787 replace-with-a-long-random-token 我的开发机

/remote status

连接命令不指定 --worker 时,默认操作 Gateway 所在机器。末尾可选文本是显示备注。反向连接的 Worker 可这样选择:

/remote connect http://VPS:8787 replace-with-a-long-random-token --worker office-linux 我的办公机
当 Pi 和目标机器都处于内网时,可以使用以下拓扑:

Pi  --HTTP-->  公网 VPS Gateway  <--WebSocket--  Worker
即使使用 http:// 和 ws://,RPC 内容与 Worker 消息也会使用 AES-256-GCM 加密,并使用带时间戳和随机 nonce 的 HMAC 认证。被动抓包者无法读取 Token、命令、文件内容或执行结果。由于 VPS 持有共享 Token,VPS Gateway 本身仍然可以解密流量。

在 VPS 的云安全组和系统防火墙中放行 TCP 8787。

在公网 VPS 上启动 Gateway:

./aremote-linux-amd64 server \

--token 'replace-with-a-long-random-token' \

在内网目标机器上启动 Worker:

./aremote-linux-amd64 worker \

--token 'replace-with-a-long-random-token' \

--server ws://VPS_PUBLIC_IP:8787 \

--id office-linux

Worker 会主动建立 WebSocket 长连接,并在断线后自动重连。目标机器不需要公网 IP、端口映射或入站防火墙规则。

在 Pi 机器上:

/remote connect http://VPS_PUBLIC_IP:8787 replace-with-a-long-random-token --worker office-linux

/remote status

请求路径为:

Pi -> HTTP -> VPS Gateway -> WebSocket -> office-linux Worker
可以连接多台 Worker,但每台机器的 --id 必须唯一:

/remote office-linux

/remote home-linux

/remote win7-test

/remote                              # 显示 remote 子命令

/remote status                       # 显示当前目标

/remote list                         # 列出已保存连接及在线状态

/remote remove                       # 删除一个已保存连接

/remote refresh                      # 刷新 Worker 信息

/remote off                          # 关闭远程连接

/remote office-linux                 # 选择一个 Worker

/remote connect http://HOST:8787 TOKEN --worker ID [备注]

aremote 可供任意支持命令行或标准 stdio MCP 的 Agent 使用。

使用 CLI 或 MCP 前,先执行一次连接。连接会先校验目标,再将 Token 及连接信息以仅当前用户可读的权限保存到 ~/.agent-remote/config.json:

aremote connect http://HOST:8787 replace-with-a-long-random-token

aremote connect http://HOST:8787 replace-with-a-long-random-token --worker office-linux 我的办公机器

aremote status 显示当前目标。aremote list 显示全部已保存目标及在线状态;在交互式终端中输入编号即可切换活动目标。使用 aremote refresh 重新查询当前目标,使用 aremote remove 交互式删除已保存目标;在脚本中使用 aremote remove TARGET_ID。使用 aremote rename NOTE... 可在不重新连接的情况下修改当前活动目标的备注。

每条已保存目标都有 aremote list 显示的 ID。使用非活动目标时无需改变默认目标,因此多个 Agent 可以并行操作不同机器:

aremote --target target-a1b2c3d4 bash "hostname"
适用于 Agent 通过 Shell 调用 aremote 的场景。先将仓库中的/skills/aremote-cli/安装到 Agent 会扫描的 Skill 目录。

然后在 Agent 对话中显式调用 Skill,进行连接检查:

$aremote 在远程机器上执行id,返回命令结果
codex 加入mcp设置

[mcp_servers.agent-remote]

command = "/opt/homebrew/bin/aremote"

args = ["mcp"]

enabled = true

MCP 同样可以访问任意已保存目标。先调用 remote_targets 获取目标 ID,再在 remote_read、remote_bash 等工具中传入 target。调用 remote_workers 并传入 target 可查看其 Gateway 和 Workers;需要选择该目标下的非默认 Worker 时传入 worker。

构建 Windows 程序前,将运行时文件放在:

internal/runtimebundle/assets/

└── windows_amd64/

└── bin/busybox.exe

Windows 构建目前只支持 amd64。windows_amd64 下除了 _placeholder 以外的文件都会嵌入 aremote.exe。

嵌入的 BusyBox 运行时可用时,Worker 会直接启动 busybox.exe sh -s。ls、id、whoami、grep 和 find 等命令由 BusyBox 处理,不会生成 applet 链接文件。使用的是 BusyBox 的 ash 语法,而不是 Bash 语法,也不会静默切换到 CMD 或 PowerShell。

如果可用,超时和取消会终止 Windows Job Object,同时停止子进程。如果进程无法加入 Job Object,Worker 会退回到直接终止 Bash 进程。

原文链接:https://mp.weixin.qq.com/s?__biz=MzU5MTExMjYwMA==&mid=2247485901&idx=1&sn=6fcb2b61f0f92b0d266feed6aca5ae6d