<span id="创建沙箱-ssh-会话凭据"></span>

# Create sandbox SSH session credentials

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

Request SSH gateway connection information and short-lived credentials from the configured sandbox service. Request success does not mean an SSH connection is established.

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

<span id="调用前准备"></span>

## Before you call this API

Prepare a personal access token and the required privileges for the target workspace. Keep environment, token, workspace, and sandbox ID consistent. [Common objects and result confirmation](objects.md) explains identities, fields, and states. Replace example resource values with actual ones.

<span id="请求"></span>

## Request

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Request example

```bash
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"
```

:::::
:::::{tab-item} Parameters

sandbox_id is required in the path; no body. Requires current sandbox terminal privileges and an external provider supporting SSH sessions.

:::::
::::::
:::::::

<span id="成功响应"></span>

## Successful response

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

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

:::::
:::::{tab-item} Fields

Meaning of HTTP 200 data below. Example values are not default configuration.

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | OK on success. |
| `msg` | string | Response explanation. |
| `data.token` | string | Short-lived SSH session credential for the gateway protocol. Do not print or persist it in records. |
| `data.gateway_host` | string | Gateway host. |
| `data.gateway_port` | integer | Gateway port. |
| `data.gateway_scheme` | string | Gateway protocol; returned when present. |
| `data.host_key_fingerprint` | string | Host key fingerprint; returned when present. |
| `data.expires_at_ms` | integer | Provider-returned expiration in Unix milliseconds. Follow the response, not terminal-token60-second expiry. |

:::::
::::::
:::::::

<span id="结果确认"></span>

## Confirm the result

Connect using the returned gateway/provider protocol and verify host identity. No unverified ssh command, username, or universal forwarding method is prescribed here. Go/Python methods retrieve connection information only; they do not dial.

<span id="错误处理"></span>

## Error handling

Check HTTP status and response code. [Shared errors and recovery](objects.md#错误与恢复) distinguishes parameter, permission, quota, provider, and unknown-result cases. Errors do not prove that no resource was created or that retry/cleanup completed.
