README.md

---
title: Self-Healing DevOps Sandbox
emoji: 🔧
colorFrom: red
colorTo: green
sdk: docker
pinned: false
app_port: 8000
base_path: /web
tags:
  - openenv
---

# Self-Healing DevOps Sandbox

An OpenEnv RL environment where an AI agent is dropped into a **broken Node.js backend** inside a Docker container. The agent must use **bash commands only** to diagnose bugs, edit files, and fix the app -- just like a real DevOps engineer would.

Built for the **Meta PyTorch OpenEnv Hackathon**.

---

## What Is This?

A 3-task challenge of increasing difficulty. The agent starts in a Docker container with a broken Express.js app in `/app` and must make all endpoints healthy.

| # | Difficulty | Bug             | What's Wrong                          |
|---|-----------|-----------------|---------------------------------------|
| 1 | Easy      | `config.json`    | Port set to `9999` instead of `3000`  |
| 2 | Medium    | `routes/users.js`| Missing `)` causes SyntaxError crash  |
| 3 | Hard      | `routes/data.js` | Missing `await` causes HTTP 500       |

**Goal:** Fix all bugs so these endpoints return HTTP 200:
- `GET /health` returns `{"status": "ok"}`
- `GET /api/users` returns `{"users": [...]}`
- `GET /api/data` returns `{"records": [...]}`

---

## Scoring (Partial Rewards)

The grader runs **after every command** and awards cumulative points:

| Milestone                        | Points | Total    |
|----------------------------------|--------|----------|
| App starts on port 3000          | +0.35  | 0.35     |
| `/health` returns 200            | +0.10  | 0.45     |
| `/api/users` returns valid JSON  | +0.15  | 0.60     |
| `/api/data` returns valid JSON   | +0.25  | 0.85     |
| All endpoints correct            | +0.15  | **1.00** |

---

## Getting Started

### Prerequisites

- **Python 3.10+**
- **Docker Desktop** (running)
- **uv** package manager (`pip install uv`)

### 1. Install Dependencies

```bash
cd devops_sandbox
uv sync
```

### 2. Build the Sandbox Docker Image

```bash
docker build -t devops-sandbox-node:latest -f simulated_app/Dockerfile simulated_app/
```

### 3. Start the Environment Server

```bash
uv run server
```

The server starts at `http://localhost:8000`.

### 4. Run the Baseline Agent

In a **separate terminal**:

```bash
# Set your OpenAI API key
export OPENAI_API_KEY="sk-..."          # Linux/Mac
$env:OPENAI_API_KEY = "sk-..."          # PowerShell

# Run the baseline
uv run python baseline.py
```

---

## Test Your Own Agent

### Option A: Use the Python Client

```python
from devops_sandbox import BashAction, DevopsSandboxEnv

with DevopsSandboxEnv(base_url="http://localhost:8000").sync() as env:
    # Reset creates a fresh Docker container
    result = env.reset()
    print(result.observation.stdout)       # Task description
    print(result.observation.grader_score)  # 0.0

    # Send bash commands
    result = env.step(BashAction(command="cat /app/config.json"))
    print(result.observation.stdout)       # File contents
    print(result.observation.grader_score)  # Score after grading

    # Fix a bug
    result = env.step(BashAction(command="sed -i 's/9999/3000/' /app/config.json"))
    print(result.observation.grader_score)  # Partial score

    # Check if done
    if result.done:
        print("Episode complete!")
```

### Option B: Use the REST API Directly

```bash
# Reset the environment
curl -X POST http://localhost:8000/reset

# Send a command
curl -X POST http://localhost:8000/step \
  -H "Content-Type: application/json" \
  -d '{"action": {"command": "ls -la /app"}}'
```

### Option C: Use the WebSocket Endpoint

Connect to `ws://localhost:8000/ws` for persistent sessions.

---

## Project Structure

```
devops_sandbox/
|-- openenv.yaml                 # OpenEnv manifest
|-- pyproject.toml               # Python dependencies
|-- README.md                    # This file
|-- baseline.py                  # LLM-powered baseline agent
|-- models.py                    # BashAction & TerminalObservation schemas
|-- client.py                    # Python client for the environment
|
|-- server/
|   |-- app.py                   # FastAPI server (entry point)
|   +-- devops_sandbox_environment.py  # Environment logic + grader
|
+-- simulated_app/               # The broken Node.js app (Docker context)
    |-- Dockerfile               # node:20-slim sandbox container
    |-- package.json             # Express.js project
    |-- server.js                # Main entry point
    |-- config.json              # Bug 1: wrong port
    +-- routes/
        |-- users.js             # Bug 2: syntax error
        +-- data.js              # Bug 3: missing await
```

---

## How It Works

```
+-----------+   BashAction    +------------+   docker exec   +--------------+
|  Agent    | --------------> |  OpenEnv   | --------------> |  Docker      |
| (LLM/RL) |                 |  Server    |                 |  Container   |
|           | <-------------- |  (8000)    | <-------------- |  (broken app)|
+-----------+  Observation    +-----+------+   stdout/stderr +--------------+
               + grader_score       |
                              +-----+------+
                              |   Grader   |
                              | (curl test |
                              |  endpoints)|
                              +------------+
```

1. **Agent** sends a `BashAction` (e.g., `cat /app/config.json`)
2. **Server** runs it inside the Docker container via `docker exec`
3. **Grader** restarts the Node app and curls all endpoints
4. **Observation** returns: stdout, stderr, score (0.0-1.0), feedback

---

## Configuration

| Env Variable        | Default                  | Description                        |
|--------------------|--------------------------|------------------------------------|
| `OPENAI_API_KEY`    | *(required)*             | OpenAI API key for baseline        |
| `OPENAI_MODEL`      | `gpt-4o-mini`            | LLM model to use                   |
| `OPENAI_BASE_URL`   | *(OpenAI default)*       | Custom endpoint (Ollama, vLLM)     |
| `MAX_TURNS`         | `30`                     | Max steps per episode              |
| `DEVOPS_SANDBOX_URL`| `http://localhost:8000`  | Environment server URL             |

### Use with Local LLMs (Ollama, vLLM)

```bash
export OPENAI_BASE_URL="http://localhost:11434/v1"
export OPENAI_MODEL="llama3"
export OPENAI_API_KEY="dummy"
uv run python baseline.py
```

---

## Validation

```bash
uv run openenv validate
# Expected: [OK] devops_sandbox: Ready for multi-mode deployment
```

---

## License

BSD-style license. See LICENSE for details.