关于 Froglet
Froglet 是一款本地优先的节点,可发布和调用 Agent 编写的服务、所选数据工作流及受限 Wasm 计算。它生成可离线验证的签名哈希链证据;README 将当前范围描述为仍有资格验证事项待完成的公开预发布版。
主要功能
- 01经明确批准后发布服务
- 02运行受限 Wasm 计算
- 03共享所选 JSON、CSV 或 SQLite 数据
- 04生成可离线验证的签名回执
适用场景
- 01发布 Agent 编写的数据服务
- 02让其他 Agent 使用共享目录
- 03运行受限 Wasm 任务并检查证据
MCP 相关
Froglet 提供原生 MCP 集成和名为 `froglet-mcp` 的 JavaScript MCP 服务。两者均向宿主 Agent 注册单个 `froglet` 工具,可执行需经批准的服务发布等操作。
配置
本地服务的配置在各客户端中通用,复制后粘贴到客户端的 MCP 配置文件即可。
工具
1收录的工具列表 · 更新于 2 周前
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| mode | enum | 否 | sync | async |
| name | string | 否 | 服务名称(project_id + service_id + scaffold 目录)。使用小写 ASCII 字母、数字或内部连字符。marketplace_publish 必填。 |
| role | enum | 否 | plan_install/get_install_guide 的用户意图。Docker 默认同时启用提供方和运行时;拆分角色属于 froglet-node 的直接配置。consumer | provider | both |
| input | any | 否 | |
| limit | integer | 否 | |
| query | string | 否 | |
| action | enum | 是 | 准确的 Froglet 操作名称。不要臆造操作。首先使用 status 验证本地提供方/运行时是否可访问。本地列表使用 list_local_services,远程市场列表使用 discover_services,权威详情使用 get_local_service/get_service,指定服务执行使用 invoke_service,向本地提供方发布已构建产物使用 publish_artifact,开放式计算使用 run_compute。一键式、适用于 Agent 的发布(HEADLINE 操作)使用 marketplace_publish——它会在一次 MCP 调用中搭建清单、构建产物、签名、注册和验证。结算情况查询:get_wallet_balance、list_settlement_activity、get_payment_intent、get_invoice_bundle。市场封装工具:marketplace_register、marketplace_search、marketplace_provider、marketplace_receipts、marketplace_file_complaint、marketplace_get_complaint——面向市场时优先使用这些工具,而非 invoke_service。plan_install 返回决策树、先决条件、所需密钥、验证检查和安装后操作手册。get_install_guide 返回已确认配置的权威 Shell 命令——通过你自己的 Shell 执行,而非 Froglet 运行时。plan_use_case 返回消费者/提供方/证据/支付/批处理/GPU 工作流的安装后实施计划。discover_services | get_service | invoke_service | list_local_services | get_local_service | publish_artifact | status | get_task | wait_task | run_compute | get_wallet_balance | list_settlement_activity | get_payment_intent | get_invoice_bundle | plan_install | get_install_guide | plan_use_case | marketplace_register | marketplace_domain_claim | marketplace_domain_complete | marketplace_search | marketplace_provider | marketplace_receipts | marketplace_file_complaint | marketplace_get_complaint | marketplace_publish |
| cursor | string | 否 | marketplace_search / marketplace_receipts 的不透明分页游标。 |
| mounts | any | 否 | 工作负载所需的可选挂载句柄或绑定。请保持为提供方定义的挂载负载。 |
| reason | string | 否 | 提交 marketplace_file_complaint 的人类可读原因。 |
| status | string | 否 | marketplace_receipts 的状态筛选器(例如 "succeeded")。 |
| deal_id | string | 否 | 目标交易 ID。get_payment_intent 和 get_invoice_bundle 必填。 |
| hosting | object | 否 | marketplace_publish 的托管后端。kind ∈ {local|tor|self}。local = 私有开发,tor = 自动隐藏服务(需要守护进程 FROGLET_NETWORK_MODE=tor),self = 用户提供的 URL。 |
| hosting.url | string | 否 | 当 kind = 'self' 时必填。 |
| hosting.kind | enum | 否 | local | tor | self |
| runtime | string | 否 | 服务或计算请求的执行运行时,例如 wasm、python 或 container。 |
| starter | string | 否 | 用于 publish_artifact 的可选精简 JSON 示例输入;仅供示例,其约束不强于 input_schema。 |
| summary | string | 否 | publish_artifact 的描述性元数据。 |
| task_id | string | 否 | |
| claim_id | string | 否 | marketplace_domain_claim 返回的域名声明 ID。 |
| evidence | any | 否 | marketplace_file_complaint 的可选 JSON 对象或证据数组。 |
| offer_id | string | 否 | |
| template | enum | 否 | 可选的 publish_artifact 模板。demo.add 会发布一个免费的本地 Python 加法服务,用于首次运行验证。demo.add |
| use_case | string | 否 | 用户安装后首次计划使用 Froglet 的用途;plan_install 使用此信息选择安装后的操作指南。 |
| footprint | enum | 否 | plan_install/get_install_guide 的安装占用范围。docker 是完整的本地 provider+runtime 技术栈;binary 仅安装 froglet-node;source 从克隆的仓库构建。docker | binary | source |
| public_ip | string | 否 | 用于 Froglet 管理的 provider 子域名声明的公网 IPv4 或 IPv6 地址。 |
| entrypoint | string | 否 | 工作负载的入口点标识符或路径。 |
| oci_digest | string | 否 | |
| offer_kind | string | 否 | marketplace_search 的 Offer 类型筛选条件(例如 "named.v1")。 |
| price_sats | integer | 否 | |
| service_id | string | 否 | 服务标识符。publish_artifact、get_local_service、get_service 和 invoke_service 必填。 |
| settlement | object | 否 | marketplace_publish 的结算方式。支持:'none'(免费)、'lightning'(保留发票托管,由节点的 Lightning 钱包结算;需要 Lightning 后端和 price.currency='sat'),或 'stripe'(Stripe MPP / Shared Payment Tokens;需要 Stripe 后端和 price.currency='usd')。 |
| settlement.method | enum | 否 | none | lightning | stripe |
| provider_id | string | 否 | 目标 provider 节点 ID。对于 marketplace 支持的 get_service、invoke_service 和 run_compute 调用,优先使用此参数。 |
| result_json | any | 否 | 可选的静态 JSON 结果。与 publish_artifact 配合用于返回固定结果的服务。 |
| capabilities | array | 否 | publish_artifact 的可选 provider 必需能力字符串,例如 compute.gpu。GPU 能力需要启用 GPU 的 provider。 |
| complaint_id | string | 否 | marketplace_file_complaint 返回的投诉 ID。 |
| input_schema | any | 否 | |
| network_mode | enum | 否 | 本地/可自托管 Froglet 的网络模式。先保持 clearnet/loopback;只有本地健康检查通过后才使用 tor 或 dual。clearnet | tor | dual |
| package_kind | string | 否 | 工作负载的执行包类型,例如 inline_module、inline_source 或 oci_image。 |
| payment_rail | enum | 否 | plan_install/get_install_guide 的显式支付渠道。生成命令前必须指定;对于第一个免费演示服务,请使用 none。none | lightning-mock | lightning-lnd-rest | stripe-test | stripe-live | x402 |
| provider_url | string | 否 | 可选的提供方基础 URL 覆盖值。必须是公开的 https URL,但 marketplace_register 可使用带 registration_transport=tor 的 Tor v3 http://*.onion URL。通常会根据 provider_id 或 service_id 自动发现。 |
| receipt_hash | string | 否 | marketplace_file_complaint 的可选收据工件哈希。 |
| target_agent | enum | 否 | plan_install/get_install_guide 的 Agent 目标。默认值为 claude-code;如果用户将自行配置 MCP,请使用 manual。claude-code | codex | openclaw | manual |
| timeout_secs | integer | 否 | |
| artifact_path | string | 否 | publish_artifact 的守护进程本地工件路径。仅当提供方配置了 FROGLET_PROVIDER_ARTIFACT_ROOT,且已知该路径规范化后位于该根目录下时使用。 |
| inline_source | string | 否 | 计算请求的可选内联源代码。若要运行明确指定的源代码,通常适用于 runtime=python、package_kind=inline_source 时,请使用此参数。 |
| oci_reference | string | 否 | |
| output_schema | any | 否 | |
| source_inline | string | 否 | 用于 marketplace_publish 的 Python 源代码(完整的 handler.py 内容,定义 handler(event, context))。当 package_kind 默认为 inline_source 时为必填项(v1A 唯一支持的形状)。 |
| complainant_id | string | 否 | marketplace_file_complaint 的可选请求者或投诉者 ID。 |
| lightning_mode | enum | 否 | plan_install/get_install_guide 的 Lightning 模式。mock 无需钱包;lnd_rest 需要 LND REST URL 和 macaroon 路径。mock | lnd_rest |
| max_price_sats | integer | 否 | marketplace_search 结果的 sats 价格上限。 |
| requested_slug | string | 否 | marketplace_domain_claim 的可选 providers.froglet.dev slug。 |
| entrypoint_kind | string | 否 | 工作负载的入口点形状,例如 handler、script 或 builtin。 |
| marketplace_url | string | 否 | marketplace_publish(以及 marketplace_register / domain_claim)的市场 URL。默认值为 https://marketplace.froglet.dev。 |
| signing_message | string | 否 | marketplace_domain_claim 返回的签名消息;marketplace_domain_complete 使用本地提供方身份对其签名。 |
| wasm_module_hex | string | 否 | 用于直接内联 Wasm 计算或 publish_artifact 的可选十六进制内联 Wasm 模块字节。对于由 Agent 驱动的发布,优先使用内联字节或 inline_source。 |
| contract_version | string | 否 | 执行负载的合约版本。 |
| include_inactive | boolean | 否 | |
| workload_profile | enum | 否 | plan_use_case 的可选配置文件。若省略,Froglet 会根据 use_case 推断。consumer | provider | evidence | payments | batch | gpu |
| publication_state | enum | 否 | active | hidden |
| poll_interval_secs | number | 否 | |
| registration_transport | enum | 否 | marketplace_register 的传输方式。默认值根据 provider_url 确定;仅在通过 http://*.onion 提供方进行注册时使用 tor。clearnet | tor |
| marketplace_arbiter_url | string | 否 | marketplace_file_complaint / marketplace_get_complaint 的可选市场仲裁方 URL。 |
| marketplace_provider_id | string | 否 | marketplace_* 操作所针对的提供方 ID。与用于路由 invoke_service 调用本身的 `provider_id` 不同。marketplace_file_complaint 必填。 |
详细介绍
Froglet
面向 Agent 交易、与支付通道无关的证据层。
无论资金通过哪种支付通道流转,Froglet 都会生成一份经签名、哈希链接的记录,说明 哪些内容获得了授权、适用哪些限额,以及执行方声明了什么——任何人都能离线验证, 无需节点或账户。
只需一条命令,即可自行验证链:
cargo run -p froglet-verify -- conformance/kernel_v1.json
由 Armanas Povilionis 创建并维护。
版权所有:Alithea Biotechnology GmbH,该公司负责运营托管服务。
目录
概览
发布准备,2026 年 10 月 2 日: 当前范围为通过原生 MCP 免费共享选定数据并运行有界 Wasm,同时可选使用已配置的 A2A。 请参阅生产交接与明确的剩余门槛。 本地软件检查、本地软件包和公开文档网站,均不能作为新生产计算部署或不可变版本的合格依据。
开发检查点,2026 年 10 月 1 日: 已恢复免费原生 MCP 工作流、可选的已配置 A2A 传输,以及通过有界 Wasm 计算共享选定数据的工作。 最终候选版本的实际 Codex CLI 工作流和提取后的演示包,已在当前 Apple Silicon Mac 上完成验证。 同一组生产输入还在隔离的 Linux arm64 开发容器中通过了 625 项库测试和九项原生 MCP 测试, 以及术语工作流。另有 13 项库测试被忽略;Python OS 隔离和 Linux Agent 主机仍未完成验证。 Claude Code 主机验证因无法登录而受阻。选定数据/配置文件示例和有界本地容量均已记录检查结果; 干净机器、公开计算 HTTPS/容量以及首位用户价值仍是独立门槛。请参阅当前工作 和验证证据。 公共文档网站已于 10 月 1 日恢复。七个检查过的路由均返回 HTTP 200,且与本地构建的字节一致。请参阅部署记录和剩余门槛。 最近一次观察到的托管计算试用不可用;本轮未重新验证该部署。生产环境和可用的托管计算验证仍未完成。不可变的 v0.4.7-beta.1 预发布版本现已发布;下载的 Apple Silicon 二进制文件通过了单独的确定性 localhost 重放测试。分发和已发布 Mac 版本的确切证据还记录了一次独立的原生 MCP Mac 到 Fly 证明:在一台现已移除的隔离测试主机上,完成了六个有界免费案例、重启持久化和离线任务恢复。该证明不代表生产环境、负载、新 Agent 主机、干净操作系统或付费运行已通过验证。 9 月暂停和回滚记录仍予以保留。文件下载仍属实验性质;Node/UI/中继验证尚未完成。 通用 CPU 作业、GPU 租赁和新的支付工作不在恢复后的范围内。
可选的研究配置明确说明了命名空间、版本、字段类型、单位、来源和映射假设。最后一个本地示例以 100 行和 40 行为分页大小,获取固定版本的公共 GO 目录,并验证了回执;这证明了数据交换和声明的元数据兼容性,而非科学正确性或独立用户需求。
在一台共享机器上,使用独立请求方身份的八个并发微型工作流在测量中均顺利完成,没有错误。在 16 和 32 个并发工作流时,六个选定数据作业触及四进程上限,并返回了经过独立验证的失败链。共享请求方身份仍受限于每秒约一个相同请求方/工作负载/条款组合的 Quote;现在,冲突会在 Deal 接纳前失败,且不会留下待处理的请求方提交。这些测量不能证明生产容量、性能优势或节省开发时间。请参阅本地验证的确切情况。
当前产品候选版本从 “让另一个 Agent 能够使用此目录。” 开始。Codex 或 Claude Code 可以准备选定的 JSON、类型化 CSV 或 SQLite 数据,或一个小型 Wasm 函数;运行本地示例;请求对确切的发布内容进行审批;并返回提供方/服务分享链接。原生设置会保留现有 Agent 设置。接收方无需 npm 即可使用相同的原生集成。
请参阅发布工作流和验证门槛。
这是一个公开预发布版本:干净机器上的 Agent 测试、通过此配置文件进行的真实公共中继流程,以及首次用户验收,仍是验证门槛。首次用户试用套件将设置易用性与有用作业的证据区分开来。支持的目标平台为 Apple Silicon macOS 和 Linux x86_64/arm64。主机必须保持在线。
本地已捕获程序的重放现已具备完整证据:Alice 保留的 81,222 字节 Wasm 程序与四个独立冻结的答案相符,七条已接纳的签名链也都通过了离线验证。这七条链包括一个所有者控制、一次选定数据检索、四次程序执行,以及另一个循环程序的预算失败。精确重放已完成的数据和计算请求后,在 Bob 停止、Alice 重启后,成功恢复了缓存结果。在那次历史重放中,Bob 停止时,get_task 返回了 HTTP 502。10 月 3 日的修正现可在本地重新验证已保存的终态任务证据;未签名或状态未解决的任务仍需 Bob 在线刷新。当前源码的本地回归测试通过;一个全新的优化原生候选版本也通过了独立验证,确认七条链以及 Bob 停止、Alice 重启后读取的全部六条 Alice 已保存终态任务记录均无误。软件包/发布门禁和网站发布仍是独立检查项。
这是对先前实际 Codex 会话中创建的程序进行确定性重放。该次新会话资格验证仍未通过,因为未捕获完整链,且持久化的 Codex 配置发生了变化。此重放不会启动 LLM、编译器或 Agent 设置操作。请参阅可复用运行手册和本地最终定稿证据。
Froglet 以一种签名经济原语支持三种产品形态:
| 形态 | 描述 |
|---|---|
| 命名服务 | 可发现、已发布的服务端点 |
| 数据支持型服务 | 由机器人编写的数据或项目支持的服务 |
| 开放式计算 | 通过 provider_id 或 provider_url 指定目标的原始计算 |
面向机器人的主要集成接口刻意保持简单:
- 一个 OpenClaw/NemoClaw 插件 ID:
froglet(位于integrations/openclaw/froglet/) - 一个位于
integrations/mcp/froglet/下的 MCP 服务,发布为froglet-mcp,可通过npx froglet-mcp使用;此外还有依赖极少的原生 桥接,位于froglet-node mcp - 两种接口都会向宿主(Claude Code、Codex、Cursor、Windsurf 等)注册一个名为
froglet的 Agent 工具。核心操作是两步式marketplace_publish:首次调用只生成计划,不会 修改任何内容;第二次调用必须携带完全一致的已批准consent_hash。原生和 JavaScript 适配器都委托给同一个 Rust 发布模块和提供方控制协议。 froglet-node二进制既是守护进程(以提供方身份运行),也是作者 CLI(包含froglet-node init/build/publish/whoami、prepare-service、invoke、doctor和check-updates)。status --open --json会返回一个短时有效、只读的本地状态 URL。
机器人应能直接创建小型可脚本化服务,在本地验证后发布,而不必从 OCI 镜像开始。 OCI 容器仍是受支持的打包和部署方式。
产品模型
- 任何 Froglet 节点都可以发布资源并调用远程资源
- 已发布的资源是执行绑定,由机器人编写的项目、明确指定的源代码或预构建工件提供支持
- 便于机器人创作和在本地检查可脚本化服务是核心产品要求
- 身份是签名工件中的一等要素
- 可自托管提供方支持通过明网 HTTPS、出站中继 HTTPS 和 Tor v3 onion 传输进行注册。引导流程默认规划官方中继 URL 和后缀,但会将其保持为未启用状态;在精确的持久授权使端点就绪之前,发布会默认失败关闭。规划中的配置并不意味着其公共运营方服务已部署。
说明
市场、排名、激励和经纪方策略位于协议之上。 支付通道是面向本地或可自托管运营方的适配器级接口,并非普通买家的入门流程。 本仓库的首发适配器为 Lightning、Stripe 和 x402。Lightning 和 x402 采用标准化的内核结算方法,并提供一致性测试向量;Stripe 的
stripe_mpp.v1收据格式已标准化,但依赖证明而非密码学验证。只有 Lightning 托管使用签名发票包流程。x402 的线路格式已定稿(x402.eip3009.v1,conformance/x402_v1.json),但其支付通道尚未定稿:发布路径不会公开该通道,且任何网络上都没有实时交互记录。第一方托管试用服务try.froglet.dev已于 2026 年 10 月 8 日退役;免费公共测试版 https://froglet.dev/services/ 已取而代之。在 Lightning 和 Stripe 提供公开支付交互记录之前,不得声称托管付费通道已上线;也不应要求用户仅为试用 Froglet 就管理 LND 通道或支付密钥。
发现与计算模型
- 通过发现机制查找具名服务和数据服务
- 开放式计算使用提供方的直接计算方案,通过
run_compute调用,并以provider_id或provider_url为目标 - 发布和引导适配器可以包含 Nostr 风格的发布机制,但不会将任何单一中继或网络作为内核事实来源
组件
从产品角度看,Froglet 是一个既能提供服务也能使用服务的节点。 参考实现提供以下二进制文件:
| 二进制文件 | 用途 | 默认端口 |
|---|---|---|
froglet-node | 提供方和/或运行时节点(通过环境变量配置角色) | 8080 / 8081 |
提示
市场集成是 Froglet 公共服务的一部分。运行时可以通过
FROGLET_MARKETPLACE_URL指向默认公共市场;提供方公开 HTTPS URL、分配给身份的中继 URL、Tor v3 onion URL 或已认领的*.providers.froglet.dev主机名后,可以在那里自行注册。请参阅 docs/MARKETPLACE.md。
前置条件
二进制文件安装(最快): curl、tar、sha256sum(Linux)或 shasum(macOS)。 支持的平台:Linux x86_64/arm64、macOS arm64。
从源代码构建: Rust 1.91+、Python 3.12+(用于测试)、Node 18+ 和 npm (用于 Claude Code/Codex MCP 设置和集成测试)。
Docker(可选备用方案/贡献者技术栈): 安装了 Compose v2 的 Docker。
快速入门
规范的入门指南位于
docs-site/src/content/docs/docs.mdx
(learn/ 索引仍作为旧版路由保留)。
使用仓库 README 了解产品和代码库概况,使用 docs-site 手册了解公开发布流程,并使用 docs/ 查阅规范、运营说明和集成参考。
公开发布说明仍然只有两个入口:
1. 试用公开 Beta 版
- 在浏览器中打开 https://froglet.dev/services/:无需安装、注册或邀请。它会在真实远程节点上运行你的受限 Wasm 程序或合成目录查询,并返回由浏览器验证的签名证据。
- 范围和限制: docs-site/src/content/docs/learn/cloud-trial.mdx
- 旧版托管试用服务
try.froglet.dev(及其ai.froglet.dev源站)已于 2026 年 10 月 8 日停用;请参阅 docs/HOSTED_TRIAL.md。 - 公开 Beta 版不证明付费通道、持久身份、服务发布、市场深度或通用运行时访问能力。
2. 本地运行
- 从 docs-site/src/content/docs/learn/quickstart.mdx 开始
- 接着阅读 docs-site/src/content/docs/learn/agents.mdx 和 docs-site/src/content/docs/learn/payment-rails.mdx
- 自托管和运维后续指南见 docs/DOCKER.md、 docs/GCP_SINGLE_VM.md 和 docs/MARKETPLACE.md
从零开始搭建最精简的本地完整技术栈:
set -eu
repo=AlitheaBio/froglet
metadata="$(mktemp "${TMPDIR:-/tmp}/froglet-release.XXXXXX")"
bootstrap="$(mktemp "${TMPDIR:-/tmp}/froglet-agent-bootstrap.XXXXXX")"
release_url="$(curl -fsSL --proto '=https' --proto-redir '=https' --tlsv1.2 -o /dev/null -w '%{url_effective}' "https://github.com/$repo/releases/latest")"
tag="${release_url%/}"; tag="${tag##*/}"
printf '%s' "$tag" | grep -Eq '^v[0-9A-Za-z][0-9A-Za-z.+-]*$'
curl -fsSL --proto '=https' --proto-redir '=https' --tlsv1.2 -H 'Accept: application/vnd.github+json' \
-H 'X-GitHub-Api-Version: 2026-03-10' \
"https://api.github.com/repos/$repo/releases/tags/$tag" -o "$metadata"
[ "$(sed -n 's/^ "immutable": \([a-z]*\),*$/\1/p' "$metadata")" = true ]
[ "$(sed -n 's/^ "tag_name": "\([^"]*\)",*$/\1/p' "$metadata")" = "$tag" ]
asset_record="$(awk '
/^ \{/ { in_asset=1; name=digest=state=""; next }
in_asset && /^ "name":/ { v=$0; sub(/^ "name": "/,"",v); sub(/",*$/,"",v); name=v }
in_asset && /^ "digest":/ { v=$0; sub(/^ "digest": "/,"",v); sub(/",*$/,"",v); digest=v }
in_asset && /^ "state":/ { v=$0; sub(/^ "state": "/,"",v); sub(/",*$/,"",v); state=v }
in_asset && /^ \},*$/ { if (name=="agent-bootstrap.sh") print digest "|" state; in_asset=0 }
' "$metadata")"
[ "$(printf '%s\n' "$asset_record" | sed '/^$/d' | wc -l | tr -d ' ')" = 1 ]
bootstrap_digest="${asset_record%%|*}"; asset_state="${asset_record#*|}"
[ "$asset_state" = uploaded ]
printf '%s' "$bootstrap_digest" | grep -Eq '^sha256:[0-9a-f]{64}$'
bootstrap_digest="${bootstrap_digest#sha256:}"
curl -fsSL --proto '=https' --proto-redir '=https' --tlsv1.2 \
"https://github.com/$repo/releases/download/$tag/agent-bootstrap.sh" -o "$bootstrap"
if command -v sha256sum >/dev/null 2>&1; then actual="$(sha256sum "$bootstrap" | awk '{print $1}')";
elif command -v shasum >/dev/null 2>&1; then actual="$(shasum -a 256 "$bootstrap" | awk '{print $1}')";
else actual="$(openssl dgst -sha256 "$bootstrap" | sed 's/^.*= //')"; fi
[ "$actual" = "$bootstrap_digest" ]
chmod 0700 "$bootstrap"
VERSION="$tag" sh "$bootstrap" plan
# Show the complete plan and wait for approval. Then copy its exact hash:
VERSION="$tag" sh "$bootstrap" execute '<install_approval_hash>'
rm -f "$bootstrap" "$metadata"
plan 是安全的默认选项,不会在临时工作区之外写入任何内容。
它会将不可变版本、经过验证的清单和目标平台二进制文件摘要、精确的引导/安装/配置脚本摘要、持久化路径以及服务管理器影响,整合为一个规范审批哈希。execute
会重新计算该契约;如果版本、脚本字节、配置文件、路径或提供的哈希发生变化,它会在进行任何持久化写入前停止。
审批通过后,Agent 引导程序会验证 Release Bundle,安装经校验和验证的
froglet-node,通过 launchd/systemd 启动原生双角色服务,
写入原生 MCP 配置,并且只有在健康检查通过、非播种式 MCP
状态证明通过,以及瞬时只读数据证明确认未发布后才会返回。
该证明首先要求活动报价源为空,且其确切服务 ID 没有任何生命周期记录;然后在发布前记录私有清理意图,并且只有在报价源为空的检查通过后,才移除其报价和创作目录。
如果证明失败,会尝试在服务仍运行时精确取消发布;如果无法确认清理成功,则会保留恢复标记。
如果无法进行原生服务管理,则使用摘要固定的双角色 GHCR 镜像作为备用方案。
审批计划默认包含官方中继端点和 DNS 后缀。这只是休眠配置:它会推导出精确的计划 HTTPS URL,但不会建立 WSS 连接,也不会在获得精确的持久发布授权前暴露任何服务。若要选择退出,请在运行 plan 前将 FROGLET_RELAY_URL='' 和
FROGLET_RELAY_PUBLIC_SUFFIX='' 都设好。第一方 DNS/TLS 端点尚未通过实时验证,因此中继发布仍是明确的外部门槛,而非安装成功的声明。请参阅
docs/RELAY.md。docs/AGENT_FIRST_PUBLICATION_PLAN.md
中的实现/证据矩阵会跟踪仍未通过的干净主机和外部门槛。
从可信的检出目录运行一次性主机验证:
bash scripts/fresh_host_quickstart_smoke.sh
较底层的 scripts/install.sh 是内部 Release Bundle 安装程序;
Agent 应使用上述带审批门控的引导程序。
源代码检出目录中的 Compose 和生成的主机端 Agent 配置依赖
FROGLET_HOST_READABLE_CONTROL_TOKEN=true;默认用户路径是无需克隆的 /agent 引导程序。快速入门页面提供逐步的 MCP 优先说明、支付通道选择、Tor 注册、托管子域名,以及贡献者/源代码模式备用方案。
直接运行二进制文件(不使用 Compose)
# Provider node
FROGLET_NODE_ROLE=provider \
FROGLET_PRICE_EXEC_WASM=10 \
FROGLET_PAYMENT_BACKEND=lightning \
FROGLET_LIGHTNING_MODE=mock \
cargo run -p froglet --bin froglet-node
# Runtime node
FROGLET_NODE_ROLE=runtime \
FROGLET_PAYMENT_BACKEND=lightning \
FROGLET_LIGHTNING_MODE=mock \
cargo run -p froglet --bin froglet-node
常规模式是让一个节点同时运行提供方和运行时角色
(FROGLET_NODE_ROLE=dual),这样它既能发布本地资源,也能调用远程资源。
在运行时节点上设置 FROGLET_MARKETPLACE_URL,即可通过外部市场进行搜索。提供方在公布匹配的公共 HTTPS 源、已分配的中继 HTTPS URL、Tor v3 onion URL 或已认领的 *.providers.froglet.dev 主机名后,可在默认公共市场自助注册。
Bot 接入界面
OpenClaw、NemoClaw 和兼容 MCP 的主机目前是面向 Bot 的主要接入界面。分发状态和市场/插件排序见 PLUGIN_DISTRIBUTION.md。
OpenClaw & NemoClaw
使用共享插件包:
integrations/openclaw/froglet。
当前,安装和检查 OpenClaw 插件,以及调用网关,都要求 Node.js 22.14.0 或更高版本。由网关代理的本地操作启动时,应将 FROGLET_PROVIDER_AUTH_TOKEN_PATH 和 FROGLET_RUNTIME_AUTH_TOKEN_PATH 指向本地 data/runtime/ 令牌文件。
配置键
| 键 | 用途 |
|---|---|
hostProduct | 目标宿主产品 |
providerUrl | 提供方/公共 API 基础 URL |
runtimeUrl | 运行时 API 基础 URL |
providerAuthTokenPath | 提供方控制令牌的路径 |
runtimeAuthTokenPath | 运行时身份验证令牌的路径 |
baseUrl | 旧版单表面备用 URL |
authTokenPath | 旧版单令牌备用路径 |
requestTimeoutMs | HTTP 请求超时时间 |
defaultSearchLimit | 默认发现结果数量上限 |
maxSearchLimit | 发现结果数量上限 |
生成的本地 OpenClaw 配置使用上述拆分的提供方/运行时键。
对于已检入的 NemoClaw 示例等单表面配置,仍支持旧版 baseUrl 和 authTokenPath。
一个 froglet 工具涵盖:
- 服务发现和调用
- 通过
marketplace_publish发布 Agent 级服务 - 通过
publish_artifact发布本地制品 - 结算状态可见性和当前市场封装
- 状态和任务轮询
- 通过不修改状态的
plan_install精确审批安装,然后通过get_install_guide生成已审批命令 - 通过
plan_use_case规划安装后的工作流 - 原始计算
重要行为说明
summary仅提供元数据;不会生成代码publish_artifact是当前的本地发布路径run_compute是开放式计算的底层路径,应包含provider_id或provider_url- 项目编写、日志跟踪和节点重启不属于当前的公共工具 API
无克隆原生安装会直接配置已发布的二进制文件:
froglet-node mcp
此桥接无需 Node.js 运行时。其有意精简的 froglet 工具支持
status、invoke_service、run_compute、get_task、两步式
marketplace_publish,以及发布状态/日志/暂停/恢复/回滚/
确认取消发布。持久化云适配器工作可通过托管操作状态、确认协调和确认补偿单独查看。
只有在操作人员有意启用随附的演示目录后,才可使用 local_proof;
全新安装不会启用该功能。发布会委托给与 CLI 相同的规范项目
加载器、许可逻辑和提供方控制 API。
如需进行有界内联 Wasm 计算和可选的 A2A 传输,请使用由此代码库构建的二进制文件,或包含这些操作的版本。本地 MCP/A2A 演示会启动隔离的 Alice 和 Bob 节点,并通过真实的原生 MCP 路径进行演练。它使用免费的 回环计算和单独的私有 A2A 凭据;不会配置生产钱包,也不会向外部发布服务。受支持的配置文件和 尚未完成的发布门槛见 互操作规范。
JavaScript MCP 包为发现、结算、安装规划、原始计算和现有主机集成提供更广泛的兼容性和贡献者 接口:
npx froglet-mcp
npm 包默认使用 FROGLET_PROFILE=local,提供方/运行时 URL
分别指向 http://127.0.0.1:8080 和 http://127.0.0.1:8081。Agent 应先调用
status。如果缺少本地节点或令牌文件,请调用
plan_install,展示其不可变发布标签、清单/引导程序 SHA-256
值、持久化路径、进程管理器影响和准确的命令预览,
然后等待批准。获得批准后,才将返回的 release_tag
和 install_approval_hash 原样传递给 get_install_guide,并通过主机 shell 运行其中
经过验证的临时文件命令。本地健康状况验证完成后,在实现消费者、提供方、证据、支付、批处理或 GPU 工作流之前,使用
plan_use_case。原生 froglet-node mcp 桥接还可准备固定的 HTTPS JSON 服务、
将会过期的邀请写入私有文件,并控制持久化准入限制。请参阅有界 HTTP 服务和邀请。
支付仍由操作人员另行决定。公共市场金丝雀目前要求匿名访问;私有/邀请服务使用直接提供方调用。
目前无法执行 GPU:参考 OCI worker 不会挂载或核算设备。不会公布 GPU 能力,GPU 请求也会明确失败。此前的 Docker/GCP 硬件验证并不适用于此 worker。批处理扇出、GPU 调度和通用存储仍是独立工作项。公共免安装验证仍是 https://froglet.dev/llms.txt 上的 HTTP 流程;它不是已安装的 MCP 操作。
对于本地节点,请使用本地配置文件:
FROGLET_PROFILE=local \
FROGLET_PROVIDER_URL=http://127.0.0.1:8080 \
FROGLET_RUNTIME_URL=http://127.0.0.1:8081 \
FROGLET_PROVIDER_AUTH_TOKEN_PATH=/absolute/path/to/froglet/data/runtime/froglet-control.token \
FROGLET_RUNTIME_AUTH_TOKEN_PATH=/absolute/path/to/froglet/data/runtime/auth.token \
npx froglet-mcp
在源代码检出目录中,也可以直接运行同一服务器:
npm ci --prefix integrations/mcp/froglet
node integrations/mcp/froglet/server.js
npm、源代码检出和固定摘要的 MCP 镜像模式通过 MCP stdio 暴露更广泛的 JavaScript 接口。原生模式则暴露上述更精简、无依赖的发布/生命周期接口;它不声称与 JavaScript 操作保持一致。
对于普通用户,/agent 引导程序无需克隆代码库即可写入本地 MCP 配置。在源代码检出目录中,贡献者仍可生成准确的配置文件,而不必手动编辑 JSON 或 TOML:
cd froglet && ./scripts/setup-agent.sh --target claude-code
cd froglet && ./scripts/setup-agent.sh --target codex
可移植托管与 OCI 隔离
froglet-service/v4 通过与提供商无关的
target/profile 表达托管配置。它不包含 AWS 区域、Lightsail 名称、Fly 应用、
ECR 仓库或云 SDK 类型。同级的
Managed Deployment operator(私有的 froglet-services 仓库,非开源)
通过当前的 Lightsail 兼容适配器或通用 SSH + OCI 适配器,实现相应的可移植期望状态生命周期,
并返回相同的标准化结果格式。将发布引擎接入 operator,以及使用凭证进行实时 canary 测试,仍是尚未通过的独立关卡。
V3 清单仍可读取。hosting.default = "fly" 和 hosting.fly.*
仅作为已弃用的兼容性输入;新的配置使用 v4 managed,提供商选择则由 operator 自有的适配器配置负责。请参阅
docs/PUBLICATION_CONTRACT.md。
任意 OCI 执行不会让 Froglet Node 获得 Docker/Podman 套接字。
节点会向经过身份验证的工作器端点发送仅含摘要、有界且能力受限的请求;该端点由
FROGLET_OCI_WORKER_URL 和 FROGLET_OCI_WORKER_TOKEN_PATH 配置。参考
OCI 工作器(私有的 froglet-services 仓库,非开源)
负责访问无根引擎,默认采用只读、非 root、无网络的执行方式。
未配置工作器时,OCI 执行会默认拒绝。
验证
验证产物链(对接方的操作)
froglet-verify 是独立的离线验证器:无需节点、网络、账户或时钟,除非你提供时钟。将产物链传给它,它会检查
每个封套签名、每条产物语义规则,以及产物之间的每个哈希链接。
cargo run -p froglet-verify -- conformance/kernel_v1.json
它接受单个产物、JSON 数组、/v1/feed 页面或一致性测试夹具,可从文件或 stdin 读取;--json 会输出机器可读的报告,
--now <unix> 会启用过期检查。退出代码:0 表示有效,1 表示无效,
2 表示用法错误。
若要检查运行中节点发布的内容,可直接将其 feed 传入。feed 是分页的,因此验证结果仅适用于你获取的页面:
curl -s 'http://127.0.0.1:8080/v1/feed?limit=50' | cargo run -q -p froglet-verify -- -
Rust 门面、浏览器 WASM 构建和仓库内的 Rust 一致性测试运行器共用
froglet-protocol 实现。python/froglet-verify
是独立实现,并检查相同的公开测试向量。多个 Rust 运行器用于测试不同的分发路径;它们并不能提供实现多样性。请参阅
conformance/README.md,了解符合规范的运行器必须断言哪些内容;规范性规则请参阅 docs/SPEC.md。
构建与仓库检查
定向检查:
cargo check -q
cargo test -q --lib
node --check integrations/openclaw/froglet/index.js
node --check integrations/openclaw/froglet/scripts/doctor.mjs
node --test integrations/openclaw/froglet/test/plugin.test.js \
integrations/openclaw/froglet/test/config-profiles.test.mjs \
integrations/openclaw/froglet/test/doctor.test.mjs \
integrations/openclaw/froglet/test/froglet-client.test.mjs
npm run check:mcp
npm run test:mcp
完整仓库检查:
./scripts/strict_checks.sh
基于 Compose 的冒烟测试
可选的基于 Compose 的机器人界面冒烟测试覆盖:
FROGLET_RUN_COMPOSE_SMOKE=1 ./scripts/strict_checks.sh
手动运行基于 Compose 的冒烟测试命令:
node integrations/openclaw/froglet/test/compose-smoke.mjs
node integrations/mcp/froglet/test/compose-smoke.mjs
当前范围
此仓库目前包含:
docs/和conformance/下的协议与配套规范——稳定性保证见 docs/VERSIONING.md;如需用另一种语言构建第二个实现,请从规范测试向量conformance/kernel_v1.json开始(指南:froglet.dev/spec/conformance)- 参考 Froglet 节点实现:单个
froglet-node二进制文件提供分离的提供方平面和运行时平面(以froglet-provider和froglet-runtime容器镜像的形式发布) - OpenClaw 源插件集成和共享的 NemoClaw 插件代码;特定主机的验证状态另行记录
- 原生、依赖精简的 MCP 桥接,以及面向外部 Agent 主机和自动化流程的更全面 JavaScript MCP 服务
- 基于 Python 的公共节点与协议接口辅助工具和测试
- 面向 Bot 编写服务的本地项目编写、构建、测试和发布流程
- 直接发布预构建 Wasm 和基于 OCI 的配置文件
- 面向 Wasm、Python、容器和机密执行路径的参考执行配置文件
- 面向运维方控制的 Lightning、Stripe 和 x402 的本地/可自托管参考结算支持
- Clearnet 和出站中继传输,以及可选的可自托管 Tor 和面向 Nostr 的适配器支持;实时公共中继就绪情况属于外部部署门槛,不会根据客户端实现推断
- 面向公共仓库接口的测试、验证脚本和发布文档
- 面向公众的自托管文档和示例
后续或单独部署:
- Lightning 和 Stripe 的第一方托管付费通道声明,等待公开实时记录;托管 x402 仍值得支持,但并非阻塞项
- 更高层的市场排名、声誉和策略服务
- 长时间运行的批处理编排,目前不在 v1 运行时接口范围内
- 在
froglet-services中维护的、与提供方无关的 Lightsail 和通用 SSH + OCI 托管部署适配器的凭证实时验证 - 当需求足以证明其合理性时,为 GCP、OVH 和类似提供方增加配置适配器;清单中不得加入新的提供方枚举值
- 将 Zip 或归档打包作为一等执行提交格式
- 第一方托管控制平面运维和运行手册
警告
各运行时的执行加固程度并不一致。 Wasm 是最强的进程内可运行隔离路径。机密/TEE 工件类型目前仍仅是协议脚手架:此构建会拒绝模拟证明/密钥释放策略,且不会公布
tee.*运行时。 Python 需要 Linux Landlock ABI v3 和 seccomp;OCI/容器执行则继承单独配置的工作器的隔离特性。
文档
第一方托管部署工具和运营人员操作手册与本仓库中的公共协议和自托管文档分开维护。
许可证
Froglet 由 Armanas Povilionis 创建并维护,采用 Apache License 2.0 授权。版权所有 2026 Alithea Biotechnology GmbH; 详见 NOTICE。
评论
一个开放协议,规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话,MCP 服务负责提供工具、资源和提示模板,两者通过标准消息通信,同一个服务可以被不同客户端复用。