> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orgo.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Embed VMs
> Embed virtual computers into your applications
## 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 base** | `https://www.orgo.ai/desktops/{instance_id}` (read `instance_id` from `GET /computers/{id}`) |
| **WebSocket VNC** | `wss://www.orgo.ai/desktops/{instance_id}/ws/websockify?token={password}` |
| **Password** | `GET /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.
You can embed from **any domain**. There is no origin allowlist and nothing to register with us — the desktop password is the credential, so it is the only thing that decides whether a connection is allowed.
## Two credentials, and which one goes in the browser
This is the single most important thing to get right when embedding.
| | Where it lives | What it opens |
| -------------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| **API key** (`sk_…`) | **Your server only.** Never in browser code. | Your entire Orgo account: every computer, billing, and minting more keys. It also bypasses MFA. |
| **Desktop password** | Safe to hand to the browser. | One computer. Rotates on restart. |
Your server holds the API key, calls `GET /computers/{id}/vnc-password` with it, and returns **only the password** to your page.
An `sk_` API key is **rejected** if it arrives from a browser — passing one as `?token=` returns WebSocket close `4001`. Use the desktop password.
**Treat the desktop password as root on that computer.** The same value opens `/ws/terminal` and `POST /desktops/{instance_id}/proxy/bash`, not just the display. Anyone who can read it from your page can run commands on the VM.
So: fetch it per-session from your own backend, never inline it into a client bundle (in Next.js, **do not** put it in a `NEXT_PUBLIC_*` variable — those are compiled into the JavaScript every visitor downloads), and point embeds at a disposable computer rather than one holding real work.
### Connect with raw noVNC (no React)
Fetch the password on your server, then hand it to the client:
```js app/api/desktop/route.js expandable theme={null}
// SERVER — your backend. The API key never leaves this file.
export async function GET() {
const headers = { Authorization: `Bearer ${process.env.ORGO_API_KEY}` };
const computer = await fetch(`https://www.orgo.ai/api/computers/${process.env.ORGO_COMPUTER_ID}`, { headers })
.then(r => r.json());
const { password } = await fetch(
`https://www.orgo.ai/api/computers/${process.env.ORGO_COMPUTER_ID}/vnc-password`,
{ headers },
).then(r => r.json());
// Only the per-computer password crosses to the browser — never the API key.
return Response.json({ instanceId: computer.instance_id, password });
}
```
```js Browser theme={null}
// BROWSER
import RFB from '@novnc/novnc';
const { instanceId, password } = await fetch('/api/desktop').then(r => r.json());
const rfb = new RFB(
document.getElementById('screen'),
`wss://www.orgo.ai/desktops/${instanceId}/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)
// Surface failures instead of showing a blank canvas.
rfb.addEventListener('securityfailure', () => console.error('VNC auth failed'));
rfb.addEventListener('credentialsrequired', () => rfb.sendCredentials({ password }));
```
Always handle `credentialsrequired` and `securityfailure`. Without them noVNC can stop mid-handshake with no `connect`, no `disconnect` and no thrown error — the canvas simply stays black and nothing is logged.
## Setup
```bash theme={null}
npm install orgo-vnc
```
1. Go to [orgo.ai/start](https://www.orgo.ai/start)
2. Open a workspace and select a computer
3. Click the **⋮** menu → **Computer Settings**
4. Copy the **Hostname**, and create an API key for your server
Point the embed at a **disposable** computer — see the warning above about what the password grants.
Create `.env.local` in your project root. The hostname is public; the API key is not.
```bash theme={null}
NEXT_PUBLIC_ORGO_COMPUTER_HOST=your-hostname
ORGO_API_KEY=sk_live_...
ORGO_COMPUTER_ID=your-computer-id
```
Only `NEXT_PUBLIC_*` values are safe to expose — Next.js compiles them into the client bundle. Keep `ORGO_API_KEY` un-prefixed so it stays on the server, and never add a `NEXT_PUBLIC_` password: the password rotates on restart, so a baked-in one breaks anyway, and until it does it is a root shell sitting in your JavaScript.
The password rotates on restart, so fetch it per session rather than storing it.
```ts app/api/desktop-password/route.ts expandable theme={null}
// Gate this with YOUR OWN auth — anyone who can call it can drive the computer.
export async function GET() {
const res = await fetch(
`https://www.orgo.ai/api/computers/${process.env.ORGO_COMPUTER_ID}/vnc-password`,
{ headers: { Authorization: `Bearer ${process.env.ORGO_API_KEY}` }, cache: 'no-store' },
);
const { password } = await res.json();
return Response.json({ password }, { headers: { 'Cache-Control': 'no-store' } });
}
```
```tsx app/page.tsx expandable theme={null}
'use client';
import { useEffect, useState } from 'react';
import { ComputerDisplay } from 'orgo-vnc';
const HOST = process.env.NEXT_PUBLIC_ORGO_COMPUTER_HOST!;
export default function Home() {
const [connected, setConnected] = useState(false);
const [password, setPassword] = useState(null);
// Fetched per session from your own server, never bundled.
useEffect(() => {
fetch('/api/desktop-password')
.then(r => r.json())
.then(d => setPassword(d.password))
.catch(() => setPassword(null));
}, []);
return (
{connected ? `Connected to ${HOST}` : 'Connecting...'}