Spaces:
Sleeping
Sleeping
File size: 2,695 Bytes
3c75da2 3661dd4 3c75da2 3661dd4 3c75da2 3661dd4 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 | ---
title: Terminus Environment Server
emoji: 🛠️
colorFrom: green
colorTo: blue
sdk: docker
pinned: false
app_port: 8000
base_path: /web
tags:
- openenv
- terminus
- hf-sandbox
- coding
short_description: Single-tool HF Sandbox-backed coding environment
---
# Terminus Environment
`terminus_env` is a single-tool coding environment backed by
[hf-sandbox](https://github.com/huggingface/hf-sandbox). Each OpenEnv episode
creates a fresh Hugging Face Jobs-backed sandbox, runs optional
setup commands, keeps shell state and files isolated for that episode, and runs
optional verify commands when the agent submits a final answer.
The tool shape follows the Terminus-style "one tool" idea: agents do their work
through a single terminal entrypoint rather than a notebook/toolbox surface.
## Tool
- `terminal(command="", final_answer="")`: run a shell command inside the
session sandbox, or submit a final answer and run verification.
## Quick Start
```python
from terminus_env import TerminusEnv
with TerminusEnv(base_url="http://localhost:8000").sync() as env:
env.reset(
setup=["mkdir -p /home/user/work"],
verify=["test -f /home/user/work/answer.txt"],
)
print(env.call_tool("terminal", command="echo done > /home/user/work/answer.txt"))
print(env.call_tool("terminal", final_answer="done"))
```
## Local Server
```bash
cd envs/terminus_env
HF_TOKEN=hf_... uv run --project . server
```
The API and custom terminal web UI are served on port 8000. The UI is mounted
at `/web`.
## Docker
```bash
cd envs/terminus_env
openenv build -t terminus-env
docker run -p 8000:8000 -e HF_TOKEN=hf_... terminus-env
```
## Configuration
- `HF_TOKEN`: required by `hf-sandbox` to launch Hugging Face Jobs.
- `HF_SANDBOX_IMAGE`: sandbox image. Defaults to `python:3.12`.
- `HF_SANDBOX_FLAVOR`: Hugging Face Jobs flavor. Defaults to `cpu-basic`.
- `HF_SANDBOX_TIMEOUT`: Hugging Face Jobs timeout. Defaults to `1h`.
- `HF_SANDBOX_FORWARD_HF_TOKEN`: forward `HF_TOKEN` into the sandbox. Defaults
to `false`.
- `MAX_CONCURRENT_ENVS`: maximum concurrent WebSocket sessions. Defaults to `4`.
## Setup and Verify Commands
`reset()` accepts either `setup` / `verify` or `setup_scripts` /
`verify_scripts`.
```python
env.reset(
setup=["pip install -q pytest"],
verify=["pytest -q /home/user/work/tests"],
)
```
Setup failure ends the reset response with `done=True` and returns captured
setup results. Verify commands run when `terminal(final_answer="...")` is
called. Reward defaults to `passed_verify_commands / total_verify_commands`. A
verify command can override this by writing a float to:
```text
/home/user/logs/verifier/reward.txt
```
|