createos-deploy

部署到 CreateOS

使用网关的、经过钱包身份验证的 HTTP 流程。无需浏览器会话或 OAuth。

默认网关：https://mpp-createos.nodeops.network

建议使用随附脚本，因为它能在支付重试期间保留完全一致的部署请求正文、过滤上传内容中的机密信息、使用新的身份验证随机数，并验证最终端点。

cd path/to/createos-deploy
bun install

# Inspect the 402 and stop before signing a payment.
bun run deploy -- --dir /path/to/project --name my-app --port 3000

# Pay the selected native MPP offer and deploy.
bun run deploy -- --dir /path/to/project --name my-app --port 3000 --chain arbitrum --yes

# Select x402 instead. It must be advertised by the gateway for that chain.
bun run deploy -- --dir /path/to/project --name my-app --port 3000 --chain bsc --protocol x402 --yes

在进程环境中或此技能旁边的 .env 文件中提供 PRIVATE_KEY。切勿将其放入要上传的项目中。设置 CREATEOS_GATEWAY 可测试其他网关。

安全边界

• 部署前检查应用源代码，并确定其实际监听端口。不要相信过时的部署元数据。
• 项目名称在整个平台注册唯一，而不是每个钱包各自唯一。始终在名称后附加随机后缀，随附脚本会自动为你处理。GET /agent/projects 只会列出你自己的项目，因此无法检测其他账户占用的名称。
• POST /agent/deploy 返回 5xx 通常意味着名称冲突，而不是网关故障。应先将其视为名称冲突，并使用新的后缀重试；对于其他账户占用的名称，网关不会返回 409。
• 如果钱包有足够的未使用额度，首次 POST /agent/deploy 可能会立即部署。仅报价模式可以阻止新的支付，但无法阻止使用此类额度进行部署，因为 API 没有单独的报价端点。
• 未提供 --yes 时，在展示所选协议、网络、收款方和 USDC 金额后停止。
• 以运行时的 402 标头为准。不要根据发现元数据硬编码默认支付链。
• 切勿同时提交 Authorization: Payment ... 和 PAYMENT-SIGNATURE。
• 提交支付凭证后，切勿仅为从错误中恢复而创建并提交第二个凭证。如果有回执或挑战以及交易引用，应将其提供给用户。当可能已有额度时，不带支付标头重试是安全的。
• 删除项目前，必须立即向用户确认。删除操作不可逆。

支付行为

默认协议为原生 MPP：

• Base、Arbitrum 和 Arbitrum Sepolia 使用 EIP-3009 USDC 授权。Agent 对授权进行签名；网关结算器广播授权并支付 Gas。
• BSC 使用 Binance B402 Permit2 Exact。钱包向规范的 Permit2 批准 USDC 后，支付无需 Gas。脚本会使用与当前支付金额相等的有限额度进行批准；批准本身需要 BNB Gas。

x402 为可选协议：

• 只有当某条链出现在 PAYMENT-REQUIRED.accepts 中时，才能通过 x402 在该链上支付。
• Base 和 Arbitrum 系列的 x402 报价使用 EIP-3009。
• BSC x402 使用 Binance B402 Permit2 Exact。
• x402 的 amount 值以代币最小单位表示。线上架构不包含 decimals；请使用可信的本地资产元数据。

网关目前将所有支持的链上的代币都建模为 USDC。只接受已知的链 ID 和完全匹配的已知代币合约。

部署工作流

1. 检查项目，确定 port，并在发送任何部署请求前验证项目名称。为唯一名称追加随机后缀；将简洁名称保留为显示名称。
2. 使用 GET /agent/projects 检查是否已有同名项目，并显示运行时可能受到共享额度影响的活跃项目。此检查仅覆盖你的钱包，因此后缀仍是必需的。
3. 使用新生成的钱包认证标头发送 POST /agent/deploy，且不附带付款凭证。
4. 如果返回 200，则部署已开始使用额度。
5. 如果返回 402，检查 WWW-Authenticate 中的原生 MPP 信息，以及 PAYMENT-REQUIRED 中的 x402 信息。仅选择用户批准的协议，以及 USDC 余额充足的公告链。
6. 创建一个凭证，并使用 Authorization 或 PAYMENT-SIGNATURE 重试完全相同的请求正文。
7. 在错误报告中保留 Payment-Receipt 和 PAYMENT-RESPONSE 的值。
8. 每五秒轮询一次所属部署，直到状态变为 ready 或 failed，每次都使用新的认证 nonce。
9. 等待后再获取端点。ready 是平台的状态，并非容器的状态：应用仍需启动并绑定端口，因此首次探测通常会返回 404 或拒绝连接。每十秒探测一次，最长两分钟，之后再判断端口问题。若 404 在整个时间段内持续出现，可能是应用在 / 的实际响应；若完全没有响应，则可能是 --port 设置错误。

若要在没有捆绑脚本的情况下实现此流程，或诊断网关响应，请阅读 references/api.md。