README.md

metadata

title: CloudEnv
emoji: ☁️
colorFrom: blue
colorTo: blue
sdk: docker
pinned: false
app_port: 8000
base_path: /web
tags:
  - openenv

CloudEnv

CloudEnv is a modular simulation environment for cloud infrastructure built on OpenEnv, backed by a local AWS emulator. It allows RL and LLM agents to interact with, diagnose, and repair realistic distributed cloud systems.

Quick Start

from cloudenv import CloudEnvAction, MyEnv
from cloudenv.server.providers.aws.services import AWSService

env = MyEnv.from_docker_image("cloudenv-env:latest")

env.reset()

# Initialize the environment session before taking AWS actions.
env.step(
    CloudEnvAction(
        episode_id="ep-1",
        task_id="easy-task-1",
        service=AWSService.INTERNAL,
        operation="InitializeEnvironment",
        payload={},
    )
)

action = CloudEnvAction(
    episode_id="ep-1",
    task_id="easy-task-1",
    service=AWSService.S3,
    operation="CreateBucket",
    payload={"Bucket": "test-bucket"},
)

result = env.step(action)
print(result.observation)

env.close()

Core Concepts

Action

# Required once per episode: task_id == pipeline_id
CloudEnvAction(
    episode_id="ep-1",
    task_id="easy-task-1",
    service=AWSService.INTERNAL,
    operation="InitializeEnvironment",
    payload={},
)

CloudEnvAction(
    episode_id="ep-1",
    task_id="easy-task-1",
    service=AWSService.S3,
    operation="PutObject",
    payload={"Bucket": "b", "Key": "k", "Body": b"data"},
)

Observation

{
  "task_id": "easy-task-1",
  "episode_id": "easy-task-episode-1",
  "step_count": 3,
  "operation_result": {
    "service": "s3",
    "operation": "PutBucketPolicy",
    "status": "SUCCESS"
  },
  "reward": 0.7,
  "done": false,
  "current_pipeline_state": {
    "s3:bucket_1": [
      {
        "service": "s3",
        "instance": "bucket1",
        "policies": []
      }
    ]
  }
}

Pipeline API

CloudEnv exposes a lightweight pipeline lifecycle API under /api/pipelines:

• POST /api/pipelines create and materialize a pipeline.
• GET /api/pipelines list pipelines with broken/ideal graphs.
• GET /api/pipelines/{pipeline_id} fetch a pipeline.
• PUT /api/pipelines/{pipeline_id} rename a pipeline ID.
• DELETE /api/pipelines/{pipeline_id} remove a pipeline.
• GET /api/pipelines/{pipeline_id}/validate validate policies/config vs ideal.

Example create request:

curl -X POST http://localhost:8000/api/pipelines \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline_id": "easy-task-1",
    "broken_pipeline": { "s3:bucket_1": [{"service": "s3:bucket1","policies": []}] },
    "ideal_pipeline": { "s3:bucket_1": [{"service": "s3:bucket1","policies": []}] }
  }'

task_id in CloudEnvAction must match the pipeline_id created here.

Inference Script

cloudenv/inference.py loads a task JSON (for example cloudenv/tasks/easy-task.json), initializes the environment, registers the pipeline via /api/pipelines, then runs an LLM loop to propose actions until convergence. Key steps:

• env.reset() (no args) and InitializeEnvironment to start the episode.
• register_pipeline() to create + materialize the broken/ideal graphs.
• Loop guards for repeated actions and no state change.

Key env vars: TASK_NAME, SERVER_URL, MODEL_NAME, MAX_STEPS.

Testing Pipelines

Pipeline test scenarios and solution steps live in cloudenv/docs/api/Pipeline Tests/. Each solution sequence should end with done=true and reward=0.99 when replayed in order.

Initialize example (required before actions):

curl --request POST \
  --url http://localhost:8000/step \
  --header 'content-type: application/json' \
  --data '{
  "action": {
    "service": "internal",
    "operation": "InitializeEnvironment",
    "task_id": "hard-task-1",
    "episode_id": "hard-episode-1"
  }
}'

Local tests (requires LocalStack/Ministack running at localhost:4566):

pytest cloudenv/tests/test_cloudenv_environment.py

Environment Design

Engines

• BuildEngine: Creates infrastructure from a sequence of steps
• CorruptionEngine: Injects failures
• RewardEngine: Rewards recovery and penalizes regressions

Example Build Plan

e, t = "ep-1", "easy-task-1"
steps = [
    CloudEnvAction(
        episode_id=e,
        task_id=t,
        service=AWSService.INTERNAL,
        operation="InitializeEnvironment",
        payload={},
    ),
    CloudEnvAction(
        episode_id=e, task_id=t, service=AWSService.IAM, operation="CreateRole", payload={}
    ),
    CloudEnvAction(
        episode_id=e,
        task_id=t,
        service=AWSService.LAMBDA,
        operation="CreateFunction",
        payload={},
    ),
    CloudEnvAction(
        episode_id=e,
        task_id=t,
        service=AWSService.S3,
        operation="CreateBucket",
        payload={},
    ),
]

Running Locally

uv run --project . server
# or
python -m cloudenv.server.app --port 8000

Docker

docker build -t cloudenv .
docker run \
  --rm \
  --name cloudenv \
  -p 4566:4566 \
  -p 8000:8000 \
  cloudenv

Project Structure

cloudenv/
├── client.py
├── inference.py
├── models.py
├── openenv.yaml
├── tasks/
├── docs/
│   └── api/Pipeline Tests/
├── tests/
├── server/
│   ├── app.py
│   ├── api/pipeline/
│   ├── cloudenv_environment.py
│   ├── managers/
│   └── providers/aws/

Deployment

openenv push