【免费下载链接】BinduBindu: The identity, communication, and payments layer for AI agents.项目地址https://gitcode.com/gh_mirrors/bin/Bindu点击查看免费下载bindu deploy script --runtimeboxd是 Bindu 提供的云端运行时方案宿主进程仅扮演部署工具的角色Agent 则运行在 boxd 展开结合仓库内BoxdRuntimeProvider的实现与测试完整讲解命令行参数、生命周期、密钥安全、源码打包规则与故障排查读完即可把你的本地 Agent 脚本一键变成真正的微服务。一、Boxd 运行时是什么Bindu 的 Agent 脚本本身与运行环境解耦默认情况下python my_agent.py在本地进程内运行in-process 运行时而bindu deploy命令通过RuntimeProvider抽象把同一个脚本运行到别处仓库内目前内置的唯一云端提供方就是BoxdRuntimeProvider见 docs/runtime/README.md。其核心工作流是bindu deploy agent.py --runtimeboxd该命令会把你的项目源码打包上传在 boxd 微VM 中安装依赖并启动 Agent最后输出一个形如https://my-agent.boxd.sh的公开地址A2AAgent-to-Agent客户端可以直接访问。运行逻辑完全在 CLI 侧Agent 脚本内没有任何 boxd 相关代码——同一个脚本既可以本地python my_agent.py运行也可以远程部署区别仅在于启动动词参见 docs/runtime/README.md 中的设计说明。两种运行模式A2 与 A1从 boxd_provider.py 的模块注释可以确认Boxd 运行时支持两种模式模式触发方式行为A2默认不传--image通过 targzip 把本地源码打包上传在 VM 内安装依赖并直接执行 Agent 脚本A1自定义镜像传--image镜像VM 直接从镜像创建镜像的CMD即入口不做源码上传与pip install关于 A1 模式的 Dockerfile 模板、适用场景与 A2/A1 权衡详见 docs/runtime/custom-image.md本文后面会做简要对照。二、部署前置条件在首次执行bindu deploy --runtimeboxd前需要满足两个条件boxd 账号与 API Key在 boxd 控制台申请形如bxk_...。将密钥以环境变量形式放在宿主环境中export BOXD_API_KEYbxk_... # 或使用 export BOXD_TOKEN...从 boxd_provider.py 可以看到deploy()入口会先校验这两个环境变量缺失时直接抛出BOXD_API_KEY or BOXD_TOKEN must be set错误。安装 runtime-boxd 扩展pip install bindu[runtime-boxd]该扩展会从 PyPI 拉取boxdPython SDK。基础bindu安装默认不带它因为大多数场景并不需要云端部署只有需要时才引入参见 docs/runtime/quickstart.md。一个可运行的 Agent 脚本脚本通过bindufy()注册配置与处理函数即可无需任何 boxd 感知代码。关键设计BOXD_API_KEY只存在于宿主环境永远不会被送入 VM详见下文身份与密钥小节。三、CLI 标志完整参考bindu deploy的 boxd 运行时相关标志如下完整继承自 docs/runtime/boxd.md 并补充默认值与解析逻辑Flag类型默认值含义--runtimestrboxd运行时提供方名称。--namestr来自脚本config[name]覆盖 Agent 名称例如用于预览环境。--imagestr未设置若设置进入A1 模式VM 由该镜像创建不再传输源码。详见 docs/runtime/custom-image.md。--vcpuint2VM 的 vCPU 数量。--memorystr4G内存接受 boxd 尺寸字符串512M、4G等。--diskstr20G磁盘大小。--auto-suspendint0禁用空闲无 HTTP 请求N 秒后 boxd 自动挂起 VM。默认关闭因为 Bindu Agent 通常有后台工作调度任务、流式 LLM 调用、WebSocket 长连接空闲超时会把这些任务冻结在半途。只有当你的 Agent 是纯请求/响应模型时才显式传入如--auto-suspend60。--on-exitstrsuspendCtrl-C 时的行为suspend主动调用box.suspend()、destroy销毁 VM、detach保持运行并脱离。suspend不依赖--auto-suspend——宿主脱离时会直接挂起 VM。--bindu-versionstr未设置固定 VM 内安装的 bindu 版本特殊值local表示把宿主的 bindu 源码打包送入 VM用于测试补丁版 bindu。--envKEYVALUE—为 VM 内 Agent 追加环境变量可重复传入。这些默认值在 config.py 的RuntimeConfig中固化vcpu2、memory4G、disk20G、auto_suspend0、on_exitsuspend。值得注意的是RuntimeConfig.from_dict会做严格的键校验image、vcpu、memory、disk、auto_suspend、on_exit、bindu_version、env这些键仅在providerboxd时合法若在in-process配置中误传会被直接拒绝见 config.py。四、部署生命周期1. 首次部署冷路径bindu deploy会先在本地以捕获哨兵模式运行一次你的脚本——bindufy()检测到BINDU_DEPLOY_CAPTURE环境变量时只把 Agent 名称与源码目录写入 JSON 就立即返回不启动任何服务见 bindufy.py。随后 CLI 完成打包项目源码送入一个新 VM执行pip install bindu与项目依赖安装通过bindu serve --script your-script启动 Agent在 VM 内实际上等价于python3 script见 boxd_provider.py轮询/health直到就绪。冷路径耗时约10–30 秒取决于依赖重量。2. 后续部署热路径同一 Agent 名称再次执行bindu deploy时CLI 会复用已有 VM_resolve_vm先按名称查询未找到才创建见 boxd_provider.py更新源码并重启 Agent耗时约1–3 秒。重启时会对旧进程做优雅 TERM 5 秒等待 SIGKILL的清理避免旧进程继续占用 3773 端口导致新代码静默失效见 boxd_provider.py。3. Ctrl-C 与--on-exit策略--on-exitsuspend默认CLI 显式调用box.suspend()冻结 VM 内存并暂停所有在途工作。VM 保留在磁盘上重新bindu deploy会在 1–3 秒内恢复状态完整保留——DID 密钥、向量存储、会话历史等全部幸存。--on-exitdestroy彻底销毁 VM下次部署从零开始。--on-exitdetachVM 保持运行计费继续适合需要 Agent 在你关闭笔记本后仍持续服务的场景。从 boxd_provider.py 的实现看suspend是主动调用box.suspend()而非等待自动挂起计时器——因为自动挂起默认关闭若依赖它--on-exitsuspend会静默变成空操作。4.--auto-suspendN默认关闭Agent 运行期间若连续 N 秒没有 HTTP 请求则挂起 VM。适合纯请求/响应的 Agent 以节省空闲成本避免用于有定时任务、流式 LLM 调用或 WebSocket 连接的 Agent——它们会被冻结在半途恢复时可能中断 RPC多数上游服务无法容忍。五、身份与密钥管理这是 Boxd 运行时最值得注意的安全设计完整继承自 docs/runtime/boxd.mdVM 内生成并持久化Agent 的 DID 密钥、x402 钱包、OAuth 令牌。BOXD_API_KEY只留在宿主绝不送入 VM。用户密钥通过--env注入重复使用--env KEYVALUE标志密钥进入 VM 内 Agent 进程的环境变量从不进入源码压缩包。.env风格文件永不随包发送部署后的 Agent 运行在公网 IP 的 VM 上误打包.env就等于公之于众。打包器会静默丢弃以下内容并向 stderr 打印被丢弃清单文件模式.env*、*.pem、*.key、id_rsa*、credentials*.json、*.kdbx、*.p12、*.pfx、*.kubeconfig目录.aws/、.ssh/、.gnupg/、.bindu/上述敏感文件永不发送、不可关闭的规则在 source_packager.py 中硬编码实现且该检查独立于.gitignore——因为用户经常在本地检出了真实的.env见 source_packager.py 的注释说明。部署前可用--dry-run查看完整的丢弃清单。六、部署前预览--dry-runbindu deploy agent.py --runtimeboxd --dry-run该命令只打印部署计划不会触碰任何 VM目标 VM 名称源码根目录入口脚本资源配置vCPU / 内存 / 磁盘 / 自动挂起 / on-exit / bindu 版本环境变量键名值隐藏压缩包文件数量与压缩后大小会被静默丢弃的敏感文件清单典型输出如下示例来自 docs/runtime/quickstart.mdDRY RUN — nothing will be deployed. agent name: runtime-boxd-example source root: /Users/you/playground entry script: agent.py provider: boxd vcpu / memory: 2 / 4G disk: 20G auto_suspend: 0s on_exit: suspend bindu_version: local tarball: 4 files, 2.4 KB compressed若计划中的名称、资源配置或包体大小异常例如目录里混入了 200 MB 数据集此时修正成本最低。七、源码打包规则项目根目录通过从入口脚本向上逐级查找以下标记自动发现pyproject.toml、setup.py、requirements.txt、.git优先级从高到低见 source_packager.py 与find_project_root。总是发送*.py、*.toml、*.txt、*.md、*.json、*.yaml、.env注意*.env与.env均被敏感规则排除此处文档表述指常规文本类源码文件。总是排除除敏感文件外目录__pycache__/、.git/、.venv/、venv/、node_modules/后缀*.pyc、*.pyo、*.log、*.sqlite、*.db以及.gitignore与.binduignore中列出的所有内容这些默认排除规则同样见 source_packager.py默认忽略目录还包含.pytest_cache、.mypy_cache、.ruff_cache。.binduignore的语法与.gitignore一致两者合并解析见 source_packager.py。硬性上限50 MB压缩后。超出时打包立即失败并提示把大文件加入.binduignore见 source_packager.py 的SourceTooLargeError。典型写法# .binduignore .venv/ data/ *.bin八、开发体验日志与 Shellbindu logs agent— 把 VM 内 Agent 的 stdout/stderr 流式输出到终端。由于 boxd 0.1.x 的服务器端StreamLogsRPC 尚未实现实现方式是借助流式 exec 执行tail -F追读 VM 内的 Agent 日志文件见 boxd_provider.py 与AGENT_LOG_PATH /tmp/bindu-agent.log。tail -F在文件缺失或轮转时持续轮询正好覆盖 Agent 启动的空窗期优点是只看到 Agent 自身的输出没有内核/启动噪音。传--no-follow只打印当前已有内容后退出。bindu shell agent— 在 Agent 的 VM 上打开交互式 Shell工作目录为/app下的源码目录。注意源码实际解压到/home/boxd/appAPP_DIR见 boxd_provider.py因为 stock boxd 镜像上/app需要 sudobindu serve则以/home/boxd/app为工作目录启动。九、源码级原理BoxdRuntimeProvider的执行链把整个部署流程串联起来的核心是 bindu/runtime/boxd_provider.py 中的deploy()见 boxd_provider.py其步骤与文档生命周期一一对应校验凭证宿主环境必须存在BOXD_API_KEY或BOXD_TOKEN解析 VM_resolve_vm按名称幂等地获取或创建已存在则复用含网络代理配置ProxyEntry(name, port3773)指向 Bindu 默认端口等待 VM 就绪box.create()返回时 VM 只是运行中内部的 exec/write_file 服务还要数秒才能响应因此用box.exec(true)轮询探测设置代理端口每次部署都重放set_proxy_port(3773)因为 boxd 0.1.1 在创建时并不总是遵守NetworkConfig.proxies而热复用会保留旧配置幂等操作A2 模式并发执行_ship_source与若--bindu-versionlocal_ship_bindu_source然后依据是否存在pyproject.toml/requirements.txt执行依赖安装——安装命令链用连接以短路失败启动 Agentsetsid nohup python3 script后台启动setsid使进程脱离 gRPC exec 通道避免通道关闭时级联 SIGHUPPID 写入/tmp/bindu-agent.pid并通过BINDU_PUBLIC_URL环境变量把公网地址告知 Agent健康检查以 1 秒间隔轮询{url}/health60 秒超时见 boxd_provider.py返回句柄RuntimeHandle携带name、url、providerboxd以及vm_id、public_ip等元数据见 base.py。值得注意的两处工程细节上传完整性校验_safe_write_file对每次box.write_file做 sha256 双向校验失败自动重试最多 3 次——这是针对 boxd 0.1.1 间歇性静默截断上传azin-tech/boxd#45的防御见 boxd_provider.py。依赖安装使用--break-system-packagesstock boxd 镜像是 Ubuntu 24.04系统 Python 受 PEP 668externally managed保护普通pip install会被拒绝VM 是单租户环境因此放行见 boxd_provider.py。--bindu-versionlocal的源码打包会排除assets/、examples/、docs/、tests/、gateway/、sdks/、i18n/等与 Python 包运行时无关的目录保持压缩包足够小以避开 boxd 的 gRPC 消息大小限制见 boxd_provider.py。仓库中 tests/unit/runtime/test_boxd_provider.py 对上述行为有完整的单测覆盖全部 mock 掉 boxd SDK例如test_resolve_vm_creates_when_not_found验证 VM 不存在时创建、存在时复用_wire_safe_write_file则模拟了 sha256 校验回环。十、部署后的验证与调用部署成功会输出类似✓ my-agent serving at https://my-agent.boxd.sh [my-agent] INFO: Started server process [12] [my-agent] INFO: Application startup complete.随后可用curl验证健康状态并获取 Agent 的公开身份卡片curl https://my-agent.boxd.sh/health curl https://my-agent.boxd.sh/.well-known/agent.jsonAgent 在 boxd 微VM 中部署后通过/.well-known/agent.json返回的 Agent Card 配置含 DID 身份、协议版本、输入输出模式等示意如下——图中标注的 LIVE - BOXD MICROVM 即表示该卡片正由 boxd 微VM 中的运行实例实时提供发送 A2A 消息的完整流程message/send提交任务、tasks/get轮询结果响应含did.message.signature签名可参考 docs/runtime/quickstart.md 中的可复制命令。十一、A2 与 A1自定义镜像对照当依赖无法通过pip install在 VM 内构建时如 Rust 工具链、系统库使用--image走 A1 模式A1/A2 的核心差异如下源自 docs/runtime/custom-image.mdA2默认源码装载A1自定义镜像前期准备无直接部署构建并推送镜像迭代速度快热路径 1–3 秒慢构建 推送 重新部署可复现性取决于pip install解析到相同依赖由镜像哈希固定原生依赖仅限 VM 内pip install能构建的镜像构建期可编译任意依赖镜像仓库不需要需要A1 模式依然复用相同的健康检查、日志流式与 on-exit 生命周期管理只是跳过了源码上传与pip install两步boxd_provider.py 中config.image is None分支即 A2否则仅创建 VM 后等待健康。十二、故障排查速查表以下排查表完整继承自 docs/runtime/boxd.md问题可能原因处理方法BOXD_API_KEY or BOXD_TOKEN must be set宿主环境缺少凭证export BOXD_API_KEYbxk_...script did not call bindufy()入口脚本在到达bindufy()前抛错或根本没调用先直接运行脚本python agent.py查看底层错误agent at url did not become healthy within 60sVM 已启动但 Agent 未成功启动运行bindu logs agent检查常见原因缺少依赖、脚本语法错误、VM 内 3773 端口被占用pip install失败依赖不在 PyPI 或原生编译失败改用 A1自定义镜像在镜像构建期安装依赖源码超过 50 MB混入了大型数据文件加入.binduignoreVM 内旧版 bindu 拒绝新特性PyPI 已发布版本落后于宿主传--bindu-versionlocal把宿主源码送入 VMupload to /tmp/... corrupted after 3 attemptsboxdwrite_file截断azin-tech/boxd#45重新执行bindu deploy该损坏是间歇性的重试几乎总能成功重新部署后运行的是旧代码boxd 0.1.x 偶尔传输截断的压缩包部署现在已对每次上传做 sha256 校验并重试若仍出现运行bindu shell agent比对cat /tmp/bindu-agent.pid与pgrep python3十三、已知限制目前仓库仅内置boxd一个运行时提供方RuntimeProvider抽象支持扩展e2b、modal、fly.io 等但尚未捆绑见 docs/runtime/README.md。无源码热监听/自动重新部署修改脚本后需要重新执行bindu deploy。暂无声明式清单bindu.toml所有部署配置通过 CLI 标志传入声明式配置计划作为后续功能。如需从零走一遍完整部署流程建议先阅读 docs/runtime/quickstart.md含可复制的 A2A 消息示例与成本控制建议再回到本文精细调参自定义镜像场景参考 docs/runtime/custom-image.md。赞分享【免费下载链接】BinduBindu: The identity, communication, and payments layer for AI agents.项目地址https://gitcode.com/gh_mirrors/bin/Bindu点击查看免费下载相关推荐Flue boxd 沙箱适配器把 boxd 托管 Linux microVM 接入 Flue AgentFlue boxd 沙箱适配器把 boxd 托管 Linux microVM 接入 Flue Agent 本篇基于 Flue 官方文档 boxd 沙箱页 ht人工智能大模型AI AgentAgent 框架工具调用Agent 沙箱MCP ClientsDeep-Live-Cam 上手指南3 步实现单图实时 AI 换脸Deep Live Cam 上手指南3 步实现单图实时 AI 换脸 Deep Live Cam 是一款开源实时换脸工具只需一张源脸照片即可在摄像头直播与视Qwen Code 五种审批模式Plan、Ask Permissions、Auto-Edit、Auto、YOLO怎么选Qwen Code 五种审批模式Plan、Ask Permissions、Auto Edit、Auto、YOLO怎么选 Qwen Code 在终端里运行上一篇Agent-Skills-for-Context-Engineering 路由基准测试解析用 LLM-as-Router 验证 15 个 Agent Skill 的描述质量下一篇Iosevka 14.0.1 更新解析$ 与 7 的重量平衡及月相符号新增创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
