# aws-runtime-bridge

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

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

## 全局安装

从 npm 包安装时：

```bash
npm install -g aws-runtime-bridge
```

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

从当前仓库安装时：

```bash
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` 并跳过引导。

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

```json
{
  "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`。

```bash
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 可执行文件，可设置：

```bash
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`、启用开机自启，并在服务尚未运行时立即启动：

```bash
sudo awsb service install
```

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

```bash
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` 或后续多调度中心身份路由明确目标。
