┌─ End user's browser ────────────┐    ┌─ Your backend ──────────────────┐
│                                 │    │                                 │
│  <RemoteControl                 │    │  POST /sessions/start ─┐        │
│    url={webrtcUrl}              │    │                        │        │
│    token={token}                │◀───┤  new Limrun({ apiKey })│        │
│  />                             │    │    .iosInstances.create(…)      │
└────────────────┬────────────────┘    └────────────────┬────────────────┘
                 │ WebSocket + WebRTC,                  │ HTTP, API key
                 │ token in query string               ▼
                 │                              Limrun control plane
                 ▼                                     │
          Limrun instance ◀─────────────────────────────┘
          (status.endpointWebSocketUrl, status.token)

# Pick your package manager
npm  install @limrun/ui
pnpm add     @limrun/ui
bun  add     @limrun/ui

import { RemoteControl, type RemoteControlHandle } from '@limrun/ui';
import { useEffect, useRef, useState } from 'react';

type Session = { id: string; webrtcUrl: string; token: string };

export function Simulator() {
  const [session, setSession] = useState<Session | null>(null);
  const ctrlRef = useRef<RemoteControlHandle>(null);

  useEffect(() => {
    let cancelled = false;
    let sessionId: string | undefined;

    fetch('/sessions/start', { method: 'POST' })
      .then((r) => r.json())
      .then((s: Session) => {
        if (cancelled) return;
        sessionId = s.id;
        setSession(s);
      });

    return () => {
      cancelled = true;
      if (sessionId) {
        fetch('/sessions/stop', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ id: sessionId }),
          keepalive: true,
        });
      }
    };
  }, []);

  if (!session) return <div>Booting simulator…</div>;

  return (
    <RemoteControl
      ref={ctrlRef}
      url={session.webrtcUrl}
      token={session.token}
      sessionId={`tab-${Date.now()}`}
    />
  );
}

const ctrlRef = useRef<RemoteControlHandle>(null);

// Open a deep link or URL on the device
ctrlRef.current?.openUrl('myapp://orders/42');

// Capture a screenshot (data URI, 30 s timeout)
const { dataUri } = await ctrlRef.current!.screenshot();

// Kill an app by bundle ID (iOS; 30 s timeout)
await ctrlRef.current!.terminateApp('com.example.MyApp');

// Send a single keyboard event
ctrlRef.current?.sendKeyEvent({ type: 'keydown', code: 'Enter' });

// Tear down the current connection and start a fresh attempt
ctrlRef.current?.reconnect();

<RemoteControl
  url={session.webrtcUrl}
  token={session.token}
  showFrame={false}
/>

import express, { Request, Response } from 'express';
import cors from 'cors';
import Limrun from '@limrun/api';

const lim = new Limrun({ apiKey: process.env.LIM_API_KEY! });
const app = express();
app.use(cors(), express.json());

app.post('/sessions/start', async (req: Request, res: Response) => {
  try {
    const { tenant = 'demo', user = 'anonymous' } = req.body ?? {};
    const xff = req.headers['x-forwarded-for'];
    const firstHop = Array.isArray(xff)
      ? xff[0]
      : xff?.split(',')[0]?.trim();
    const clientIp = firstHop ?? req.socket.remoteAddress ?? undefined;

    const instance = await lim.iosInstances.create({
      wait: true,
      reuseIfExists: true,
      metadata: {
        labels: { tenant, user, managed_by: 'platform-embed' },
      },
      spec: {
        model: 'iphone',
        inactivityTimeout: '15m',
        hardTimeout: '2h',
        ...(clientIp && clientIp !== '::1' && clientIp !== '127.0.0.1'
          ? { clues: [{ kind: 'ClientIP', clientIp }] }
          : {}),
        initialAssets: [
          {
            kind: 'App',
            source: 'AssetName',
            assetName: 'appstore/Expo-Go-55-iOS-latest.tar.gz',
            launchMode: 'ForegroundIfRunning',
          },
        ],
      },
    });

    res.json({
      id:        instance.metadata.id,
      webrtcUrl: instance.status.endpointWebSocketUrl,
      token:     instance.status.token,
    });
  } catch (err) {
    res.status(500).json({
      error: err instanceof Error ? err.message : String(err),
    });
  }
});

app.post('/sessions/stop', async (req: Request, res: Response) => {
  try {
    await lim.iosInstances.delete(req.body.id);
    res.sendStatus(204);
  } catch (err) {
    res.status(500).json({
      error: err instanceof Error ? err.message : String(err),
    });
  }
});

app.listen(3001, () => console.log('Backend listening on :3001'));

import { RemoteControl, type RemoteControlHandle } from '@limrun/ui';
import { useEffect, useRef, useState } from 'react';

type Session = { id: string; webrtcUrl: string; token: string };

export function Simulator({ tenant, user }: { tenant: string; user: string }) {
  const [session, setSession] = useState<Session | null>(null);
  const [error,   setError]   = useState<string | null>(null);
  const ctrlRef = useRef<RemoteControlHandle>(null);

  useEffect(() => {
    let cancelled = false;
    let sessionId: string | undefined;

    (async () => {
      try {
        const res = await fetch('/sessions/start', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ tenant, user }),
        });
        if (!res.ok) throw new Error((await res.json()).error ?? res.statusText);
        const s: Session = await res.json();
        if (cancelled) {
          fetch('/sessions/stop', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ id: s.id }),
            keepalive: true,
          });
          return;
        }
        sessionId = s.id;
        setSession(s);
      } catch (e) {
        if (!cancelled) setError(e instanceof Error ? e.message : String(e));
      }
    })();

    return () => {
      cancelled = true;
      if (sessionId) {
        fetch('/sessions/stop', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ id: sessionId }),
          keepalive: true,
        });
      }
    };
  }, [tenant, user]);

  if (error)   return <div role="alert">Failed to start session: {error}</div>;
  if (!session) return <div>Booting simulator…</div>;

  return (
    <div style={{ display: 'flex', gap: 12 }}>
      <RemoteControl
        ref={ctrlRef}
        url={session.webrtcUrl}
        token={session.token}
        sessionId={`tab-${Date.now()}`}
        autoReconnect
        openUrl="exp://exp.host/@anonymous/my-snack"
      />
      <button
        onClick={async () => {
          const shot = await ctrlRef.current?.screenshot();
          if (shot) window.open(shot.dataUri);
        }}
      >
        Screenshot
      </button>
    </div>
  );
}