# SoloCore Agent Gateway

SoloCore Agent Gateway 是一个 Apache-2.0 开源的 Agent 互联入口。它通过设备主动出站连接，让无需公网入站端口的本地 Agent 安全接入托管 Hub，并向 MCP 与 A2A 客户端暴露受控能力。

当前状态：`v0.2.9` 保持 32 MiB 受控任务 payload 与 24 小时待审批配对窗口；标准 inbox 可接收 `solocore.inbox` 和文档型 `solocore.message`。已登记设备仍使用短期令牌自动刷新和自动重连。

## 快速开始

已发布 npm 包时可固定版本安装；未发布前从公开仓库固定 tag `v0.2.9` 构建：

```bash
git clone --branch v0.2.9 --depth 1 https://github.com/lihongqing2001-gif/SoloCoreAgentGateway.git solocore-agent-gateway
cd solocore-agent-gateway && npm ci && npm run build
```

Aily 无 App ID、OpenAPI Scope 或管理员权限时，设备本地生成 Ed25519 密钥并请求人工审批：

```bash
node dist/cli.js connect request --gateway https://solocore.cn \
  --agent aily-agent --credential-backend file-0600
```

审批后使用 `connect await` 完成登记，再通过 `chat send --stdin --wait` 与 `inbox pull` 收发。待审批请求可保留 24 小时，已配对设备正常使用不需重复审批。受控 payload 最大为 32 MiB；更大的文档请先发布为只读资源，再在任务中传递其 alias/path。可直接复制给 Aily 的完整一条消息见 [Aily 接入指令](docs/delivery/aily-one-command.md)。托管 Hub 可用 [Docker Compose](deploy/compose.yaml) 全新安装；已有 Nginx 占用 80/443 的主机使用 [回环部署配置](deploy/compose.nginx-host.yaml)。URL 不是认证方式，仍须使用设备凭据或 Secret 中的授权头。

## 当前公网协议入口

- 控制面：`https://solocore.cn`
- MCP Streamable HTTP：`https://solocore.cn/mcp`
- A2A：`https://solocore.cn/a2a`
- 设备主动出站 Relay：`wss://solocore.cn/v1/device`

规划中的独立子域为：

- 控制面：`https://agents.solocore.cn`
- MCP Streamable HTTP：`https://mcp.solocore.cn/mcp`
- A2A：`https://a2a.solocore.cn/a2a`
- 设备主动出站 Relay：`wss://relay.solocore.cn/v1/device`

独立子域需在 DNS 与 TLS 验证完成后才切换使用；当前 `solocore.cn` 同域入口已验证可用。Aily 示例见 [config/aily.mcp.example.json](config/aily.mcp.example.json)，Token 必须进入 Aily Secret，不得写入配置文件。

## 首版边界

- 允许：Agent 发现、能力查询、受控任务传递、显式发布目录中的只读资源、健康检查和诊断。
- 禁止：任意 Shell、任意文件写入、凭据访问、生产操作和未注册命令。
- 默认：设备经 HTTPS/WSS 443 主动出站连接，不开放路由器或防火墙入站端口。
- 可选：Aily 直连托管 MCP；高级用户可使用经检查的自托管 direct 配置。

设计、安全审查、验证状态和外部阻塞见 [docs/INDEX.md](docs/INDEX.md)。

## 安全提示

Enrollment Key 只能通过隐藏交互输入或 Docker Secret 提供，不得出现在命令行、聊天、Git、日志或明文配置中。仓库只包含示例与凭据元数据。

## License

Apache-2.0，见 [LICENSE](LICENSE)。