README.md

metadata

title: FixOS Environment Server
emoji: 🔧
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
app_port: 8000
base_path: /web
tags:
  - openenv
  - troubleshooting
  - deterministic

FixOS

FixOS is a deterministic OS troubleshooting simulation environment for evaluating AI agents on realistic system maintenance workflows.

The environment simulates:

• Processes with PID, CPU %, and memory usage
• Services (nginx, mysql) with status and config dependencies
• Filesystem with config/log files and disk impact
• Resources (cpu_percent, memory_mb, disk_percent)
• Timestamped logs and command history
• Deterministic task variants with reproducible scoring

OpenEnv Spec Compliance

This project implements:

• Typed models in models.py
• reset(), step(), and state in server/my_env_environment.py
• OpenEnv manifest in openenv.yaml
• FastAPI server in server/app.py
• Baseline script in inference.py

Tasks and Difficulty

There are 7 deterministic tasks across 3 tiers:

• easy_1: nginx stopped
• easy_2: mysql stopped + log hint
• medium_1: invalid nginx config + log hint
• medium_2: invalid mysql config + log hint
• hard_1: invalid nginx config + disk 97% + high CPU pid 909 + mysql dependency issue
• hard_2: invalid mysql config + disk 98% + high CPU pid 910 + nginx dependency issue
• hard_3: invalid nginx config + disk 99% + cpu contention (pids 920/921) + port blocker pid 922

Task selection is deterministic and cycles in fixed order per reset.

Action Space

FixOSAction

• command: str
• args: dict

Supported commands:

• ps, top, df, status, logs, cat, edit, restart, kill, rm

Observation Space

FixOSObservation

• command_output: str
• processes: List[ProcessInfo]
• services: List[ServiceInfo]
• filesystem: List[FileInfo]
• resources: Dict[str, float]
• logs: List[LogEntry]
• history: List[str]
• task_id: str
• task_difficulty: str
• task_score: float
• is_success_step: bool
• remaining_steps: int
• reward: float
• done: bool

Reward Function (0.0 to 1.0 per step)

Positive signals:

• +0.1 exploration commands (ps/top/df/status/logs/cat)
• +0.2 diagnostic hit from logs or config reads with error/warn patterns
• +0.3 edit attempt
• +0.3 kill high CPU process (cpu >= 50)
• +0.3 file removal that reduces disk
• +0.5 service restart from stopped/failed to running
• +0.5 disk normalized from >95 to <=95
• +0.5 task solved
• +0.4 * delta score improvement

Reward is clamped to [0.0, 1.0].

Quick Start

1. Install dependencies

pip install -e .

2. Run server

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

3. Validate OpenEnv spec

openenv validate

4. Build Docker image

docker build -t fixos-env:latest -f server/Dockerfile .

Baseline Inference

The required inference script is at inference.py.

Required environment variables:

• API_BASE_URL
• MODEL_NAME
• HF_TOKEN

Run:

python inference.py

The script emits structured logs using [START], [STEP], and [END] records.

Hugging Face Spaces Deployment

From project root:

openenv push

After deployment verify:

• POST /reset returns HTTP 200
• openenv validate passes locally
• Docker image builds successfully

Pre-submission Validator

Run your validator script before submission:

./validate-submission.sh https://your-space.hf.space .

It checks:

• HF Space ping (/reset)
• Docker build
• openenv validate

Project Structure

my_env/
+-- __init__.py
+-- client.py
+-- inference.py
+-- models.py
+-- openenv.yaml
+-- pyproject.toml
+-- README.md
+-- requirements.txt
`-- server/
  +-- __init__.py
  +-- app.py
  +-- Dockerfile
  +-- my_env_environment.py
  `-- requirements.txt