Loading components
Orgo
Orgo gives Convex actions isolated cloud VMs with a Linux/Windows desktop, browser, terminal, and persistent disk, with reactive state in Convex tables.
Installation
npm install orgo-convexAbout Orgo
Give your agents a computer. Each Orgo computer is an isolated virtual machine with a full Linux or Windows desktop, a browser, a terminal and a disk that persists.
- **Computers.** Create, start, stop and delete. Stopping keeps the disk.
- **Commands and Python.** Output, exit codes, timeouts and a full run history.
- **Screenshots.** The screen as PNG bytes, ready for computer-use models.
- **Files.** Upload and export, up to 10 MiB each.
- **Live state.** Every computer and run in reactive tables, with no polling.
Requires an Orgo API key from [orgo.ai](https://www.orgo.ai).
Benefits
- Provision and drive full virtual machines from Convex actions without leaving your existing stack or adding Node.js dependencies
- Track every computer's status and execution history in reactive Convex tables your UI can subscribe to without polling
- Enforce per-user isolation automatically via server-derived userKey checks before any request reaches the Orgo API
- Capture screenshots as PNG bytes for computer-use AI models and transfer files up to 10 MiB in either direction
Use cases
how to run python code in a sandboxed VM from a Convex action
Orgo lets you call orgo.runPython from a Convex action to execute Python in an isolated cloud VM and get back stdout, stderr, exit code, and status. Each computer is a persistent VM with its own disk, so state carries across runs. The result is recorded in a Convex table so queries can display run history reactively.
how to give AI agents a full desktop environment from Convex
orgo-convex provisions Linux or Windows VMs with a browser, terminal, and persistent disk via orgo.createComputer in a Convex action. You can then run bash or PowerShell commands, take screenshots for computer-use vision models, and upload or export files. Each VM's status is stored in Convex tables your UI subscribes to without polling.
how to take screenshots of a remote desktop in Convex for AI computer use
orgo.screenshot returns an ArrayBuffer of PNG bytes along with width and height, which you can pass directly to computer-use vision models or store in Convex file storage. The call works from any Convex action and requires only a computerId and userKey for authorization.
how to isolate cloud VMs per user in a Convex backend
orgo-convex enforces per-user isolation through a userKey parameter that your server derives from the authenticated user identity, for example from identity.tokenIdentifier. Every read or mutation on a computer must present the same userKey it was created with, and mismatches return not-found before any request reaches Orgo. This check happens inside the component on the server side, never from client input.
Frequently asked questions
Does orgo-convex require Node.js or any native dependencies?
No. orgo-convex uses plain fetch in Convex's default runtime and has no SDK dependencies and no requirement for 'use node'. This means it works in standard Convex actions without switching runtimes.
How does orgo-convex store computer and execution state in Convex?
orgo-convex writes each computer and execution record to its own component tables. Methods like getComputer, listComputers, getExecution, and listExecutions read from those tables and work in Convex queries, so your UI can subscribe to live updates. The tables hold the last observed state; call refreshComputer to re-read from Orgo when you need fresh status.
How do I keep secrets like API keys and tokens out of Convex tables when using orgo-convex?
orgo-convex is designed so passwords, tokens, and signed links that Orgo returns never reach a Convex table, a return value, or an error message. Command output and code are also not stored by default; set retainOutput: true in the Orgo constructor only if you need execution history and understand that truncation is not redaction.
What happens if a command times out or fails on the VM?
orgo-convex resolves with a status of 'failed' or 'timed_out' rather than throwing when a command exits with a nonzero code or exceeds the timeout. It throws only when Orgo refuses the request entirely or when the response is lost and the outcome is unknown. Commands are never automatically retried because a retry could run the command twice.
What version of Convex is required to use orgo-convex?
orgo-convex requires convex version 1.43 or later. It is registered as a component in convex.config.ts using defineApp, and the ORGO_API_KEY is passed by reference so rotating the key requires no redeployment.
Links
Components
Open-source building blocks for your Convex app
Browse components in this category.