> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ns.rocks/llms.txt
> Use this file to discover all available pages before exploring further.

# Managed Desktop Viewer

> Start a browser-accessible desktop viewer session.

## Start a viewer

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  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)
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace machine desktop stream start mch_123
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  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}'
  ```
</CodeGroup>

The response carries the public `viewer_url` and a short-lived `auth_key`.

## View-only mode

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  stream = machine.desktop.stream.start(view_only=True)
  print(stream.viewer_url)
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace machine desktop stream start mch_123 --view-only
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  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}'
  ```
</CodeGroup>

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

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  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)
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace machine desktop stream info mch_123
  nullspace machine desktop stream auth-key mch_123
  nullspace machine desktop stream viewer-url mch_123
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  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}"
  ```
</CodeGroup>

`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

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  caps = machine.desktop.capabilities()
  print(caps.streaming.managed_viewer)
  print(caps.streaming.view_only)
  print(caps.streaming.raw_vnc_mode)
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace machine desktop capabilities mch_123
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  curl "${NULLSPACE_API_URL}/v1/machines/mch_123/desktop/capabilities" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}"
  ```
</CodeGroup>

Desktop deployments can expose different streaming modes. Public docs should
use the managed viewer URL unless your deployment explicitly enables another
mode.

## Stop

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  machine.desktop.stream.stop()
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace machine desktop stream stop mch_123
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  curl -X POST "${NULLSPACE_API_URL}/v1/machines/mch_123/desktop/stream/stop" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}"
  ```
</CodeGroup>

## 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.

## Related

* [Desktop automation](./automation)
* [Desktop viewer example](../examples/desktop-viewer)
* [WebSocket protocol](../reference/websocket-protocol)