Metadata-Version: 2.4
Name: omnigent-community-sandbox-opensandbox
Version: 0.1.0
Summary: OpenSandbox community sandbox provider for Omnigent
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/jianpingpei/omnigent-community-sandbox-opensandbox
Project-URL: Documentation, https://open-sandbox.ai
Project-URL: Repository, https://github.com/jianpingpei/omnigent-community-sandbox-opensandbox
Project-URL: Issues, https://github.com/jianpingpei/omnigent-community-sandbox-opensandbox/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: <4,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click<9,>=8
Requires-Dist: omnigent<0.10,>=0.8.2
Requires-Dist: opensandbox<0.2,>=0.1.15
Provides-Extra: test
Requires-Dist: build<2,>=1; extra == "test"
Requires-Dist: pyrefly==1.1.1; extra == "test"
Requires-Dist: pytest<10,>=9; extra == "test"
Requires-Dist: ruff<1,>=0.15; extra == "test"
Dynamic: license-file

# Omnigent OpenSandbox provider

`omnigent-community-sandbox-opensandbox` is a community sandbox provider that
runs server-managed [Omnigent](https://github.com/omnigent-ai/omnigent) hosts in
[OpenSandbox](https://open-sandbox.ai/) 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:

```bash
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:

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

```bash
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

| Variable | Default | Purpose |
|---|---|---|
| `OPEN_SANDBOX_DOMAIN` | SDK default (`localhost:8080`) | OpenSandbox management endpoint |
| `OPEN_SANDBOX_API_KEY` | unset | Management API credential |
| `OPEN_SANDBOX_PROTOCOL` | `http` | `http` or `https` |
| `OPEN_SANDBOX_REQUEST_TIMEOUT` | `30` | Management request timeout in seconds |
| `OPEN_SANDBOX_USE_SERVER_PROXY` | `false` | Route sandbox service calls through the server proxy |
| `OMNIGENT_OPENSANDBOX_IMAGE` | Omnigent `DEFAULT_HOST_IMAGE` | Prebuilt host image |
| `OMNIGENT_OPENSANDBOX_SNAPSHOT_ID` | unset | Snapshot to restore instead of an image |
| `OMNIGENT_OPENSANDBOX_TIMEOUT_SECONDS` | `86400` | Maximum sandbox lifetime; minimum `60` |
| `OMNIGENT_OPENSANDBOX_READY_TIMEOUT_SECONDS` | `120` | Create, connect, and resume readiness timeout |
| `OMNIGENT_OPENSANDBOX_ENV` | unset | Comma-separated host variable names copied into the sandbox |
| `OMNIGENT_OPENSANDBOX_RESUME_STOPPED` | `false` | Advertise and enable in-place resume only when the deployment has checkpoint/snapshot support |

`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

```bash
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:

```bash
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](docs/verification.md) for the latest automated
results and the boundary of the live checks.
