README.md

---
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

```bash
pip install -e .
```

### 2. Run server

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

### 3. Validate OpenEnv spec

```bash
openenv validate
```

### 4. Build Docker image

```bash
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:

```bash
python inference.py
```

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

## Hugging Face Spaces Deployment

From project root:

```bash
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:

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

It checks:
- HF Space ping (`/reset`)
- Docker build
- `openenv validate`

## Project Structure

```text
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
```