Managed Desktop Viewer

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.

Get started

Machines

Commands

Filesystem

Code Interpreter

Desktop

Templates

Volumes

Networking

Interactive access

Observability

Managed Desktop Viewer

Start a viewer

View-only mode

Auth key and raw stream info

Capabilities

Stop

Behavior

​Start a viewer

​View-only mode

​Auth key and raw stream info

​Capabilities

​Stop

​Behavior

​Related

Start a viewer

View-only mode

Auth key and raw stream info

Capabilities

Stop

Behavior

Related