WebSocket Protocol

Nullspace exposes several WebSocket channels:

Channel	Use
`/v1/machines/{id}/ws`	Streaming exec, PTY, and machine file-watch control messages.
`/v1/volumes/{id}/ws`	Direct volume watch events.
`/v1/lifecycle/ws`	Lifecycle event stream.
`/v1/monitor/ws`	Fleet/machine monitor stream for snapshots, updates, metrics, processes, and errors.
`/v1/machines/{id}/access/desktop-viewer/ws`	Managed desktop viewer bridge.
`machine.get_websocket_url(port)`	Signed public WebSocket access to a service running in the machine.
`machine.get_host_info(22).websocket_url`	Legacy signed SSH-over-WebSocket proxy URL for older port-22 fallback deployments.

Lifecycle and machine control channels send WebSocket Ping frames every 15 seconds and close after two missed Pong responses. PTY clients should treat a close without pty_exited as a transport disconnect. Default SSH access uses the certificate-backed relay through nullspace ssh and does not consume one of these WebSocket channels.

SDK examples

machine.commands.run(
    "for i in 1 2 3; do echo $i; sleep 1; done",
    shell=True,
    on_stdout=lambda data: print(data, end=""),
)

session = machine.pty.create_session()
session.send_input("pwd\n")

from nullspace import Lifecycle

lifecycle = Lifecycle()
subscription = lifecycle.subscribe(on_event=lambda event: print(event.operation))
subscription.stop()
lifecycle.close()

from nullspace import Monitor

monitor = Monitor()
subscription = monitor.subscribe(
    interval_ms=1000,
    include_processes=True,
    on_metrics=lambda event: print(event.metrics),
)
subscription.stop()

Public exposed-port WebSockets

info = machine.get_host_info(8080)
print(info.websocket_url)

The signed URL is scoped to the machine, port, and WebSocket transport. Missing or expired edge tokens fail before traffic reaches the machine service. Custom clients send a monitor_subscribe message to /v1/monitor/ws:

{
  "type": "monitor_subscribe",
  "id": "monitor_1",
  "interval_ms": 1000,
  "include_processes": true
}

Server messages include snapshot, update, metrics, processes, and error payloads. Use SDK callbacks unless you need a non-Python client.

Full protocol

The longer repository protocol reference, including message shapes, lives at docs/product/reference/websocket-protocol.md.

Python SDK

Python SDK objects

TypeScript SDK

CLI

Platform reference

WebSocket Protocol

SDK examples

Public exposed-port WebSockets

Full protocol

​SDK examples

​Public exposed-port WebSockets

​Monitor subscribe message

​Full protocol

​Related

SDK examples

Public exposed-port WebSockets

Monitor subscribe message

Full protocol

Related