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

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.

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.

Last updated on