The terminal, as a socket

GET /v1/sandbox/{id}/terminal/ws

Upgrades to a WebSocket carrying a login shell on a pseudo-terminal inside the sandbox — for a host that brings its own emulator. Requires ticket; a missing, expired or already-spent one answers 401 without upgrading.

THE WIRE. A text frame is stdin, unless it is the one control object {"resize":{"cols":N,"rows":M}}; a binary frame is always stdin. Output comes back as BINARY frames, because a pty emits arbitrary bytes cut at arbitrary offsets and a text frame carrying half a rune is one the browser closes the connection over.

arg names a SESSION: the shell runs under tmux new -A -s <arg>, which attaches to that session if it exists and creates it if it does not — so one sandbox holds as many terminals as a caller has names for. It is 1-64 characters of letters, digits, - or _ and may not begin with -; anything else is 400. Without arg the shell is unnamed and unmultiplexed.

The shell is zsh -l, falling back to bash -l and then to sh -l, and to the plain shell again when the image has no tmux. Every step is a preference and none is a requirement: whatever else the image carries — the hanzo CLI included — is a command to type, never a condition for getting a prompt.

Request

1 field.

Response

The document declares no response body for this operation. It answers 200 on success and the platform error shape on failure — see Errors.

Examples

hanzo sandboxes terminal ws <id>

import { Configuration, SandboxApi } from 'hanzoai';

const api = new SandboxApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getSandboxByIdTerminalWs({ id: 'id' });

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import SandboxApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = SandboxApi(client).get_sandbox_by_id_terminal_ws(id='id')

cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)

resp, _, err := client.SandboxAPI.GetSandboxByIdTerminalWs(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_cloud::apis::{configuration::Configuration, sandbox_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = sandbox_api::get_sandbox_by_id_terminal_ws(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.SandboxApi;

ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));

var result = new SandboxApi(client).getSandboxByIdTerminalWs();

curl https://api.hanzo.ai/v1/sandbox/<id>/terminal/ws \
  -H "Authorization: Bearer $HANZO_API_KEY"

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "list_sandboxes"
         }
       }
     }'

Sandbox API · All Hanzo APIs · Interactive reference