Embed a device stream in your app

Use @mobilerun/react to add a live, interactive Mobilerun cloud device to your React application. The package provides:

DeviceStream for video, touch, keyboard input, and reconnection
NavigationBar for Android Back, Home, and Recents controls
RemoteControlHandle for actions such as opening a URL or taking a screenshot
A prebuilt stylesheet that you can customize with CSS variables

Your application provides the surrounding layout, branding, loading states, and access control.

Keep the API key in your backend

MOBILERUN_CLOUD_API_KEY is an account-level secret. Never include it in browser code, public environment variables, or a client-side SDK instance.In a multi-user application, your backend must authenticate the current user and verify that the user may access the requested device before returning stream credentials.

The browser does not need the account API key. It only needs the streamUrl and streamToken for the selected device: The stream token is device-scoped, but it is still sensitive. Do not store it in local storage or send it to logs, analytics, traces, or error-reporting tools.

Install

npm install @mobilerun/react @mobilerun/sdk react react-dom

Import the package stylesheet once in your application:

app/layout.tsx

import '@mobilerun/react/styles.css';
import './globals.css';

Create a backend credentials endpoint

The following Next.js route uses @mobilerun/sdk only on the server. Replace the example authentication imports with your application’s own authorization layer.

app/api/device-stream/[deviceId]/route.ts

import Mobilerun from '@mobilerun/sdk';
import { type NextRequest, NextResponse } from 'next/server';

import { canAccessDevice, getCurrentUser } from '@/server/auth';

const apiKey = process.env.MOBILERUN_CLOUD_API_KEY;
if (!apiKey) {
  throw new Error('MOBILERUN_CLOUD_API_KEY is not configured');
}

const mobilerun = new Mobilerun({ apiKey });

export async function GET(
  request: NextRequest,
  context: { params: Promise<{ deviceId: string }> },
) {
  const user = await getCurrentUser(request);
  if (!user) {
    return NextResponse.json({ error: 'unauthorized' }, { status: 401 });
  }

  const { deviceId } = await context.params;

  // A device ID is not authorization. Enforce your application's ownership or
  // membership rules before retrieving credentials with the account API key.
  if (!(await canAccessDevice(user.id, deviceId))) {
    return NextResponse.json({ error: 'forbidden' }, { status: 403 });
  }

  try {
    const device = await mobilerun.devices.retrieve(deviceId);

    return NextResponse.json(
      {
        streamUrl: device.streamUrl || null,
        streamToken: device.streamToken || null,
        state: device.state,
      },
      { headers: { 'Cache-Control': 'no-store' } },
    );
  } catch (error) {
    const status =
      error instanceof Mobilerun.APIError && error.status === 404 ? 404 : 502;

    return NextResponse.json(
      { error: status === 404 ? 'device_not_found' : 'stream_unavailable' },
      { status },
    );
  }
}

This endpoint returns only the fields required by the stream. It does not expose the account API key or the full device response.

Render `DeviceStream`

Fetch the device credentials from your authenticated backend, then pass them directly to the package component:

components/device-stream-panel.tsx

'use client';

import {
  DeviceStream,
  NavigationBar,
  type RemoteControlHandle,
} from '@mobilerun/react';
import { useCallback, useEffect, useRef, useState } from 'react';

interface StreamCredentials {
  streamUrl: string | null;
  streamToken: string | null;
  state: string;
}

export function DeviceStreamPanel({ deviceId }: { deviceId: string }) {
  const controls = useRef<RemoteControlHandle>(null);
  const [credentials, setCredentials] = useState<StreamCredentials>();
  const [error, setError] = useState<string>();

  const loadCredentials = useCallback(async () => {
    try {
      const response = await fetch(`/api/device-stream/${deviceId}`, {
        cache: 'no-store',
      });

      if (!response.ok) {
        setError(`Unable to load stream (${response.status})`);
        return;
      }

      setCredentials((await response.json()) as StreamCredentials);
      setError(undefined);
    } catch {
      setError('Unable to reach the stream endpoint');
    }
  }, [deviceId]);

  useEffect(() => {
    void loadCredentials();
  }, [loadCredentials]);

  useEffect(() => {
    if (!credentials || credentials.streamUrl || error) {
      return;
    }

    const timer = window.setTimeout(() => {
      void loadCredentials();
    }, 3_000);

    return () => window.clearTimeout(timer);
  }, [credentials, error, loadCredentials]);

  if (error) {
    return <p>{error}</p>;
  }

  return (
    <section className="device-panel" aria-label="Remote device">
      <div className="device-screen">
        <DeviceStream
          ref={controls}
          streamUrl={credentials?.streamUrl ?? undefined}
          streamToken={credentials?.streamToken ?? undefined}
          hasControl
          muted
          placeholderLabel={credentials?.state ?? 'loading'}
          onStreamHealed={loadCredentials}
        />
      </div>

      <NavigationBar
        onAction={(action) => controls.current?.sendSystemKey(action)}
      />
    </section>
  );
}

If a device is still starting, streamUrl may be empty. The second effect polls the backend every three seconds until it becomes available. onStreamHealed also retrieves the current credentials after a stable disconnect. NavigationBar stays below the stream and provides Android Back, Home, and Recents. The hasControl prop controls direct interaction with the device screen; it does not disable NavigationBar or provide an authorization boundary. Anyone who receives stream credentials must be authorized to control that device. If your UI includes a view-only mode, also guard the onAction callback and treat that as a UI affordance, not a security control. The stream starts muted so browser autoplay policies do not block it; only unmute after a user action.

Customize the appearance

DeviceStream does not add Mobilerun logos or application chrome. Style its parent and override the package CSS variables to match your product:

app/globals.css

.device-panel {
  --background: #09090b;
  --foreground: #fafafa;
  --muted-foreground: #a1a1aa;
  --border: #3f3f46;
  --primary: #7c3aed;

  display: flex;
  width: min(100%, 390px);
  aspect-ratio: 9 / 19.5;
  flex-direction: column;
  overflow: hidden;
  border: 1px solid var(--border);
  border-radius: 32px;
  background: var(--background);
}

.device-screen {
  min-height: 0;
  flex: 1;
}

Observe the integration safely

Instrument the backend credentials request with your existing OpenTelemetry setup. Record the device ID, device state, and upstream status, but never credentials. Use onConnectionStateChange for user-visible connection analytics:

onConnectionStateChange={(connected) => {
  posthog.capture(
    connected ? 'device_stream_connected' : 'device_stream_disconnected',
    { device_id: deviceId },
  );
}}

Do not include streamUrl, streamToken, or MOBILERUN_CLOUD_API_KEY in PostHog events.

Production checklist

The account API key is used only by backend code.
Every credentials request requires an authenticated application session.
Your backend verifies that the current user may access the requested device.
Credential responses use Cache-Control: no-store.
Stream credentials are excluded from logs, traces, analytics, and error reports.
Interactive control is enabled only for authorized users.

For all exported components and the local playground, see the @mobilerun/react package repository.

Introduction

Concepts

Guides

Dashboard

Integrations

Embed a device stream in your app

Keep the API key in your backend

Install

Create a backend credentials endpoint

Render `DeviceStream`

Customize the appearance

Observe the integration safely

Production checklist

​Keep the API key in your backend

​Install

​Create a backend credentials endpoint

​Render DeviceStream

​Customize the appearance

​Observe the integration safely

​Production checklist

Keep the API key in your backend

Install

Create a backend credentials endpoint

Render `DeviceStream`

Customize the appearance

Observe the integration safely

Production checklist