Create sandbox SSH session credentials¶
Request SSH gateway connection information and short-lived credentials from the configured sandbox service. Request success does not mean an SSH connection is established.
POST https://api.moi.matrixorigin.cn/v5/agent-sandboxes/{sandbox_id}/ssh-session
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 explains identities, fields, and states. Replace example resource values with actual ones.
Request¶
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 is required in the path; no body. Requires current sandbox terminal privileges and an external provider supporting SSH sessions.
Successful response¶
{
"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
}
}
Meaning of HTTP 200 data below. Example values are not default configuration.
Field |
Type |
Description |
|---|---|---|
|
string |
OK on success. |
|
string |
Response explanation. |
|
string |
Short-lived SSH session credential for the gateway protocol. Do not print or persist it in records. |
|
string |
Gateway host. |
|
integer |
Gateway port. |
|
string |
Gateway protocol; returned when present. |
|
string |
Host key fingerprint; returned when present. |
|
integer |
Provider-returned expiration in Unix milliseconds. Follow the response, not terminal-token60-second expiry. |
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.
Error handling¶
Check HTTP status and response code. Shared errors and recovery distinguishes parameter, permission, quota, provider, and unknown-result cases. Errors do not prove that no resource was created or that retry/cleanup completed.