Omnigent OpenSandbox provider

omnigent-community-sandbox-opensandbox is a community sandbox provider that runs server-managed Omnigent hosts in OpenSandbox sandboxes. It uses Omnigent's omnigent.sandbox_providers entry point and keeps all provider code in the required omnigent.community.sandbox.* namespace.

This is an independent community implementation. It has not been submitted to or endorsed by the Omnigent maintainers.

Compatibility

• Python 3.12+
• Omnigent 0.8.2 through 0.9.x
• OpenSandbox Python SDK 0.1.15

Install

From this directory:

python -m pip install .

After installation, Omnigent discovers the provider as opensandbox. For a server-managed deployment, configure Omnigent with the provider and supply the OpenSandbox connection through environment variables:

sandbox:
  provider: opensandbox
  server_url: https://your-omnigent-server.example

export OPEN_SANDBOX_DOMAIN=localhost:8080
export OPEN_SANDBOX_PROTOCOL=http
omnigent server

The default sandbox image is Omnigent's official DEFAULT_HOST_IMAGE. Set OMNIGENT_OPENSANDBOX_IMAGE to use another prebuilt image, or set OMNIGENT_OPENSANDBOX_SNAPSHOT_ID to restore a snapshot. Image and snapshot are mutually exclusive.

Configuration

OpenSandboxLauncher also accepts an explicit ConnectionConfigSync, image or snapshot, environment, passthrough variable names, metadata, and timeout values. Explicit environment and metadata dictionaries are useful when the launcher is instantiated by deployment code rather than the Omnigent registry.

Implemented contract

• management-plane preflight with prepare();
• create from image or snapshot and wait for readiness;
• attach to an existing running sandbox without taking ownership;
• synchronous commands with separate stdout, stderr, and exit code;
• binary file upload with parent-directory creation and source mode retention;
• terminate, pause-state detection, and in-place resume;
• local SDK client cleanup that never implicitly terminates remote sandboxes.

The launcher advertises only those capabilities. managed_launch, programmatic_terminate and file_copy are enabled. resume_stopped is conservatively disabled by default because OpenSandbox checkpoint support is a deployment capability. Set OMNIGENT_OPENSANDBOX_RESUME_STOPPED=true only after pause/resume has been verified against that deployment. cli_bootstrap, streaming exec, foreground exec, and local port forwarding are disabled.

Boundaries

• The implementation targets one prebuilt, single-container sandbox. It does not build Dockerfiles or model Compose applications.
• Omnigent CLI bootstrap is intentionally unavailable because OpenSandbox SDK 0.1.15 does not provide the required foreground/PTY streaming and local port forwarding contract.
• close() releases local HTTP clients only. Omnigent must call terminate() when it intends to delete remote compute.
• OpenSandbox snapshots, images, and endpoint reachability remain deployment responsibilities.
• In-place resume requires a configured OpenSandbox checkpoint/snapshot provider. The capability must be explicitly enabled per deployment.

Development

python -m pip install -e '.[test]'
ruff format --check .
ruff check .
pyrefly check src
pytest -q
python -m build --outdir /tmp/omnigent-opensandbox-dist

The live test is opt-in and creates a real sandbox:

OPEN_SANDBOX_INTEGRATION_TEST=1 pytest -q tests/test_live.py

Without that flag, the live test is reported as skipped, not passed.

See the verification record for the latest automated results and the boundary of the live checks.