Skip to main content

​
Overview

Embed Orgo virtual computers directly into your web apps. Build AI agent interfaces, automation dashboards, or any product with live VM displays.
You can use any VNC client to connect to Orgo computers. The orgo-vnc package is a React component for convenience.

​
Connection details

Every computer is reachable same-origin under www.orgo.ai. The connection base is shown as Connection URL in Computer Settings.
Connection basehttps://www.orgo.ai/desktops/{instance_id} (read instance_id from GET /computers/{id})
WebSocket VNCwss://www.orgo.ai/desktops/{instance_id}/ws/websockify?token={password}
PasswordGET /computers/{id}/vnc-password - rotates on restart, fetch fresh, do not hardcode
The WebSocket form is what the orgo-vnc component, noVNC, and any websockify-compatible client use.

​
Connect with raw noVNC (no React)

import RFB from '@novnc/novnc';

const computer = await fetch(`https://www.orgo.ai/api/computers/${id}`, {
  headers: { Authorization: `Bearer ${apiKey}` }
}).then(r => r.json());

const { password } = await fetch(
  `https://www.orgo.ai/api/computers/${id}/vnc-password`,
  { headers: { Authorization: `Bearer ${apiKey}` } }
).then(r => r.json());

const rfb = new RFB(
  document.getElementById('screen'),
  `wss://www.orgo.ai/desktops/${computer.instance_id}/ws/websockify?token=${encodeURIComponent(password)}`,
  { credentials: { password } }
);

// Adjust after construction
rfb.viewOnly = true;       // read-only mode (no input)
rfb.scaleViewport = true;  // fit display to container
rfb.qualityLevel = 6;      // 0–9 (default 6)
rfb.compressLevel = 2;     // 0–9 (default 2)

​
Setup

1

Install

    npm install orgo-vnc
2

Get credentials

  1. Go to orgo.ai/start
  2. Open a workspace and select a computer
  3. Click the ⋮ menu → Computer Settings
  4. Copy the Hostname and Password
3

Configure environment

Create .env.local in your project root:
    NEXT_PUBLIC_ORGO_COMPUTER_HOST=your-hostname
    NEXT_PUBLIC_ORGO_COMPUTER_PASSWORD=your-password
4

Use the ComputerDisplay component

    'use client';
    import { useState } from 'react';
    import { ComputerDisplay } from 'orgo-vnc';

    const HOST = process.env.NEXT_PUBLIC_ORGO_COMPUTER_HOST!;
    const PASSWORD = process.env.NEXT_PUBLIC_ORGO_COMPUTER_PASSWORD!;

    export default function Home() {
      const [connected, setConnected] = useState(false);
      
      return (
        <div className="grid place-items-center min-h-screen p-8">
          <div className="w-full max-w-4xl flex flex-col gap-3">
            <p className="text-sm text-foreground/60 flex items-center gap-2">
              <span className={`w-2 h-2 rounded-full ${connected ? 'bg-emerald-500' : 'bg-foreground/30 animate-pulse'}`} />
              {connected ? `Connected to ${HOST}` : 'Connecting...'}
            </p>
            <div className="aspect-[4/3] rounded-lg overflow-hidden bg-foreground/5">
              <ComputerDisplay
                hostname={HOST}
                password={PASSWORD}
                background="transparent"
                readOnly={false}
                onConnect={() => setConnected(true)}
                onDisconnect={() => setConnected(false)}
              />
            </div>
          </div>
        </div>
      );
    }

​
Props

PropTypeDefaultDescription
hostnamestringrequiredComputer hostname
passwordstringrequiredComputer password
readOnlybooleanfalseDisable user interaction
backgroundstringundefinedBackground color
scaleViewportbooleantrueScale display to fit container
clipViewportbooleanfalseClip display to container bounds
resizeSessionbooleanfalseResize remote session to match
showDotCursorbooleanfalseShow dot cursor when remote cursor hidden
compressionLevelnumber2Compression level (0-9)
qualityLevelnumber6Image quality (0-9)
onConnectfunctionundefinedCalled when connected
onDisconnectfunctionundefinedCalled when disconnected
onErrorfunctionundefinedCalled on error
onClipboardfunctionundefinedCalled when clipboard data received
onReadyfunctionundefinedCalled with handle for programmatic control

​
Programmatic Control

Use the onReady callback to get a handle for programmatic control: 
const [handle, setHandle] = useState<ComputerDisplayHandle | null>(null);

<ComputerDisplay
  hostname={HOST}
  password={PASSWORD}
  onReady={setHandle}
/>

// Later...
handle?.reconnect();
handle?.disconnect();
handle?.sendClipboard('text to send');
await handle?.pasteFromClipboard();

​
Next Steps

Quick Start

Full SDK setup

API Reference

Control computers programmatically