openenv/pr_813/en/getting-started.md

Getting Started

Install OpenEnv, load an environment, and run your first step.

Install OpenEnv

pip install openenv

This installs the openenv CLI and the openenv.core runtime. Environment projects can depend on openenv[core] when they only need the server and client libraries.

Try an Environment

Use AutoEnv and AutoAction when you want OpenEnv to find the matching client and action classes for an installed or discoverable environment.

from openenv import AutoAction, AutoEnv

env = AutoEnv.from_env("echo")
EchoAction = AutoAction.from_env("echo")

with env.sync() as client:
    result = client.reset()
    print(result.observation.echoed_message)  # "Echo environment ready!"

    result = client.step(EchoAction(message="Hello, OpenEnv!"))
    print(result.observation.echoed_message)  # "Hello, OpenEnv!"

AutoEnv.from_env() accepts the common name forms:

AutoEnv.from_env("echo")
AutoEnv.from_env("echo-env")
AutoEnv.from_env("echo_env")

Connect to a Running Environment

OpenEnv clients are async by default. Use the async client for production code, parallel environment runs, and integrations with async frameworks.

import asyncio

from echo_env import EchoAction, EchoEnv

async def main():
    async with EchoEnv(base_url="https://openenv-echo-env.hf.space") as client:
        result = await client.reset()
        print(result.observation.echoed_message)

        result = await client.step(EchoAction(message="Hello, World!"))
        print(result.reward)

asyncio.run(main())

For scripts and notebooks, use .sync():

from echo_env import EchoAction, EchoEnv

with EchoEnv(base_url="https://openenv-echo-env.hf.space").sync() as client:
    result = client.reset()
    result = client.step(EchoAction(message="Hello, World!"))
    print(result.observation.echoed_message)

Use Containers or Local Servers

You can run an environment from a Docker image:

import asyncio

from echo_env import EchoEnv

async def main():
    client = await EchoEnv.from_docker_image(
        "registry.hf.space/openenv-echo-env:latest"
    )
    async with client:
        result = await client.reset()
        print(result.observation)

asyncio.run(main())

If you run the Hugging Face Space image yourself with docker run, expose port 7860 and connect to that port:

docker run -it -p 7860:7860 --platform=linux/amd64 \
    registry.hf.space/openenv-echo-env:latest

from echo_env import EchoEnv

with EchoEnv(base_url="http://localhost:7860").sync() as client:
    result = client.reset()

Or connect to a local server:

cd path/to/echo-env
uv venv
source .venv/bin/activate
uv pip install -e .
uv run server --host 0.0.0.0 --port 8000

from echo_env import EchoEnv

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

Next Steps

• Concepts
• Explore environments
• Build your first environment