WebSockets

The hzel API exposes two WebSocket endpoints for real-time interaction with your containers.

Terminal — GET /ws/terminal/{container_id}

Opens an interactive terminal session to a container.

Connection

wss://api.hzel.org/ws/terminal/{container_id}

Pass your bearer token in the Authorization header or as a token query parameter, depending on your client's capabilities.

Protocol

All messages in both directions are JSON text frames.

Client → Server:

{ "type": "input", "data": "ls -la\n" }
{ "type": "resize", "cols": 120, "rows": 40 }
{ "type": "file_upload", "path": "/root/file.txt", "data": "<base64-encoded content>" }

Server → Client:

{ "type": "opened", "container_id": "..." }
{ "type": "output", "data": "total 42\n..." }
{ "type": "resized", "cols": 120, "rows": 40 }
{ "type": "file_uploaded", "path": "/root/file.txt" }
{ "type": "file_upload_error", "path": "/root/file.txt", "message": "..." }
{ "type": "error", "message": "..." }
{ "type": "closed" }

The first opened frame is sent by the server as soon as the session is established. The first message from the client should be a resize to set the initial terminal dimensions — if omitted, the server defaults to 80×24. Closing the WebSocket connection ends the session cleanly.

Binary frames are also accepted from the client and treated as raw terminal input for convenience.

Access

Only the container owner or users with operator-level access can open a terminal session. Unauthorized connection attempts are rejected before the WebSocket upgrade completes.

Job Output — GET /ws/jobs/{job_id}