Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/source/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ A few integrations ship as optional extras. Install them with
|-------|----------|
| `inspect` | The Inspect AI evaluation harness |
| `harbor` | The [Harbor integration](environments/harbor) and its sandbox backends (Python 3.12+) |
| `daytona`, `aca`, `modal`, `novita` | Cloud sandbox providers (see [Runtime Providers](guides/runtime-providers)) |
| `daytona`, `aca`, `modal`, `novita`, `boxd` | Cloud sandbox providers (see [Runtime Providers](guides/runtime-providers)) |

## Try an Environment

Expand Down Expand Up @@ -155,7 +155,7 @@ with EchoEnv(base_url="http://localhost:8000").sync() as client:
result = client.reset()
```

The same client also runs environments on cloud sandboxes (Daytona, Modal, Novita, Azure Container Apps, Hugging Face) and on a Kubernetes cluster through runtime providers. `HFSandboxProvider` ships with core OpenEnv and needs a Hugging Face token for an account that can run Jobs (the sandboxes are billed as Jobs): it runs an environment's Space image in a Hugging Face sandbox ([example](guides/runtime-providers#hfsandboxprovider)). `KubernetesProvider` is an optional extra (`pip install openenv[kubernetes]`, [example](guides/runtime-providers#kubernetesprovider)). See the [Runtime Providers guide](guides/runtime-providers) to pick one.
The same client also runs environments on cloud sandboxes (Daytona, Modal, Novita, Azure Container Apps, Hugging Face, boxd) and on a Kubernetes cluster through runtime providers. `HFSandboxProvider` ships with core OpenEnv and needs a Hugging Face token for an account that can run Jobs (the sandboxes are billed as Jobs): it runs an environment's Space image in a Hugging Face sandbox ([example](guides/runtime-providers#hfsandboxprovider)). `KubernetesProvider` is an optional extra (`pip install openenv[kubernetes]`, [example](guides/runtime-providers#kubernetesprovider)). See the [Runtime Providers guide](guides/runtime-providers) to pick one.

## Next Steps

Expand Down
49 changes: 47 additions & 2 deletions docs/source/guides/runtime-providers.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,7 @@ is a one-line change.
| `NovitaSandboxProvider` | Novita AI sandboxes | `pip install openenv[novita]` | ✅ |
| `HFSandboxProvider` | Hugging Face sandboxes (billed as HF Jobs) | core | ✅ |
| `KubernetesProvider` | Kubernetes cluster | `pip install openenv[kubernetes]` | ✅ |
| `BoxdProvider` | boxd machines (microVMs) | `pip install openenv[boxd]` | ✅ |

Cloud-provider SDKs are optional extras, imported lazily, so installing core
OpenEnv pulls in no cloud SDK. The core providers (`LocalDockerProvider`,
Expand Down Expand Up @@ -91,8 +92,8 @@ async with MyEnv(provider=provider) as env:
...
```

`ModalProvider`, `DaytonaProvider`, `ACASandboxProvider`, and `HFSandboxProvider`
support this provider-owned flow. Providers that require an explicit image at
`ModalProvider`, `DaytonaProvider`, `ACASandboxProvider`, `HFSandboxProvider`,
and `BoxdProvider` support this provider-owned flow. Providers that require an explicit image at
`start_container()` time, such as `LocalDockerProvider` and
`DockerSwarmProvider`, should still be started manually and passed in with the
returned `base_url`:
Expand Down Expand Up @@ -178,6 +179,50 @@ provider = ACASandboxProvider(
)
```

### BoxdProvider

Runs the server in a [boxd](https://boxd.sh?ref=OpenEnv) machine, a microVM
with Docker installed. Install with `pip install openenv[boxd]`. Requires a
boxd API key, as `api_key=` or the `BOXD_API_KEY` environment variable
(optionally `org=`/`BOXD_ORG` and `region=`/`BOXD_REGION`, `fra` or `nyc`).

The provider creates one isolated machine per `start_container`, runs the
image in it with `docker run`, and returns the machine's HTTPS URL. The URL is
reachable from the internet with no login in front of it, so treat it like a
secret: anyone who has it can drive the environment. The provider keeps it out
of its errors.
`stop_container()` deletes the machine. `env_vars` reach the container through
a `docker run --env-file` that is removed after the run.

```python
from openenv.core.containers.runtime.boxd_provider import BoxdProvider

