---
title: Agterm Environment Server
emoji: 🎼
colorFrom: purple
colorTo: blue
sdk: docker
pinned: false
app_port: 8000
base_path: /web
tags:
  - openenv
---

# Agterm Environment

Lightweight echo environment for testing OpenEnv-compatible clients and APIs.

This repository provides:

- A small FastAPI server that executes any command in a bash shell.
- A minimal Python client to connect to a running environment.
- A Dockerfile for building a containerized environment useful for CI or deployment.

## Quick Start — Python client

Install the project dependencies (see `pyproject.toml`) and use the client:

```python
from openenv_agterm import agtermAction, agtermEnv

env = agtermEnv.from_docker_image("openenv_agterm-env:latest")
try:
    res = env.reset()
    print("Reset echoed:", res.observation.echoed_message)

    r = env.step(AgtermAction(message="echo 'Hello World'"))
    print("Echo:", r.observation.result)
    print("Reward:", r.reward)
finally:
    env.close()
```

Notes:

- `from_docker_image()` starts the container, waits for readiness, and connects the client.
- If you connect with `AgtermEnv(base_url=...)`, `close()` will not stop the external server.

## Build & Run

Build the Docker image from the repository root:

```bash
docker build -t agterm-env:latest -f server/Dockerfile .
```

Run the server locally (development):

```bash
# from repository root
uvicorn server.app:app --reload
```

Or run the built image:

```bash
docker run --rm -p 8000:8000 agterm-env:latest
```

API surface (when server running):

- `GET /health` — health check
- `GET /docs` — OpenAPI/Swagger UI
- `GET /web` — web UI (if included in the image)

## Environment API & Models

Action (`AgtermAction`):

- `message` (str): text to echo back.

Observation (`AgtermObservation`):

- `result` (str): result of the command
- `reward` (float): computed reward
- `done` (bool): True if error
- `metadata` (dict): extra info (e.g., step count)

Reward formula:

- Successful result = 1.0
- Failed result = -1.0

## Development & Tests

Run the environment module directly for quick checks:

```bash
python3 server/agterm_environment.py
```

Run the FastAPI app locally:

```bash
uvicorn server.app:app --reload
```

## Project layout

- [client.py](client.py) — Python client implementation and helpers
- [models.py](models.py) — pydantic models for actions and observations
- [server/app.py](server/app.py) — FastAPI application entry
- [server/agterm_environment.py](server/AGTerm_environment.py) — core environment logic (scriptable)
- [server/Dockerfile](server/Dockerfile) — image definition used to build `agterm-env`
- [openenv.yaml](openenv.yaml) — OpenEnv manifest
- [pyproject.toml](pyproject.toml) — project metadata and dependencies

## Deployment

You can push this environment to Hugging Face Spaces or similar container hosts. If using `openenv` tooling, run `openenv push` from the environment directory (where `openenv.yaml` is located) and follow its prompts.

## Next steps

- Verify the server locally with `uvicorn` and exercise the client in a small script.
- Build the Docker image and test containerized runs.
- (Optional) Deploy to a Spaces/Cloud environment for public testing.

---

See [client.py](client.py) and [server/app.py](server/app.py) for implementation details.