Connect an interactive sandbox terminal¶
Obtain a short-lived token for the target sandbox, then connect through WebSocket. This endpoint restores identity from the terminal token and revalidates current authorization. Do not place a personal access token in the token query parameter.
GET https://api.moi.matrixorigin.cn/v5/agent-sandboxes/{sandbox_id}/terminal/ws
Connection preparation¶
Obtain a sandbox ID from listing/creation and read target phase and actual availability.
Request a Terminal token using a personal access token and target workspace. Retain
data.tokenanddata.expires_at.Before expiry, construct same-environment
wss://…/agent-sandboxes/{sandbox_id}/terminal/ws?token=<URL-encoded-token>&cols=80&rows=24and perform a standard WebSocket handshake. Use the current environment’s host/prefix and URL-encode the token.
Query field |
Type |
Description |
|---|---|---|
|
string |
Valid signed token for this sandbox, binding identity, role candidates, and workspace. |
|
integer |
Initial columns; missing, invalid uint32, or0 uses 80. |
|
integer |
Initial rows; missing, invalid uint32, or0 uses 24. |
An Origin must match the same host or deployment allowlist. Clients without Origin still require valid tokens/current privileges. Unready signing, identity-restoration, or provider services mean registered routes/token success alone cannot establish connectivity.
Message protocol¶
Direction/type |
Payload |
Purpose |
|---|---|---|
Client → binary |
Raw input bytes |
Write terminal input. |
Client → text |
|
Resize the terminal. |
Server → binary |
Raw output bytes |
Terminal output; not necessarily UTF-8 or JSON. |
Server → text JSON |
|
Terminal process exit observed normally. code is the actual exit code;0 is only an example. |
Server → text JSON |
|
Service error after upgrade. code:0 is the current structure’s zero value, not process success. |
Each client inbound WebSocket message is limited to 64 KiB. Unknown/invalid text is not a command execution API; do not wrap shell commands in invented JSON fields. Go/Python terminal helpers send input, resize, and receive raw content, but clients must recognize exit/errors. Arbitrary text or connection closure does not establish success.
Session termination¶
Connections last at most30 minutes, with authorization rebound/rechecked roughly every 30 seconds. Revocation, deletion, service errors, and disconnection end them. Token60-second expiry controls preconnection validity. Established connections are not guaranteed either60 seconds or30 minutes of availability. Close local connections on disconnect. Recheck state/credentials before reconnecting and retain unknown results when no exit message was received.
Handle preupgrade failures as HTTP errors and postupgrade failures as messages/closure. URLs contain sensitive tokens; avoid recording complete URLs. External command execution or real-session acceptance is not equivalent to a local handshake test.