创建沙箱 SSH 会话凭据

向已配置的沙箱服务申请 SSH 网关连接信息和短期凭据;请求成功不等于已经建立 SSH 连接。

POST https://api.moi.matrixorigin.cn/v5/agent-sandboxes/{sandbox_id}/ssh-session

调用前准备

准备目标工作区的个人访问令牌与相应操作权限;环境、令牌、工作区和沙箱 ID 保持一致。公共对象和结果确认说明资源身份、字段及状态。示例的资源值须替换为实际值。

请求

curl -X POST "https://api.moi.matrixorigin.cn/v5/agent-sandboxes/$SANDBOX_ID/ssh-session" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"

sandbox_id 为路径必填;无请求体。需要当前沙箱终端权限,外部提供商必须支持 SSH 会话。

成功响应

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "token": "<ssh-session-token>",
    "gateway_host": "ssh.example.com",
    "gateway_port": 443,
    "gateway_scheme": "https",
    "host_key_fingerprint": "<provider-fingerprint>",
    "expires_at_ms": 1794384060000
  }
}

HTTP 200 的数据含义如下;示例值不是默认配置。

字段

类型

说明

code

string

成功时为 OK。

msg

string

响应说明。

data.token

string

SSH 会话短期凭据,按网关协议使用,不打印或持久记录。

data.gateway_host

string

网关主机。

data.gateway_port

integer

网关端口。

data.gateway_scheme

string

有值时返回网关协议。

data.host_key_fingerprint

string

有值时返回主机密钥指纹。

data.expires_at_ms

integer

提供商返回的过期时间,Unix 毫秒;以返回值为准,不套用终端 token 的 60 秒。

结果确认

客户端按返回网关和提供商协议连接,并验证主机身份。这里不规定未核实的 ssh 命令行、用户名或通用转发方式;Go/Python 方法只获取连接信息,不拨号。

错误处理

按 HTTP 状态及响应 code 判断;公共错误与恢复区分参数、权限、配额、提供商和结果未知。错误不证明尚未产生资源,也不能当成重试或清理已经完成。

最后更新于