Skip to main content
A Connected Machine is your own always-on computer, enrolled once and then usable as a session target. The agent runs there directly, with no cloud box in between. See Compute targets for how it differs from a managed sandbox.
On a self-hosted deployment, Connected Machines are off until an operator enables them. Setting OPENGENI_SANDBOX_SELFHOSTED_ENABLED=true alone is not enough: the deployment also needs the stream relay, NATS with auth-callout, public WebSocket ingress for both, and their secrets. The Connected Machines section of the deployment guide enumerates them. Managed OpenGeni has them enabled.

​
Enroll interactively

1

Run the installer

Open the Machines page in your workspace and copy the one-line installer. Run it on the machine. It installs or updates the opengeni-agent binary, registers it as a background service, and starts a device flow.
2

Approve the device

The agent prints a short code and a verification URL. Open the URL, confirm the code, and choose who may use the machine: only you (the default), the workspace, or the whole organization. Screen control is a separate consent.
3

Done

The machine appears in the Machines list with its status and metrics and is immediately available as a session target.

​
Enroll headlessly

For fleets and CI boxes, mint a short-lived enrollment token in the workspace and pass it to the installer. The token is shown once and exchanged on the machine for its own long-lived credential.

​
Use it in a session

  • At creation: pick the machine, and optionally a working directory on it, when starting a session. The first turn runs there.
  • Later: swap a running session’s active compute target to the machine, or back to its managed sandbox. The session’s history is unaffected.
The agent works under the chosen folder, creating its own worktrees as needed, and uses the machine’s existing git configuration. OpenGeni never clones repositories onto it.

​
One agent, many connections

The agent binary is multi-connection. Installing it once and connecting another workspace, even on a different OpenGeni deployment, adds an independent link without disturbing the existing ones.
disconnect stops only the local link. The enrollment remains visible offline in the workspace until an administrator removes it, so possessing the machine never grants workspace authority.

​
Revoke

Revoke a machine from the Machines page. Revocation invalidates every existing grant and refuses further use until the machine is enrolled again.

​
Programmatic enrollment

Products embedding OpenGeni can render their own approval page and drive enrollment through the SDK. The repository’s Connected Machines guide documents the device-flow lookup, approve, deny, token minting, and swap methods.