MagicFrog agent 不必只在客户端所在的机器上工作。每一台计算机——你创建的云电脑(cloud computer)、你自己的机器,或本机本身——都是一等执行目标,agent 可以在其上执行浏览器、命令、文件与桌面操作。
每台计算机由一个稳定的 computerId 标识。IP 地址不是身份:地址会变,同一台路由器后的两台机器还可能共享一个地址。computerId 才是你选择的目标,也是每一次工具调用被授权的依据。

图为 Computers 页的空态与 Provision 表单(如实呈现,未做修饰)。
计算机从哪里来
| 类型 | 来源 | 典型用途 |
|---|---|---|
local |
恒定存在。客户端所在的那台机器,以 id local 注册。 |
在你面前的这台机器上工作。 |
docker |
平台创建:以容器形态运行的 Linux 云电脑。 | 一次性 Linux 工作负载,带浏览器与 shell 访问。 |
windows |
平台创建:Windows 云电脑。 | Windows 专属的浏览器、shell 与桌面工作。 |
enrolled |
你通过 CLI 登记:既有的物理机、服务器或 VM。 | 把你自己的硬件编入名册。 |
docker 与 windows 计算机由平台托管创建(provisioned)——创建、启动、停止与销毁都归平台所有。local 计算机就是客户端所在的那台机器。已登记计算机则不同:MagicFrog 从未创建它,也从不删除它。吊销一台已登记计算机只是移除登记,仅此而已。
范围:一个控制面,一台服务器
MagicFrog 刻意做成单服务器。控制面只在它所在的那台服务器上、经由该主机自己的容器 runtime 来创建、启动、停止、销毁托管创建的云电脑。没有办法注册第二台物理主机、添加节点资源池、把 runtime 指向远程 Docker daemon,或把计算机调度到另一台机器上——这些面在配置和 API 里都不存在。这是产品边界,不是你可以调大的默认值。
单文件 SQLite 数据库是同一边界的技术对应物:持久化就是一块卷上的一个数据库,不是共享集群存储。
已登记计算机在这个范围之外。它们由你用 CLI 自行登记;控制面从不托管创建、启动或销毁它们,只通过它们主动外连的 daemon 连接向它们派发工作。所以「一台服务器」限制的是控制面创建什么,而不是你的 agent 能操作哪些机器。
生命周期
托管创建的云电脑与已登记机器的生命周期各不相同。
托管创建的计算机
托管创建的计算机(docker 或 windows)经历这些状态:
creating——容器或 VM 正在被创建。若创建超时或镜像缺失,半成品实例会被清理,创建以显式错误失败。ready——实例已就绪并接受工作。Linux 计算机在其容器运行并就绪时到达此状态;Windows 计算机在其克隆运行且远程桌面端口开始监听时到达此状态。stopped——实例已停机,但其磁盘(容器卷或 VM 镜像)保留。再次启动会回到ready。destroyed——终态。容器/VM 及其卷被删除。
计算机还有活跃 run 或租约时,启动与停止都会被拒绝,所以停一台计算机不会抽掉正在运行的任务脚下的地板。
已登记计算机
已登记机器走自己的状态:
pairing——CLI enroll 正在进行,等待你确认配对码。enrolled——活跃且已登记。revoked——终态。登记已消失:设备凭据失效,既有连接在数秒内被切断,该计算机不再作为可用目标出现。
离线
任何计算机还可能处于 offline。已登记机器运行 daemon,每 15 秒向服务端报一次活;连续两次心跳未到,约 30 秒后该计算机被标记为 offline。路由到 offline 计算机的调用显式失败——它们绝不静默改投另一台机器。
能力
计算机的能力是探测出来的,不是声明出来的。enroll 期间 daemon 探测真实主机并如实上报——shell 与文件访问恒可用,浏览器在运行时验证,桌面控制取决于平台(macOS 需要屏幕录制权限;Windows 需要启用远程桌面)。上报的能力集包含主机的操作系统与 CPU 架构。
你不需要手工配置能力。当工具需要目标不具备的能力时——例如在一台 headless 机器上执行桌面操作——调用会以显式能力错误失败,而不是静默降级。
登记你自己的计算机
你掌控的任何机器都能作为已登记计算机加入你的账号:
magicfrog enroll --server https://<your-host>:4096
CLI 会登录你的账号,请求一个短期配对码,并等待你确认。确认之后,这台机器获得自己的设备身份,并以已登记计算机的形式出现在你的账号下。
- 设备凭据本地存放在
~/.magicfrog/credentials/device.json(权限0600),与你的用户登录相互独立。 - 设备 token 可随时被独立吊销。
magicfrog enroll --unenroll(或从服务端侧吊销)只移除登记,不触碰机器上的任何东西。
CLI 命令详见 CLI 文档。
列出计算机
控制面暴露你账号下的计算机:
GET /v1/computers
每一条目都携带其 computerId、来源(托管创建或已登记)、生命周期状态与探测到的能力——与 daemon 上报的同一份事实,而不是静态配置。
计算机一旦存在,每一个触碰机器的 agent 工具都以 computerId 指名目标。该路由与授权模型见 Computer ID 路由。