SETUP.md

SentinelOps Arena — Complete Setup Guide

1. Local Dev Environment

Python Version

• Required: Python 3.14 (system) or 3.12+ (venv)
• Current venv: Python 3.14.2 in hackathon_env/.venv/ (created by uv)
• Root venv: Python 3.12.12 in .venv/ (created by uv)
• OpenEnv 0.2.1 requires >=3.10, works fine on 3.14
• Tool manager: uv 0.9.26 (installed at /Users/nihalnihalani/.local/bin/uv)

Existing Environment State

The hackathon_env/ directory already has a working OpenEnv echo environment with:

• openenv-core==0.2.1 installed in hackathon_env/.venv/
• Working Environment subclass pattern (see server/hackathon_env_environment.py)
• Working create_app() HTTP server (see server/app.py)
• Working EnvClient subclass with _step_payload() and _parse_result() (see client.py)
• Working Dockerfile for HF Spaces deployment
• openenv.yaml spec file

CRITICAL: The venv has a broken interpreter path

The hackathon_env/.venv/bin/openenv script points to /Users/nihalnihalani/Desktop/Github/openev/hackathon_env/.venv/bin/python (note openev not NexusEnv). This means the venv was created in a different directory and moved. The Python binary itself works fine, but CLI entry points are broken.

Fix: Recreate the venv from hackathon_env/:

cd /Users/nihalnihalani/Desktop/Github/NexusEnv/hackathon_env
uv venv .venv --python 3.14
uv sync

Dependencies — pyproject.toml for SentinelOps

The project needs a root-level pyproject.toml for the SentinelOps Arena package. The hackathon_env/pyproject.toml only covers the echo env template.

