Orgo - Cloud computers for AI agents

Every computer streams over one WebSocket URL on www.orgo.ai. Any websockify-compatible VNC client connects to it, so you need no Orgo package to embed one. This page uses noVNC.

The connection URL

wss://www.orgo.ai/desktops/{id}/ws/websockify?token={password}

Value	Where it comes from
`id`	The computer’s UUID, as `POST /computers` and `GET /computers/{id}` return it. Its `instance_id` also works, but it changes when a sleeping computer wakes onto a new host, so use the `id`.
`password`	`GET /computers/{id}` returns it as `vnc_password`. `GET /computers/{id}/vnc-password` returns it as `password`. It survives a restart but can change, so fetch it for each session rather than storing it.

Both endpoints need your API key, so call them from your server.

Two credentials, and which one goes in the browser

Credential	Where it lives	What it opens
API key (`sk_…`)	Your server only. Never in browser code.	An account-wide key opens your whole Orgo account: every computer, billing, and minting more keys. It also bypasses MFA.
Computer password	Only share with people allowed to control the computer.	One computer.

Your server holds the API key, reads the password with it, and returns only the password to your page.

The computer password is root on that computer. The same value opens /ws/terminal and POST /api/desktops/{id}/proxy/bash, not only the screen. Anyone who can read it from your page can run commands on the computer.So fetch it per session from your own backend, and keep it out of your client bundle. In Next.js that means never a NEXT_PUBLIC_* variable: those are compiled into the JavaScript every visitor downloads. Point embeds at a disposable computer rather than one holding real work.

An sk_ key is rejected when it arrives from a browser. Passing one as ?token= closes the socket with 4001. Send the computer password instead.

A client setting such as rfb.viewOnly = true only disables that client’s controls. It does not reduce the permission of a computer password sent to the browser; a visitor can turn the setting off. For authenticated Orgo workspace viewers, the web proxy enforces view-only access on the server and filters input. Use workspace viewer access for this case. A public anonymous embed with a separate native VNC view-only password is not currently provided by this API.

Embed from any domain

There is no origin allowlist on this path and nothing to register with us. The per-computer password is the credential, and it is the only thing that decides whether a connection is allowed.

Embed with noVNC

Two files. First a server route that trades your API key for the two values the browser needs.

app/api/computer/route.ts

// SERVER. The API key never leaves this file.
export async function GET() {
  const res = await fetch(
    `https://www.orgo.ai/api/computers/${process.env.ORGO_COMPUTER_ID}`,
    {
      headers: { Authorization: `Bearer ${process.env.ORGO_API_KEY}` },
      cache: 'no-store',
    },
  );
  const computer = await res.json();

  // Only the per-computer password crosses to the browser.
  return Response.json(
    { id: computer.id, password: computer.vnc_password },
    { headers: { 'Cache-Control': 'no-store' } },
  );
}

Gate that route with your own auth. Anyone who can call it can drive the computer.

Then the browser. Install noVNC 1.7.0 or later with npm install @novnc/novnc. Earlier versions have no package-root export, so the import below fails on them.

Browser

import RFB from '@novnc/novnc';

const { id, password } = await fetch('/api/computer').then((r) => r.json());

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

rfb.viewOnly = false;      // true renders the screen without sending input
rfb.scaleViewport = true;  // fit the screen to its container
rfb.qualityLevel = 6;      // 0 to 9
rfb.compressionLevel = 2;  // 0 to 9

// Answer the VNC auth challenge when the proxy forwards it.
rfb.addEventListener('credentialsrequired', () => rfb.sendCredentials({ password }));
rfb.addEventListener('securityfailure', (e) => console.error('VNC auth failed', e.detail));

// The close code is the only signal a rejected connection gives you.
rfb._sock._websocket.addEventListener('close', (e) => console.log('closed', e.code));

That last line reads noVNC internals, because noVNC’s own disconnect event does not carry the close code.

A failed embed is a black screen

The proxy rejects a connection by accepting the WebSocket upgrade and then closing it. noVNC throws nothing, its disconnect event reports only clean: false, and the canvas stays black. The code appears only in the socket’s close event and in a noVNC console error. It is the only way to tell a bad password from a stopped computer.

Code	What happened	What to do
`4001`	Authentication was rejected.	Send the per-computer password, not an `sk_` key. It may have changed, so fetch it again.
`4003`	The computer is not available: stopped, asleep, not ready yet, or its trial or subscription ended.	Start or resume it, then reconnect once its status is `running`. If it is already running, check the account’s plan or credit.
`4004`	No such computer.	Check the computer `id`.
`4006`	The credential is valid but scoped to another workspace.	Use a key for this computer’s workspace, or an account-wide key.
`4007`	MFA is required for this session.	Complete the MFA challenge, then reconnect.
`4008`	Idle for 30 minutes.	Expected. Reconnect on user activity.
`4010`	WebRTC is disabled for this computer.	Use the websockify path.
`4011`	This grant allows viewing the screen only.	Connect to `/ws/websockify`. Terminal and audio are not available.
`4500`	The proxy hit an internal error.	Retry.
`4502`	The proxy has no address for the computer.	Usually transient while a computer is starting or moving hosts. Retry.
`4503`	The proxy could not look up the computer.	Transient. Retry.

Anything outside 4000-4599 is a standard WebSocket code. The proxy closes with 1000 when its own connection to the computer fails or ends, and with 1001 when it shuts down. 4003, 4007, 4008, 4500, 4502 and 4503 are worth retrying. The rest need an input changed first. A wrong path gets no Orgo code at all: a URL outside /desktops/{id}/ws/ fails the handshake, and the browser reports 1006.

Every long-lived embed eventually hits 4008. After 30 minutes with no human input the proxy closes the connection. The timer measures keyboard, pointer and clipboard input from your page, not pixels, so a computer an agent is driving with nobody watching still counts as idle. Treat 4008 as a clean close and reconnect on the next user action.

The orgo-vnc package

For a React component, use orgo-vnc 0.3.0 or later (npm install orgo-vnc). Version 0.3.0, published on 2026-10-03, is the current release. It connects to the URL in The connection URL with ?token=. onClose receives every close code, plus a decoded reason when the package knows the code (null otherwise). onError receives a one-line message for each code it knows.

React

import { ComputerDisplay } from 'orgo-vnc';

<ComputerDisplay
  instanceId={id}
  password={password}
  onError={(message) => console.error(message)}
/>

The prop is named instanceId, but the package puts its value in the same /desktops/{id}/ path, so the computer’s id works there and does not change when a sleeping computer wakes on a new host. Fetch id and password from your server, as in Embed with noVNC. Versions 0.2.x take a hostname prop and connect to wss://{hostname}/websockify, from when every computer had its own host. That address no longer exists, so 0.2.x cannot connect. 0.3.0 ignores hostname and logs a warning.

Get Started

Using Orgo

Guides

Migrations

Templates

Model integrations

Embed computers

The connection URL

Two credentials, and which one goes in the browser

Embed from any domain

Embed with noVNC

A failed embed is a black screen

The orgo-vnc package

Next steps

Quickstart

API reference

​The connection URL

​Two credentials, and which one goes in the browser

​View-only sharing

​Embed from any domain

​Embed with noVNC

​A failed embed is a black screen

​The orgo-vnc package

​Next steps

Quickstart

API reference

The connection URL

Two credentials, and which one goes in the browser

View-only sharing

Embed from any domain

Embed with noVNC

A failed embed is a black screen

The orgo-vnc package

Next steps