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

  1. Obtain a sandbox ID from listing/creation and read target phase and actual availability.

  2. Request a Terminal token using a personal access token and target workspace. Retain data.token and data.expires_at.

  3. Before expiry, construct same-environment wss://…/agent-sandboxes/{sandbox_id}/terminal/ws?token=<URL-encoded-token>&cols=80&rows=24 and perform a standard WebSocket handshake. Use the current environment’s host/prefix and URL-encode the token.

Query field

Type

Description

token

string

Valid signed token for this sandbox, binding identity, role candidates, and workspace.

cols

integer

Initial columns; missing, invalid uint32, or0 uses 80.

rows

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

{"type":"resize","cols":120,"rows":30}

Resize the terminal.

Server → binary

Raw output bytes

Terminal output; not necessarily UTF-8 or JSON.

Server → text JSON

{"type":"exit","code":0}

Terminal process exit observed normally. code is the actual exit code;0 is only an example.

Server → text JSON

{"type":"error","code":0,"message":"<localized message>"}

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.

Last updated on