Managed Environment Pools

Managed Environment Pools

Managed pools provide a "data in, optimized pipeline out" experience: users upload files (or point to a GitHub repo / S3 bucket), an LLM agent analyzes the data, and the system assembles a fully configured environment pool ready for GEPA/Eval.

Owner: rust_backend/src/managed_env_pool/ Agent execution: sandbox-agent (wraps OpenCode CLI into HTTP API) Pool primitives: rhodes-core crate

Architecture

User (SDK / CLI / Dashboard)
        |
        | file upload / GitHub URL / S3 config
        v
+---------------------------+
|   Synth Backend (Python)  |   auth, billing, org scoping
+------------+--------------+
             |
             v
+--------------------------------------------------+
|  rust_backend/src/managed_env_pool/              |
|                                                  |
|  1. Data Ingestion                               |
|     FileIngestor | GitIngestor | S3Ingestor      |
|     -> DataManifest (inventory, hashes, metadata) |
|                                                  |
|  2. Assembly Engine                              |
|     sandbox-agent HTTP -> OpenCode -> Claude LLM |
|     Fallback: opencode CLI -> heuristic          |
|     -> AssemblyResult (env type, files, config)  |
|                                                  |
|  3. Pool Provisioner                             |
|     PoolConfig + generated files -> PoolRegistry |
+--------------------------------------------------+
             |
             v
+--------------------------------------------------+
|  rhodes-core (imported crate)                    |
|  PoolConfig, PoolRegistry, SandboxAgentClient    |
+--------------------------------------------------+

Data Flow

1. Ingest -- user provides data via upload, GitHub URL, or S3 reference. A DataManifest is produced (file listing with sizes, SHA256 hashes, MIME types).

2. Assemble -- the assembly engine sends the manifest plus sample file contents to an LLM agent (Claude via OpenCode via sandbox-agent). The agent selects an environment type (harbor, openenv, browser, archipelago) and generates configuration files (task.toml, Dockerfile, localapi.py, etc.).

3. Provision -- the assembly output is converted to a PoolConfig, generated files are stored in blob storage, and the pool is registered with the pool registry.

API Endpoints

All endpoints are org-scoped via API key (x-user-api-key header).

Data Sources

Assembly

Assembly request body:

{
  "data_source_id": "ds_...",
  "exclusion_patterns": ["*.log", "node_modules/**"],
  "target_hint": "openenv",
  "agent_model": "claude-sonnet-4-20250514"
}

Managed Pools

Assembly Engine

The assembly engine has a 3-tier fallback:

1. sandbox-agent HTTP (preferred) -- creates a session on the sandbox-agent server, sends the prompt to OpenCode which calls the Claude LLM, polls universal-schema events via HTTP, collects text deltas, and parses the structured JSON output.

2. opencode CLI -- spawns OpenCode as a subprocess with --format json, pipes the prompt via stdin, and parses JSONL events from stdout.

3. heuristic -- pattern-matches on file names and content to guess the environment type and generate scaffold files without an LLM.

sandbox-agent Integration

The sandbox-agent is a Rust HTTP server that wraps coding agents (Claude Code, OpenCode, Codex) into a unified session-based API with universal event schema.

Session lifecycle (from rust_backend perspective):

1. POST /v1/sessions/{id}          -- create session (agent=opencode, model, permissionMode)
2. POST /v1/sessions/{id}/messages -- send assembly prompt
3. GET  /v1/sessions/{id}/events   -- poll universal events (offset pagination)
4. POST /v1/sessions/{id}/permissions/{pid}/reply -- auto-approve permissions
5. POST /v1/sessions/{id}/terminate -- cleanup

Event processing: The engine collects item.delta events for text content and watches for session.idle or session.ended to detect completion. permission.requested events are auto-approved with "always".

OpenCode SSE specifics: OpenCode v1.1.18+ wraps SSE events in a {"directory":"...","payload":{...}} structure. The sandbox-agent unwraps the payload before converting to universal schema. A typed dispatch function (opencode_typed_event) routes events by the type field to avoid issues with the generated #[serde(untagged)] Event enum where greedy variants swallow events.

Agent Output Format

The agent is prompted to output structured JSON:

{
  "environment_type": "openenv",
  "reasoning": "This is a text classification task...",
  "generated_files": {
    "task.toml": "...",
    "localapi.py": "...",
    "Dockerfile": "..."
  },
  "pool_config": {
    "pool_id": "...",
    "type": "openenv",
    "concurrency": 4
  },
  "task_definitions": [...]
}

The parser is lenient: pool_config and task_definitions are optional with fallback defaults. The JSON extractor finds the last valid JSON block in the agent output to avoid capturing prompt echo text.

Environment Types

Feature Flags

Assembly Events (SSE)

Events streamed via GET /v1/managed-pools/assembly/:id/events:

Directory Structure

rust_backend/src/managed_env_pool/
├── mod.rs              # ManagedPoolService, feature flags, orchestration
├── types.rs            # DataSource, AssemblyRecord, ManagedPool, etc.
├── upload.rs           # Presigned upload URL generation
├── api/
│   ├── mod.rs
│   ├── routes.rs       # 21 Axum route handlers
│   ├── requests.rs     # Request DTOs
│   └── responses.rs    # Response DTOs
├── assembly/
│   ├── mod.rs
│   ├── engine.rs       # 3-tier assembly engine (agent -> CLI -> heuristic)
│   ├── prompts.rs      # LLM prompt template
│   ├── parser.rs       # Lenient JSON parser for agent output
│   └── generators/     # Heuristic fallback generators
│       ├── openenv.rs  # OpenEnv localapi.py generation
│       ├── harbor.rs   # Harbor scaffold
│       ├── browser.rs  # Browser scaffold
│       └── archipelago.rs
├── ingestion/
│   ├── mod.rs
│   ├── file.rs         # File/archive ingestor
│   ├── github.rs       # Git clone ingestor
│   ├── s3.rs           # S3 bucket ingestor
│   └── manifest.rs     # DataManifest builder
├── provisioner/
│   ├── mod.rs
│   └── storage.rs      # Generated file blob storage
└── store/
    ├── mod.rs
    └── postgres.rs     # DB persistence for data sources, assemblies, pools

MVP: Banking77 Flow

1. User uploads test.csv + categories.json (Banking77 dataset)
2. System ingests files and produces DataManifest
3. User calls POST /v1/managed-pools/assemble
4. Assembly engine sends manifest + file samples to Claude via sandbox-agent
5. Agent determines: environment_type = openenv, generates localapi.py with text classification logic, Dockerfile, task.toml
6. Pool is provisioned as PoolType::Openenv with concurrency=4
7. User runs GEPA against the managed pool