opengeni-agent.
Self-hosted deployments must enable Connected Machines first. Besides
OPENGENI_SANDBOX_SELFHOSTED_ENABLED=true, they need the stream relay and NATS auth-callout; see
the deployment
guide.Connect your computer
In the Opengeni desktop app, turn on Computer use in Settings > Machines, or choose Use this computer in the conversation’s computer card. The app sets it up for your account. On macOS, follow any system permission prompts to let agents see and use the screen. Turning it off pauses it until you turn it on again, even after a restart. If you set the computer up earlier from the web app, the desktop app uses that same agent and shows computer use on. In the app, Connect a machine is for other computers and servers. In a web browser, choose Connect a computer, download the app for your operating system, and install it. Return to the card and choose Open app and connect. The app signs you in if needed, checks the account and workspace, and asks you to confirm access. No terminal command or setup code is needed. If you are on a phone, open the chat on the computer you want to connect. If the app opens without connecting, install the latest version using the download in the card, replacing the old app. Then choose Open app and connect again. Older desktop versions cannot complete this handoff. An application built on Opengeni can offer its own desktop app and connection flow instead. Connecting a computer does not automatically move an existing chat onto it; Use in this chat is available when you want to move the chat’s working environment too.Connect a server
For a computer without the desktop app, choose Connect a server instead to reveal the advanced command-based setup. For interactive device-code pairing:1
Run the installer
Open the Machines page in your workspace, choose Connect a server instead and Pair with a
code instead, copy the installer command, and run it on the machine. It installs Opengeni
Runner (
opengeni-agent) as a background service and starts a device sign-in.2
Approve the device
Open the printed URL, confirm the code, and choose who may use the machine: only you (the
default), the workspace, or the organization. Screen control is a separate consent.
3
Done
The machine appears on the Machines page. On macOS, approve the Runner’s Screen Recording,
Accessibility and Input Monitoring requests for desktop use. A connected machine can run
commands before desktop permissions are granted.
Enroll headlessly
For fleets and CI machines, create a one-time enrollment token in the workspace and pass it to the installer:Use it in a session
- At creation: pick the machine, and optionally a working directory, when starting a session.
- Later: switch a session to the machine, or back to its managed sandbox. History is unaffected.
Large file writes
On supported Linux and macOS filesystems, large file replacements are transferred in bounded chunks and published only after verification. Machine-addressed writes such asrun_on need a Runner that supports these transfers without a session
route. If an older transactional Runner is connected, writes above 262144 bytes
(256 KiB) fail before writing, with an instruction to update the Runner; smaller
writes still work. Runners predating transactional transfers retain their original
single-message size limit. Parent directories must already exist for a
transactional replacement.
Connect more workspaces
One Runner can connect to several workspaces, even on different Opengeni deployments. Each connection is independent.disconnect only stops the local link. The machine stays listed in the workspace until an admin removes it.