WorkflowVM 通过 rpyc classic 模式,将 GitHub Actions Runner 变成可远程操控的 Python 环境。所有 Python 协议(with、for、运算符、len()、bool() 等)均透明支持,无需手动序列化。
核心特性
- 免费云算力:无缝对接 GitHub Actions,零成本调度 Ubuntu Runner。
- 透明 RPC:基于 rpyc NetRef,在本地像操作本地对象一样使用远端 Python 对象,上下文管理器、迭代器、运算符自动透传。
- 自动生命周期:自动分配、保活和释放 Runner 资源。
警告:请合理使用,使用本工具可能导致 github 账号被永久封禁。
警告:请合理使用,使用本工具可能导致 github 账号被永久封禁。
警告:请合理使用,使用本工具可能导致 github 账号被永久封禁。
前置准备:GitHub Token
你需要一个具有特定权限的 Classic PAT (Personal Access Token)。 前往 GitHub Developer Settings 生成 Token,并确保勾选以下权限:
repo- 完整仓库访问权限(用于创建 runner 仓库)。workflow- 触发workflow_dispatch(必需,用于调度 Runner)。
快速开始
1. 配置账号池
创建一个 accounts.yml 文件:
accounts:
- username: your-github-username
token: ghp_YOUR_CLASSIC_PAT # 必须包含 repo + workflow 权限
runner_repo: wvm-runner # 将自动创建此仓库
max_concurrent: 5 # 最大并发 runner 数量
server:
host: 0.0.0.0
port: 8765
api_token: "your-server-api-token"
# ws_url: "wss://your-domain.com" # 反代时配置;默认 ws://host:port
2. 初始化 Runner 仓库
workflowvm setup --config accounts.yml
提示:
workflowvm serve启动时也会自动执行初始化检测。
3. 启动服务器
选项 A:直接安装运行
pip install workflowvm
workflowvm serve --config accounts.yml
选项 B:使用 Docker
docker compose up -d
4. SDK 调用示例
from workflowvm import Controller
ctrl = Controller("wss://your-server:8765", token="your-server-api-token")
conn = ctrl.acquire(timeout=120, max_duration=300)
# 访问远端模块
os = conn.modules.os
print(os.system("whoami")) # 在 GitHub Actions runner 上执行
# 上下文管理器(自动透明)
camoufox = conn.modules.camoufox
with camoufox.SyncCamoufox() as browser:
page = browser.new_page()
page.goto("https://example.com")
print(page.title())
conn.close()
rpyc 的 async_() 包装器可用于处理异步方法:
import rpyc
async_fn = rpyc.async_(browser.some_async_method)
result = async_fn()
result.wait()
value = result.value
架构
SDK (调用方)
└─ Controller.acquire() → 返回 rpyc.Connection
└─ 调度服务器 (WebSocket Server + 账号池 + Session 管理)
└─ 调用 GitHub API (workflow_dispatch)
└─ 启动 GitHub Actions Ubuntu runner
└─ agent.py → 主动反连服务器,暴露 rpyc SlaveService
SDK ─── WebSocket ──→ Server ─── WebSocket ──→ Agent
(acquire协商) (字节隧道) (rpyc classic SlaveService)
←─── rpyc 协议字节流 ─────────
Server 仅负责 acquire 握手阶段,之后变为纯字节隧道,rpyc 协议端到端运行在 SDK 与 Agent 之间。SDK 通过 rpyc.Connection 直接访问 Agent 的 Python 环境。
CLI 命令参考
| 命令 | 功能说明 |
|---|---|
workflowvm serve --config <file> |
启动 WebSocket 调度服务器 |
workflowvm setup --config <file> |
初始化并验证所有 Runner 仓库状态 |
workflowvm-agent --server <url> --token <tok> --duration <sec> |
在 Runner 内运行 Agent(通常由 GitHub Workflow 自动执行) |
安全说明
rpyc classic 模式暴露完整 Python 环境(任意代码执行)。WorkflowVM 的使用场景是一次性 GitHub Actions Runner,这是可接受的——用户本来就完全控制 runner 环境。生产部署中,api_token 是唯一访问控制,请妥善保管。
测试
pip install -e ".[dev]"
pytest tests/ -v
Linux DO
Metadata
Release files for workflowvm 0.3.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| workflowvm-0.3.3.tar.gz | 22.0 kB | With provenance | Details for workflowvm-0.3.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| workflowvm-0.3.3-py3-none-any.whl | Python 3 | none | any | Details for workflowvm-0.3.3-py3-none-any.whl |
Total release size: 41.8 kB
Release files / workflowvm-0.3.3.tar.gz
| Download URL | workflowvm-0.3.3.tar.gz |
|---|---|
| Size | 22.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
aab0bcd92a5e66e5cf51344e433417fcdc50437eb43c33ea680b2ba469d8d5dc
|
|
BLAKE2b-256 checksum How to use checksums |
b21d2857b5c106050365f8ceca8aece88fa4206c0033c954f907af5d3631f715
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 11, 2026.
Transparency logRelease files / workflowvm-0.3.3-py3-none-any.whl
| Download URL | workflowvm-0.3.3-py3-none-any.whl |
|---|---|
| Size | 19.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
66e0156307ab4f728b4de4b7486fb0b3835620a5ba6c08362cb1c8d5a4622843
|
|
BLAKE2b-256 checksum How to use checksums |
aaf32278ba4bc976edcf11f7668caa7dfb7c58c819bae31e3f9a4aaad388aa3a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 11, 2026.
Transparency logSecurity for workflowvm 0.3.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for workflowvm-0.3.3.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 11, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.