universe docs source
▸ browse docs
introduction.md quickstart.md architecture.md
configuration/
node-config.md instance-config.md templates.md database.md
runtimes/
overview.md screen-tmux.md docker.md kubernetes.md
extensions/
overview.md storage-s3.md databases.md metrics.md tailscale.md gitops.md argocd.md discord.md building-extensions.md
minecraft/
overview.md plugins.md proxy-plugins.md api.md
operations/
console-commands.md logging.md networking.md security.md
api-reference/
overview.md authentication.md instances.md configurations.md templates.md cluster.md node.md commands.md websockets.md
docs /api-reference /websockets

WebSockets

Two WebSocket endpoints stream data over a persistent connection: a per-instance live log stream and an interactive console to the Master. Both perform the bearer-token handshake during the HTTP upgrade and exchange plain text frames.

Where the REST endpoints return a snapshot, the WebSocket endpoints keep a connection open and stream text frames as events happen. There are two: a live log stream scoped to a single instance, and an interactive console attached to the Master. Both upgrade from HTTP and carry the same bearer token.

!
warning

Both WebSocket endpoints require a token with ALL permission. The token is validated during the upgrade handshake; an unauthenticated handshake is rejected with 401 Unauthorized before the socket opens.

Connecting

Open a WebSocket against the Master’s API port and supply the token as an Authorization header on the handshake request. On success the server responds with 101 Switching Protocols and the connection stays open. Messages flow as UTF-8 text frames in both directions.

i
note

Use ws:// against a plain HTTP Master, or wss:// when the API is fronted by TLS. The path and authentication are identical in both cases.

Live log stream

ws://<master>:7000/api/instances/{id}/live-log

Streams live log output from a single instance. New log lines are pushed as text frames as the process emits them. This works across every runtime, so the stream is identical whether the instance runs under screen, tmux, a bare process, Docker, or Kubernetes.

ParameterInDescription
idpathThe 6-character instance ID to stream. Required.
GET /api/instances/a1b2c3/live-log HTTP/1.1
Host: <master>:7000
Upgrade: websocket
Connection: Upgrade
Authorization: Bearer YOUR_TOKEN
✦
tip

For a one-time tail rather than a live stream, call GET /api/instances/{id}/logs?lines=N on the Instances API instead.

Interactive console

ws://<master>:7000/api/console

Opens an interactive console session to the Master. Send console commands as text frames; responses stream back as text frames. Unlike POST /api/commands/execute, which runs one command and returns its captured output, the console socket keeps a session open so output arrives as it is produced.

GET /api/console HTTP/1.1
Host: <master>:7000
Upgrade: websocket
Connection: Upgrade
Authorization: Bearer YOUR_TOKEN

Client example

Most WebSocket clients can set the Authorization header on the handshake. Using wscat:

# Stream live logs with wscat
wscat -c ws://<master>:7000/api/instances/a1b2c3/live-log \
  -H "Authorization: Bearer YOUR_TOKEN"

# Interactive console
wscat -c ws://<master>:7000/api/console \
  -H "Authorization: Bearer YOUR_TOKEN"
i
note

If your client cannot attach custom headers to the handshake, place a reverse proxy in front of the Master that injects the Authorization header for the upgrade request.

Endpoint summary

EndpointDirectionPurpose
/api/instances/{id}/live-logserver → clientLive log output for one instance.
/api/consoleclient ↔ serverInteractive Master console session.
Instances API

Fetch a one-time log tail and send commands to an instance’s stdin.
Commands API

Run a single console command over REST and capture its output.
Authentication

How the bearer token is validated during the WebSocket handshake.