Skip to main content

WorkflowVM

将 GitHub Actions 化为可调度的云端 Python 沙盒

License Workflow Status Release PyPI version

Docker Image version Docker Image size Last Commit

LINUX DO


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

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)

Source distribution for workflowvm 0.3.3
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)

Table of built distributions (wheels) for workflowvm 0.3.3
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page