<span id="连接沙箱交互终端"></span>

# 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.

```text
GET https://api.moi.matrixorigin.cn/v5/agent-sandboxes/{sandbox_id}/terminal/ws
```

<span id="连接准备"></span>

## Connection preparation

1. Obtain a sandbox ID from listing/creation and read target phase and actual availability.
2. Request a [Terminal token](get-terminal-token.md) 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.

<span id="消息协议"></span>

## 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.

<span id="会话结束"></span>

## 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.
