​
Start a viewer

from nullspace import Machine

with Machine.create(template="desktop", timeout=300) as machine:
    stream = machine.desktop.stream.start(view_only=False)
    print(stream.viewer_url)

nullspace machine desktop stream start mch_123

curl -X POST "${NULLSPACE_API_URL}/v1/machines/mch_123/desktop/stream/start" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
  -H "Content-Type: application/json" -d '{"view_only": false}'
The response carries the public viewer_url and a short-lived auth_key.

​
View-only mode

stream = machine.desktop.stream.start(view_only=True)
print(stream.viewer_url)

nullspace machine desktop stream start mch_123 --view-only

curl -X POST "${NULLSPACE_API_URL}/v1/machines/mch_123/desktop/stream/start" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
  -H "Content-Type: application/json" -d '{"view_only": true}'
View-only mode is enforced by the viewer session, not just by the browser UI. Use it when you want someone to inspect a desktop without sending mouse, keyboard, or clipboard input back into the machine.

​
Auth key and raw stream info

info = machine.desktop.stream.info()
auth_key = machine.desktop.stream.get_auth_key()
viewer_url = machine.desktop.stream.get_viewer_url(auth_key)
print(info, viewer_url)

nullspace machine desktop stream info mch_123
nullspace machine desktop stream auth-key mch_123
nullspace machine desktop stream viewer-url mch_123

curl "${NULLSPACE_API_URL}/v1/machines/mch_123/desktop/stream" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}"

curl "${NULLSPACE_API_URL}/v1/machines/mch_123/desktop/stream/auth-key" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}"
desktop.stream.info() (GET /desktop/stream) exposes the lower-level raw vnc:// surface for advanced clients, and is only available when raw VNC exposure is enabled in API policy. The auth-key route returns both the active auth_key and the matching viewer_url. For browser sharing and inspection, prefer stream.viewer_url from start().

​
Capabilities

caps = machine.desktop.capabilities()
print(caps.streaming.managed_viewer)
print(caps.streaming.view_only)
print(caps.streaming.raw_vnc_mode)

nullspace machine desktop capabilities mch_123

curl "${NULLSPACE_API_URL}/v1/machines/mch_123/desktop/capabilities" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}"
Desktop deployments can expose different streaming modes. Public docs should use the managed viewer URL unless your deployment explicitly enables another mode.

​
Stop

machine.desktop.stream.stop()

nullspace machine desktop stream stop mch_123

curl -X POST "${NULLSPACE_API_URL}/v1/machines/mch_123/desktop/stream/stop" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}"

​
Behavior

Viewer sessions are signed and temporary. Start or rotate a viewer session when you need a fresh URL. Clipboard access uses the viewer session token. A view-only viewer can copy text out when enabled by the deployment, but cannot inject input into the machine.