Embedding & Streaming

To show a live desktop session in your end-user’s browser, embed MIOSA’s desktop stream. Use this for “watch the AI work” UI, manual takeover, internal support tools, and kiosk-style apps.

The flow


1. Your backend asks MIOSA for signed Computer URLs or a stream token for a running computer
2. MIOSA returns a short-lived desktop URL or token
3. Your frontend renders an iframe with that URL
4. The user sees the live desktop; keyboard/mouse input is forwarded into the VM

Get an embed URL

Response:

{
  "desktop_url": "https://agent-1.computer.miosa.ai/desktop/index.html?auth=...",
  "desktop_entry_url": "https://agent-1.computer.miosa.ai/desktop/index.html",
  "vnc_url": "https://agent-1.computer.miosa.ai/desktop/index.html?auth=...",
  "ws_url": "wss://agent-1.computer.miosa.ai/vnc/websockify?auth=...",
  "terminal_url": "wss://agent-1.computer.miosa.ai/ws/terminal/cmp_xxx",
  "token": "miosa_stream_...",
  "expires_at": 1783000000,
  "computer_id": "cmp_xxx"
}

desktop_url is what you embed. token is returned in case you need to construct your own stream URL or proxy the stream through a custom gateway.

Embed

MIOSA handles pixel streaming and input forwarding inside the iframe. The user clicks or types in the iframe and those events go to the desktop.

What’s streamed

Pixels - encoded video tuned for desktop content.
Cursor position - overlay rendered client-side.
Audio - optional, off by default. Pass ?audio=1 if your app needs it.
Clipboard - bidirectional, gated by the iframe’s allow="clipboard-read; clipboard-write".

Read-only mode

For “user watches the agent” UI where the end-user shouldn’t interact with the desktop:

Use your own application permissions to decide whether to render an interactive iframe or a watch-only surface. Public read-only stream token controls are plan-dependent and should not be assumed unless enabled for your tenant.

Bandwidth

Default codec / bitrate is tuned for typical desktop content, usually about 500 Kbps to 2 Mbps. For high-motion content, such as video playback inside the VM, the codec adapts but expect higher bitrate. The stream gateway is geo-routed to the user’s nearest region for lower latency.

Lifetime

Stream URLs are short-lived. The default lifetime is 1 hour, and max lifetime is plan-dependent. When a token expires, the stream disconnects. Your frontend should watch expires_at and re-mint before that.

Multiple stream URLs per computer are fine. Multiple browsers can watch the same desktop simultaneously. They all see the same pixels.

Custom domains / branded streaming

White-label customers can configure a branded stream domain so end users see your brand in the iframe URL. The DNS and TLS flow follows the same contract as Deployment Domains, with a different routing target. Contact support to set up branded streaming.

CSP

The stream gateway emits Content-Security-Policy allowing the stream to be embedded from approved origins:

Default: *.miosa.app, *.miosa.ai, localhost:4000.
For white-label: add your platform origin via tenant config.

If your iframe doesn’t render, check the parent page’s CSP isn’t blocking the iframe and that the stream gateway CSP includes your origin.

Audit

Each stream URL issuance emits an audit event with:

The computer ID
The token prefix
Issuing API key
External attribution

If a token is leaked, rotate the user session or stop the Computer while you investigate. Stream tokens are short-lived by default.