[build-system]
requires = ["setuptools>=45", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "sentinelops-arena"
version = "0.1.0"
description = "Multi-agent self-play training environment for enterprise AI security"
requires-python = ">=3.10"
dependencies = [
    # Core OpenEnv runtime
    "openenv-core[core]>=0.2.1",
    # MCP tool server
    "mcp>=1.26.0",
    "fastmcp>=2.14.5",
    # HTTP server
    "fastapi>=0.115.0",
    "uvicorn>=0.24.0",
    # MCP-X gateway dependencies
    "PyJWT>=2.0",
    "toml>=0.10.2",
    "httpx>=0.27",
    # Gradio for HF Spaces demo UI
    "gradio>=5.0.0",
    # Data handling
    "pydantic>=2.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=8.0.0",
    "pytest-cov>=4.0.0",
]
training = [
    # These are for local training only, NOT for HF Spaces
    "trl>=0.15.0",
    "transformers>=4.40.0",
    "torch>=2.0.0",
    "accelerate>=0.30.0",
    "datasets>=2.18.0",
    "peft>=0.10.0",
]

[project.scripts]
server = "sentinelops_arena.server:main"

[tool.setuptools]
include-package-data = true
packages = ["sentinelops_arena", "sentinelops_arena.systems"]

Pinned Dependency Versions (from envbeats reference)

Package	Min Version	Source
openenv-core	0.2.1	hackathon_env/pyproject.toml
mcp	1.26.0	eb_assessor/pyproject.toml
fastmcp	2.14.5	mcp-x/pyproject.toml
fastapi	0.128.6+	mcp-x/pyproject.toml
PyJWT	2.0+	mcp-x/pyproject.toml
toml	0.10.2+	mcp-x/pyproject.toml
httpx	0.27+	mcp-x/pyproject.toml
uvicorn	0.24.0+	hackathon_env/server/requirements.txt
pydantic	2.0+	transitive via openenv-core
gradio	5.0+	for HF Spaces demo UI

---

2. Infrastructure Setup

Northflank H100

• Each team gets H100 GPU access via Northflank
• Used for training only (not deployment)
• Request at hackathon check-in or via organizer Slack
• Configure: SSH access, install Python 3.10+, CUDA drivers
• Not required for MVP — can use Colab free tier for training demo

HuggingFace

• Account: Already have (nihalnihalani)
• Join openenv-community: Required for $30 compute credits — join org at huggingface.co
• Create Space: nihalnihalani/sentinelops-arena
  • SDK: Docker (custom Dockerfile) or Gradio
  • Hardware: CPU Basic (free) or CPU Upgrade ($0.03/hr from credits)
• Push command: openenv push --space nihalnihalani/sentinelops-arena OR manual git push to HF repo

Google Colab

• Training notebook: training/colab_training.ipynb
• Runtime: T4 GPU (free tier) or A100 if credits available
• Key concern: Colab runs Python 3.10-3.11, but openenv-core requires >=3.10 (should work)
• Fallback: Bundle standalone env code in notebook without openenv import (for Python compat)

YouTube

• Account for demo video upload
• Video length: 1 minute (per spec, NOT 3-5 minutes as in the build plan)
• Screen record: Gradio demo + training signal
• Upload as unlisted, share link in submission

---

3. Repository Structure

Target File Tree

NexusEnv/
├── .git/
├── .gitignore
├── .venv/                          # Root venv (Python 3.12)
├── CLAUDE.md                       # Claude Code rules
├── README.md                       # Project README (update for submission)
├── SENTINELOPS_ARENA.md            # Full spec document
├── SETUP.md                        # This file
├── pyproject.toml                  # Root project config (NEW)
├── app.py                          # HF Spaces entry point — Gradio app (NEW)
├── sentinelops_arena/              # Core package (NEW)
│   ├── __init__.py
│   ├── models.py                   # Pydantic models: Action, Observation, State, data models
│   ├── systems/
│   │   ├── __init__.py
│   │   ├── crm.py                  # CRM simulator
│   │   ├── billing.py              # Billing simulator
│   │   └── ticketing.py            # Ticketing simulator
│   ├── attacks.py                  # Attack mechanics (4 types)
│   ├── rewards.py                  # Reward functions (3 agents)
│   ├── task_generator.py           # Customer task generation
│   ├── environment.py              # SentinelOpsArena(Environment)
│   ├── mcp_tools.py                # FastMCP tool definitions
│   ├── server.py                   # create_app() HTTP server
│   └── demo.py                     # Demo script with heuristic agents
├── mcp_x/                          # MCP-X gateway (adapted from envbeats) (NEW)
│   ├── mcp_x.py                    # Gateway server (copy+adapt)
│   └── config.toml                 # Per-agent tool ACLs
├── training/                       # Training deliverables (NEW)
│   ├── colab_training.ipynb        # REQUIRED Colab notebook
│   └── rollout.py                  # rollout_func for GRPOTrainer
├── envbeats/                       # Reference implementation (existing, read-only)
│   ├── eb_assessor/
│   ├── eb_assessee_gym/
│   └── mcp-x/
├── hackathon_env/                  # Original echo env template (existing, reference)
│   ├── ...
│   └── server/
│       ├── Dockerfile              # Reference Dockerfile
│       └── app.py                  # Reference create_app() usage
└── train.py                        # Existing training script (update or replace)

Key Files to Create (in build order)

1. pyproject.toml — root project config
2. sentinelops_arena/__init__.py
3. sentinelops_arena/models.py — all Pydantic models
4. sentinelops_arena/systems/__init__.py
5. sentinelops_arena/systems/crm.py
6. sentinelops_arena/systems/billing.py
7. sentinelops_arena/systems/ticketing.py
8. sentinelops_arena/attacks.py
9. sentinelops_arena/rewards.py
10. sentinelops_arena/task_generator.py
11. sentinelops_arena/environment.py
12. sentinelops_arena/mcp_tools.py
13. sentinelops_arena/server.py
14. sentinelops_arena/demo.py
15. app.py — Gradio HF Spaces entry point
16. mcp_x/mcp_x.py + mcp_x/config.toml
17. training/colab_training.ipynb

---

4. Deployment Config

HuggingFace Spaces — Two Options

Option A: Gradio SDK (Simpler, Recommended)

HF Spaces README.md header: ```yaml

title: SentinelOps Arena emoji: 🛡️ colorFrom: red colorTo: blue sdk: gradio sdk_version: 5.12.0 app_file: app.py pinned: false license: mit

No Dockerfile needed. HF auto-installs from `requirements.txt`:

**requirements.txt** (for HF Spaces):

openenv-core[core]>=0.2.1 mcp>=1.26.0 fastmcp>=2.14.5 fastapi>=0.115.0 uvicorn>=0.24.0 PyJWT>=2.0 toml>=0.10.2 httpx>=0.27 gradio>=5.0.0 pydantic>=2.0

#### Option B: Docker (If Gradio SDK fails)
Use adapted Dockerfile from `hackathon_env/server/Dockerfile`.

HF Spaces README.md header:
```yaml
---
title: SentinelOps Arena
emoji: 🛡️
colorFrom: red
colorTo: blue
sdk: docker
pinned: false
license: mit
---

Dockerfile:

FROM python:3.14-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .

# Gradio uses port 7860 on HF Spaces
EXPOSE 7860
CMD ["python", "app.py"]

Deployment Commands

# Option 1: Using openenv CLI
cd sentinelops_arena
openenv push --space nihalnihalani/sentinelops-arena

# Option 2: Manual HF push
# Create space on huggingface.co first, then:
git remote add hf https://huggingface.co/spaces/nihalnihalani/sentinelops-arena
git push hf main

# Option 3: Using huggingface_hub Python API
from huggingface_hub import HfApi
api = HfApi()
api.upload_folder(folder_path=".", repo_id="nihalnihalani/sentinelops-arena", repo_type="space")

---

5. Submission Checklist

Every field required in the submission form:

Field	Value	Status
Team Name	TBD (e.g., "NexusEnv" or "SentinelOps")	Need to decide
Project Description	Multi-agent self-play RL environment where 3 AI agents (Attacker, Worker, Oversight) interact with simulated enterprise systems. Through adversarial dynamics, agents learn to attack, defend, and audit enterprise operations.	Draft ready
HuggingFace Spaces Link	https://huggingface.co/spaces/nihalnihalani/sentinelops-arena	Need to create
Demo Video (YouTube)	1-minute screencast of Gradio demo + training	Need to record
Minimal Training Script	Colab notebook link (training/colab_training.ipynb)	Need to build
Partner Tracks	Fleet AI (Scalable Oversight), Patronus AI (Schema Drift)	Selected

Submission Deadline

Sunday, March 8th, 2026 at 1:00 PM

---

6. Pre-flight Checks

Before Writing Any Code

• Python 3.14 available (system)
• uv installed and working
• OpenEnv 0.2.1 installed in hackathon_env/.venv/
• OpenEnv Environment/Action/Observation/State APIs understood
• EnvBeats patterns analyzed (create_app, MCP-X, client patterns)
• Git repo initialized, on main branch
• Create nihal branch (per CLAUDE.md push rules)
• Create root pyproject.toml
• Set up new venv with all dependencies: uv venv .venv && uv sync
• Verify imports: python -c "from openenv.core.env_server.interfaces import Environment; print('OK')"
• Create HF Space (can be empty placeholder)
• HuggingFace: Join openenv-community org for $30 credits

Critical API Patterns (from hackathon_env reference)

Environment class:

from openenv.core.env_server.interfaces import Environment
from openenv.core.env_server.types import Action, Observation, State

class MyEnv(Environment):
    SUPPORTS_CONCURRENT_SESSIONS = True

    def reset(self, seed=None, episode_id=None, **kwargs) -> MyObservation:
        ...

    def step(self, action: MyAction, timeout_s=None, **kwargs) -> MyObservation:
        ...

    @property
    def state(self) -> State:  # NOTE: property, not method
        ...

Action class:

class MyAction(Action):
    # extra='forbid' inherited from Action base
    field: str = Field(..., description="...")

Observation class:

class MyObservation(Observation):
    # Inherits: done (bool), reward (float|None), metadata (dict)
    my_field: str = Field(default="", description="...")

HTTP Server:

from openenv.core.env_server.http_server import create_app
app = create_app(MyEnv, MyAction, MyObservation, env_name="my_env")
# Run: uvicorn module:app --host 0.0.0.0 --port 8000

Client:

from openenv.core import EnvClient
class MyClient(EnvClient[MyAction, MyObservation]):
    def _step_payload(self, action: MyAction) -> Dict:
        return action.model_dump()
    def _parse_result(self, payload: Dict) -> StepResult[MyObservation]:
        ...

Known Gotchas

1. Action has extra='forbid' — SentinelAction must not have extra fields
2. state is a @property not a method — use env.state not env.state()
3. create_app() returns an ASGI app — use uvicorn.run(app) not app.run()
4. Observation reward field type is bool | int | float | None (allows bool)
5. The hackathon_env venv has broken CLI entry points (moved from different path)
6. CLAUDE.md says push to nihal branch, not main
7. Demo video must be 1 minute, not 3-5 minutes (spec says 1 minute)

OpenEnv Version Note

The spec says "OpenEnv 0.4" but OpenEnv 0.4 does NOT exist. The stable version is 0.2.1. The SENTINELOPS_ARENA.md references "0.4" but the actual codebase and all dependencies use 0.2.1. Build against 0.2.1.

---

7. Quick Start Commands

# 1. Create nihal branch
cd /Users/nihalnihalani/Desktop/Github/NexusEnv
git checkout -b nihal

# 2. Create root pyproject.toml (see Section 1)

# 3. Set up venv
uv venv .venv --python 3.14
uv sync

# 4. Verify setup
.venv/bin/python -c "from openenv.core.env_server.interfaces import Environment; print('OpenEnv OK')"
.venv/bin/python -c "from mcp.server.fastmcp import FastMCP; print('FastMCP OK')"
.venv/bin/python -c "import gradio; print('Gradio OK')"

# 5. Start building sentinelops_arena/models.py