provider = BoxdProvider(image="ghcr.io/huggingface/openenv-echo-env:latest")
```

A local Dockerfile works too. The build context is uploaded to the machine and
built there with `docker build`:

```python
image = BoxdProvider.image_from_dockerfile("envs/echo_env/server/Dockerfile")
provider = BoxdProvider(image=image)
```

boxd also deletes the machine `delete_after` seconds after it was created, one
hour by default, even when `stop_container()` never runs (a crashed script, or
a Ctrl-C while the machine is being created). Set it above your longest
session, or pass `delete_after=None` to keep the machine until
`stop_container()`:

```python
provider = BoxdProvider(image="ghcr.io/huggingface/openenv-echo-env:latest", delete_after=4 * 3600)
```

`vcpu` and `memory` pick the machine size (`1`/`"4G"`, `2`/`"8G"`, `4`/`"16G"`
or `8`/`"32G"`); the organization's default applies otherwise.

Full example: [`examples/boxd_echo_env.py`](https://github.com/openenv/OpenEnv/blob/main/examples/boxd_echo_env.py).

### DaytonaProvider

Runs the server in a Daytona cloud sandbox. Install with
Expand Down
2 changes: 2 additions & 0 deletions docs/source/reference/core.md
Original file line number Diff line number Diff line change
Expand Up @@ -293,3 +293,5 @@ See [Evaluating with Environments](../tutorials/evaluation-inspect) for a worked
[[autodoc]] openenv.core.containers.runtime.hf_sandbox_provider.HFSandboxProvider

[[autodoc]] openenv.core.containers.runtime.kubernetes_provider.KubernetesProvider

[[autodoc]] openenv.core.containers.runtime.boxd_provider.BoxdProvider
67 changes: 67 additions & 0 deletions examples/boxd_echo_env.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
#!/usr/bin/env python3
"""Hello-world example running the Echo environment on boxd.

Creates a boxd machine via ``BoxdProvider``, runs the echo-env image in it with
Docker, then talks to it through ``EchoEnv`` over the machine's HTTPS URL
(https/wss). The machine is deleted when the provider closes.

Usage:
pip install "openenv[boxd]"
export BOXD_API_KEY=... (https://boxd.sh?ref=OpenEnv)
PYTHONPATH=src:envs uv run python examples/boxd_echo_env.py

Optional environment variables:
OPENENV_IMAGE registry image, or "dockerfile" to build
envs/echo_env/server/Dockerfile in the machine
(default: ghcr.io/huggingface/openenv-echo-env:latest)
BOXD_REGION "fra" or "nyc" (read by the boxd SDK)
OPENENV_NAME_PREFIX machine name prefix (default: openenv)
"""

import asyncio
import logging
import os

from echo_env import EchoEnv
from openenv.core.containers.runtime.boxd_provider import BoxdProvider

logger = logging.getLogger(__name__)


async def _interact(base_url: str) -> None:
"""Run the async WebSocket interaction against the running machine."""
async with EchoEnv(base_url=base_url) as env:
await env.reset()

tools = await env.list_tools()
logger.info("Available tools: %s", [t.name for t in tools])

echoed = await env.call_tool("echo_message", message="Hello, World!")
logger.info("echo_message -> %s", echoed)


def main() -> int:
logging.basicConfig(level=logging.INFO, format="%(message)s")

image = os.environ.get(
"OPENENV_IMAGE", "ghcr.io/huggingface/openenv-echo-env:latest"
)
if image == "dockerfile":
image = BoxdProvider.image_from_dockerfile("envs/echo_env/server/Dockerfile")

with BoxdProvider(
name_prefix=os.environ.get("OPENENV_NAME_PREFIX", "openenv"),
) as provider:
logger.info("Starting boxd machine...")
base_url = provider.start_container(image)
logger.info("Machine %s is up", provider.machine_id)
provider.wait_for_ready(base_url, timeout_s=180)
logger.info("Server ready.")
asyncio.run(_interact(base_url))
logger.info("Deleting machine...")

return 0


if __name__ == "__main__":
raise SystemExit(main())
3 changes: 3 additions & 0 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,9 @@ kubernetes = [
novita = [
"novita-sandbox>=2.1.1",
]
boxd = [
"boxd>=0.3.1",
]
inspect = [
"inspect-ai>=0.3.0",
]
Expand Down
Loading
Loading