tutorial/tutorial2.md

# 2. Deploying an OpenEnv environment

This section covers deploying OpenEnv environments locally, on clusters, and on Hugging Face Spaces.

**Contents:**
- [Local Development with Uvicorn](#local-development-with-uvicorn)
- [Docker Deployment](#docker-deployment)
- [Hugging Face Spaces](#hugging-face-spaces)
- [Best Practices](#best-practices)

## HF Spaces are the infrastructure for OpenEnv environments

Every HF Space provides three things that OpenEnv environments need:

| Component | What it provides | How to access | Used as |
|-----------|------------------|---------------|-----------|
| **Server** | Running environment endpoint | `https://<username>-<space-name>.hf.space` | Agent and Public API |
| **Repository** | Installable Python package | `pip install git+https://huggingface.co/spaces/<username>-<space-name>` | Code and client |
| **Registry** | Docker container image | `docker pull registry.hf.space/<username>-<space-name>:latest` | Deployment |

This means a single Space deployment gives you all the components you need to use an environment in training.

### 1. Server: A running environment endpoint

When you deploy to HF Spaces, your environment runs as a server. The client connects via **WebSocket** (`/ws`) for a persistent session:

```python

from echo_env import EchoEnv, EchoAction



# Connect directly to the running Space (WebSocket under the hood)

# Async (recommended):

async with EchoEnv(base_url="https://openenv-echo-env.hf.space") as client:

    result = await client.reset()

    result = await client.step(EchoAction(message="Hello"))



# Sync (using .sync() wrapper):

with EchoEnv(base_url="https://openenv-echo-env.hf.space").sync() as client:

    result = client.reset()

    result = client.step(EchoAction(message="Hello"))

```

**Endpoints available:**

| Endpoint | Protocol | Description |
|----------|----------|-------------|
| `/ws` | **WebSocket** | Persistent session (used by client) |
| `/health` | HTTP GET | Health check |
| `/reset` | HTTP POST | Reset environment (stateless) |
| `/step` | HTTP POST | Execute action (stateless) |
| `/state` | HTTP GET | Get current state |
| `/docs` | HTTP GET | OpenAPI documentation |
| `/web` | HTTP GET | Interactive web UI |

> **Note:** The Python client uses the `/ws` WebSocket endpoint by default. HTTP endpoints are available for debugging or stateless use cases.

**Example: Check if a Space is running**

```bash

curl https://openenv-echo-env.hf.space/health

# {"status": "healthy"}

```

### 2. Repository: Installable Python package

Every Space is a Git repository. OpenEnv environments include a `pyproject.toml`, making them pip-installable directly from the Space URL.

```bash

# Install client package from Space

pip install git+https://huggingface.co/spaces/openenv/echo-env

```

This installs:
- **Client class** (`EchoEnv`) — Handles HTTP/WebSocket communication
- **Models** (`EchoAction`, `EchoObservation`) — Typed action and observation classes
- **Utilities** — Any helper functions the environment provides

**After installation:**

```python

from envs.echo_env import EchoEnv, EchoAction, EchoObservation



# Now you have typed classes for the environment

action = EchoAction(message="Hello")

```

### 3. Registry: Docker container image

Every Docker-based Space has a container registry. You can pull and run the environment locally.

```bash

# Pull the image

docker pull registry.hf.space/openenv-echo-env:latest



# Run locally on port 8001

docker run -d -p 8001:8000 registry.hf.space/openenv-echo-env:latest

```

**Find the registry URL for any Space:**

1. Go to the Space page (e.g., [openenv/echo-env](https://huggingface.co/spaces/openenv/echo-env))
2. Click **⋮** (three dots) → **"Run locally"**
3. Copy the `docker run` command

### Choosing an access method

| Method | Use when | Pros | Cons |
|--------|----------|------|------|
| **Server** | Quick testing, low volume | Zero setup | Network latency, rate limits |
| **Repository** | Need typed classes | Type safety, IDE support | Still need a server |
| **Docker** | Local dev, high throughput | Full control, no network | Requires Docker |

**Typical workflow:**

```python

import asyncio

from echo_env import EchoEnv, EchoAction



async def main():

    # Development: connect to remote Space

    async with EchoEnv(base_url="https://openenv-echo-env.hf.space") as client:

        result = await client.reset()



    # Production: run locally for speed

    # docker run -d -p 8001:8000 registry.hf.space/openenv-echo-env:latest

    async with EchoEnv(base_url="http://localhost:8001") as client:

        result = await client.reset()



    # Or let the client manage Docker for you

    client = await EchoEnv.from_env("openenv/echo-env")  # Auto-pulls and runs

    async with client:

        result = await client.reset()



asyncio.run(main())



# For sync usage, use the .sync() wrapper:

with EchoEnv(base_url="http://localhost:8001").sync() as client:

    result = client.reset()

```

> **Reference:** [HF Spaces Documentation](https://huggingface.co/docs/hub/spaces) | [Environment Hub Collection](https://huggingface.co/collections/openenv/environment-hub)


## Local Development with Uvicorn

The fastest way to iterate on environment logic is running directly with Uvicorn.

## Clone and run the environment locally

```bash

# Clone from HF Space

git clone https://huggingface.co/spaces/burtenshaw/openenv-benchmark

cd openenv-benchmark



# Install in editable mode

uv sync



# Start server

uv run server



# Run isolated from remote Space

uv run --isolated --project https://huggingface.co/spaces/burtenshaw/openenv-benchmark server

```

## Uvicorn directly in python

```bash

# Full control over uvicorn options

uvicorn benchmark.server.app:app --host "$HOST" --port "$PORT" --workers "$WORKERS"



# With reload for development

uvicorn benchmark.server.app:app --host 0.0.0.0 --port 8000 --reload



# Multi-Worker Mode For better concurrency:

uvicorn benchmark.server.app:app --host 0.0.0.0 --port 8000 --workers 4

```

| Flag | Purpose |
|------|---------|
| `--reload` | Auto-restart on code changes |
| `--workers N` | Run N worker processes |
| `--log-level debug` | Verbose logging |

## Docker Deployment

Docker provides isolation and reproducibility for production use.

### Run the environment locally from the space

```bash

# Run the environment locally from the space

docker run -d -p 8000:8000 registry.hf.space/openenv-echo-env:latest

```

### Build Image

```bash

# Clone from HF Space

git clone https://huggingface.co/spaces/burtenshaw/openenv-benchmark

cd openenv-benchmark



# Using OpenEnv CLI (recommended)

openenv build -t openenv-benchmark:latest



# Or with Docker directly

docker build -t openenv-benchmark:latest -f server/Dockerfile .

```

### Run Container

```bash

# Basic run

docker run -d -p 8000:8000 my-env:latest



# With environment variables

docker run -d -p 8000:8000 \

    -e WORKERS=4 \

    -e MAX_CONCURRENT_ENVS=100 \

    my-env:latest



# Named container for easy management

docker run -d --name my-env -p 8000:8000 my-env:latest

```

### Connect from Python

```python

import asyncio

from echo_env import EchoEnv, EchoAction



async def main():

    # Async usage (recommended)

    async with EchoEnv(base_url="http://localhost:8000") as client:

        result = await client.reset()

        result = await client.step(EchoAction(message="Hello"))

        print(result.observation)



    # From Docker image

    client = await EchoEnv.from_docker_image("<local_docker_image>")

    async with client:

        result = await client.reset()

        print(result.observation)



asyncio.run(main())



# Sync usage (using .sync() wrapper)

with EchoEnv(base_url="http://localhost:8000").sync() as client:

    result = client.reset()

    result = client.step(EchoAction(message="Hello"))

    print(result.observation)

```

### Container Lifecycle

| Method | Container | WebSocket | On `close()` |
|--------|-----------|-----------|--------------|
| `from_hub(repo_id)` | Starts | Connects | Stops container |
| `from_hub(repo_id, use_docker=False)` | None (UV) | Connects | Stops UV server |
| `from_docker_image(image)` | Starts | Connects | Stops container |
| `MyEnv(base_url=...)` | None | Connects | Disconnects only |

Find Docker Commands for Any Space

1. Open the Space on HuggingFace Hub
2. Click **⋮ (three dots)** menu
3. Select **"Run locally"**
4. Copy the provided `docker run` command

## Deploy with CLI

```bash

cd my_env



# Deploy to your namespace

openenv push



# Deploy to specific repo

openenv push --repo-id username/my-env



# Deploy as private

openenv push --repo-id username/my-env --private

```

### Space Configuration

The `openenv.yaml` manifest controls Space settings:

```yaml

# openenv.yaml

name: my_env

version: "1.0.0"

description: My custom environment

```

Hardware Options:

| Tier | vCPU | RAM | Cost |
|------|------|-----|------|
| CPU Basic (Free) | 2 | 16GB | Free |
| CPU Upgrade | 8 | 32GB | $0.03/hr |

OpenEnv environments support configuration via environment variables.

| Variable | Default | Description |
|----------|---------|-------------|
| `WORKERS` | 4 | Uvicorn worker processes |
| `PORT` | 8000 | Server port |
| `HOST` | 0.0.0.0 | Bind address |
| `MAX_CONCURRENT_ENVS` | 100 | Max WebSocket sessions |
| `ENABLE_WEB_INTERFACE` | Auto | Enable web UI |

### Environment-Specific Variables

Some environments have custom variables:

**TextArena:**
```bash

TEXTARENA_ENV_ID=Wordle-v0

TEXTARENA_NUM_PLAYERS=1

TEXTARENA_MAX_TURNS=6

```

**Coding Environment:**
```bash

SANDBOX_TIMEOUT=30

MAX_OUTPUT_LENGTH=10000

```

# DEMO: Deploying to Hugging Face Spaces

This demo walks through the full workflow: create an environment, test locally, deploy to HF Spaces, and use it.

## Step 1: Initialize a new environment

```bash

openenv init my_env

cd my_env

```

This creates the standard OpenEnv structure:

```

my_env/

├── server/

│   ├── app.py           # FastAPI server

│   ├── environment.py   # Your environment logic

│   └── Dockerfile

├── models.py            # Action/Observation types

├── client.py            # HTTP client

├── openenv.yaml         # Manifest

└── pyproject.toml

```

## Step 2: Run locally

```bash

# Start the server

uv run server



# Or with uvicorn directly

uvicorn server.app:app --host 0.0.0.0 --port 8000 --reload

```

Test the health endpoint:

```bash

curl http://localhost:8000/health

# {"status": "healthy"}

```

## Step 3: Deploy to HF Spaces

```bash

openenv push --repo-id username/my-env

```

Your environment is now live at:
- Web UI: https://username-my-env.hf.space/web
- API Docs: https://username-my-env.hf.space/docs
- Health: https://username-my-env.hf.space/health

```bash

curl https://openenv-echo-env.hf.space/health

# {"status": "healthy"}

```

## Step 4: install the environment

```bash

uv pip install git+https://huggingface.co/spaces/openenv/echo_env

```

## Step 5: Run locally via Docker (optional)

Pull and run the container from the HF registry, or open the [browser](https://huggingface.co/spaces/openenv/echo_env?docker=true):

```bash

# Pull from HF Spaces registry

docker pull registry.hf.space/openenv-echo-env:latest



# Run locally

docker run -it -p 7860:7860 --platform=linux/amd64 \

	registry.hf.space/openenv-echo-env:latest

```

Now connect to your local instance:

```python

import asyncio

from echo_env import EchoEnv, EchoAction



# Async (recommended)

async def main():

    async with EchoEnv(base_url="http://localhost:8000") as env:

        result = await env.reset()

        print(result.observation)

        result = await env.step(EchoAction(message="Hello"))

        print(result.observation)



asyncio.run(main())



# Sync (using .sync() wrapper)

with EchoEnv(base_url="http://localhost:8000").sync() as env:

    result = env.reset()

    print(result.observation)

    result = env.step(EchoAction(message="Hello"))

    print(result.observation)

```