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