aws-runtime-bridge

AgentsWorkStudio 机器实例运行时桥接服务，用于在实例上管理 Agent 运行时、终端、配置与回调通信。

aws-runtime-bridge 面向机器实例宿主机运行，需要访问本机工作区、终端、运行时配置和文件系统；不要将它作为 Docker/Compose 服务部署。Docker Compose 仅用于仓库根目录的 aws-dashboard 与 aws-mcp-server Web 服务。

全局安装

从 npm 包安装时：

npm install -g aws-runtime-bridge

安装脚本会在 macOS、Linux 与常见 Unix 平台自动为 CLI 入口补齐可执行权限；Windows 平台无需 chmod，会自动跳过该步骤。

从当前仓库安装时：

cd aws-runtime-bridge
npm install
npm run build
npm install -g .

启动

首次运行 awsb / aws-bridge 时，如果不存在 ~/.aws-bridge/config.json，CLI 会进入交互式配置引导；也可以在提示中选择跳过。跳过时仍会创建配置文件并自动生成随机 connectionKey，终端会输出该密钥，请保存后在 server/面板连接此 Bridge 时使用。非交互环境（如 systemd、CI 后台启动）不会阻塞等待输入，也会自动生成随机 connectionKey 并跳过引导。

引导会生成类似下面的配置：

{
  "connectionKey": "gkmzjaznX55..",
  "autoRegisterTargets": [
    {
      "serverUrl": "http://127.0.0.1:8080",
      "instanceName": "至强主机",
      "userKey": "aws_live_crh_g0GGrg5IntODg1sFwnas7qf4yGrcwoisDWPBtd8",
      "registerIp": "127.0.0.1"
    }
  ]
}

如需在交互式终端中也强制跳过引导，可设置 AWS_BRIDGE_SKIP_SETUP=true；此时仍会生成随机 connectionKey。

AWS_RUNTIME_BRIDGE_PORT=18081 \
AWS_RUNTIME_HOME_DIR=/opt/agentswork/runtime-home \
aws-bridge

当 ~/.aws-bridge/config.json 只配置了一个 autoRegisterTargets[].serverUrl 时，bridge 会自动将该地址作为 /runtime/ping 回连调度中心的地址，无需重复配置 AWS_RUNTIME_SCHEDULER_BASE_URL。如需显式覆盖，或同一个 bridge 配置了多个自动注册目标，请设置 AWS_RUNTIME_SCHEDULER_BASE_URL 指定当前实例测试连接时应回连的调度中心。

If an existing runtime binding still stores an old scheduler URL such as http://127.0.0.1:8080, re-run auto-register, refresh the runtime token, or re-pair after changing serverUrl / AWS_RUNTIME_SCHEDULER_BASE_URL; bridge will not reuse a token issued for the old scheduler URL against the new scheduler URL.

aws-runtime-bridge 命令仍作为兼容别名保留。安装 aws-runtime-bridge 后，包内会随附 aws-client-agent-mcp 的编译产物；bridge 启动时只负责准备该 MCP 产物，不再在 Agent 启动时默认动态注入 aws-mcp。

请在面板中为目标运行时安装/配置 MCP；这样 Claude Code、Codex、OpenCode 等 SDK 启动模式都走一致的持久化 MCP 配置链路。

如需使用自定义 MCP 可执行文件，可设置：

AWS_CLIENT_AGENT_MCP_COMMAND=/absolute/path/to/aws-client-agent-mcp \
AWS_CLIENT_AGENT_MCP_ARGS='[]' \
aws-bridge

systemd 服务管理

Linux systemd 环境中可使用 CLI 安装或卸载 awsb.service。安装命令会写入 systemd unit、执行 systemctl daemon-reload、启用开机自启，并在服务尚未运行时立即启动：

sudo awsb service install

卸载命令会在服务运行时先停止服务，禁用开机自启，删除 unit 文件，并重新执行 systemctl daemon-reload：

sudo awsb service uninstall

service 命令仅支持 Linux systemd；在其他平台会直接返回清晰错误。生成的 unit 会设置 AWS_BRIDGE_SKIP_SETUP=true，避免后台服务启动时阻塞在交互式配置引导。

关键环境变量

| 变量名 | 说明 | 默认值 | | --- | --- | --- | | AWS_RUNTIME_BRIDGE_PORT | Bridge HTTP 端口 | 18081 | | AWS_RUNTIME_SCHEDULER_BASE_URL | aws-mcp-server 地址；显式配置优先级最高，未配置且只有一个 autoRegisterTargets[].serverUrl 时自动使用该地址 | 单目标自动注册地址；否则 http://localhost:8080 | | AWS_RUNTIME_HOME_DIR | Bridge 管理配置与状态的主目录 | 当前用户 Home | | AWS_RUNTIME_CORS_ORIGINS | 允许访问 bridge 的来源，逗号分隔 | 本地开发地址 |

生产环境中，bridge 最终解析出的调度中心地址必须是机器实例可访问的 aws-mcp-server 地址，不能使用不可达的容器内 localhost。如果配置了多个 autoRegisterTargets，bridge 不会静默选择第一个目标，需通过 AWS_RUNTIME_SCHEDULER_BASE_URL 或后续多调度中心身份路由明确目标。