README.md

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

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

```python
# 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

```json
{
  "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:

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

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

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

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

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


## Docker

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

```bash
openenv push
```