Eclipse Che integration with Agent Sandbox

[ibuziuk]

Introduction

Since we are considering having a dedicated Agent Space exposed on the User Dashboard, Agent Sandbox might be the actual runtime that powers this new type of workload.

Agent-sandbox from kubernetes-sigs enables easy management of isolated, stateful, singleton workloads, ideal for use cases like AI agent runtimes:

• https://github.com/kubernetes-sigs/agent-sandbox
• https://agent-sandbox.sigs.k8s.io/

Executive Summary

This epic proposes integrating Kubernetes agent-sandbox into che-operator to expand Eclipse Che's capabilities beyond Cloud Development Environments (CDEs) to also support AI agent runtimes.

Key Proposal: Add agent-sandbox as an optional dependency alongside DevWorkspace Operator, enabling Eclipse Che to orchestrate secure, isolated AI agent execution environments while maintaining its core CDE functionality.

Background

Current Architecture

Eclipse Che currently supports CDEs through integration with DevWorkspace Operator (DWO):

┌─────────────────────────────────────────────────────────┐
│                     Eclipse Che                         │
│  ┌──────────────┐  ┌─────────┐  ┌──────────────┐        │
│  │  Dashboard   │  │  Server │  │ Registry     │  ...   │
│  └──────────────┘  └─────────┘  └──────────────┘        │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│            DevWorkspace Operator (DWO)                  │
│  - Manages workspace pod lifecycle                      │
│  - Devfile-based configuration                          │
│  - Routing                                              │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
                   User CDEs (Cloud Development Environments)
    

Why Agent Sandbox?

Stronger Isolation for Untrusted Code:
AI agents may execute LLM-generated code that requires kernel-level isolation beyond standard containers.

Resource Efficiency:
Hibernation/resume and warm pools optimize costs for intermittent agent workloads.

Stable Identity:
Long-running agents benefit from persistent network identity across restarts.

Programmatic API:
Designed for applications to consume programmatically, not just human users.

High-Level Design

┌─────────────────────────────────────────────────────────────────┐
│                        Eclipse Che                              │
│  ┌──────────────┐  ┌─────────┐  ┌──────────────┐                │
│  │  Dashboard   │  │ Gateway │  │ DevFile Reg  │  ...           │
│  └──────────────┘  └─────────┘  └──────────────┘                │
│                                                                 │
│  New: Agent Dashboard / API for managing agent sandboxes        │
└─────────────────────────────────────────────────────────────────┘
            │                                    │
            ▼                                    ▼
┌──────────────────────────┐      ┌──────────────────────────────┐
│ DevWorkspace Operator    │      │   Agent Sandbox              │
│ - CDEs (devfile-based)   │      │   - AI agent runtimes        │
│ - Human developers       │      │   - Strong isolation         │
│ - Multi-container        │      │   - Hibernation/resume       │
└──────────────────────────┘      └──────────────────────────────┘
            │                                    │
            ▼                                    ▼
    Cloud Development Environments           Agentic Development Environments

Integration Levels (Phased Approach)

[DONE] Phase 1: Coexistence (Minimal Integration)

Goal: Verify agent-sandbox can run alongside che-operator without conflicts.

Scope:

• Deploy agent-sandbox operator in cluster
• No changes to che-operator code
• Manual Sandbox CR creation by advanced users
• Validate networking, RBAC, and resource quotas don't conflict

Deliverables:

• Installation documentation
• Compatibility matrix

[NOT STARTED] Phase 2: API Integration

Goal: Optional dependency on agent-sandbox from che-operator . Add support for agent runtimes in CheCluster API as a feature toggle

Scope:

• Extend CheCluster CR with smth. like spec.Components.AgentRuntimes / spec.Components.Agents / spec.Components.AgentSandbox
• Add controller to watch agent-sandbox namespace
• Integrate agent-sandbox routing with Che gateway (if needed)
• Add RBAC management for agent sandboxes

Deliverables:

• CRD changes + regenerated manifests
• AgentRuntimeReconciler controller
• RBAC rules for managing Sandbox CRs
• Documentation for enabling agent runtimes

[NOT STARTED] Phase 3: Full Integration (Future)

Goal: Unified user experience for CDEs and agent runtimes.

Scope:

• Dashboard UI for creating/managing agent sandboxes (separate epic)
• Unified routing through Che gateway
• Integration with Che authentication/authorization
• Templates for common agent types (code execution, testing, build, editor)
• Gateway-routed editor access for human-in-the-loop review (/agent/<name>/editor/)
• Metrics and monitoring for agent sandboxes
• Persistence of the Skills, settings, and MCPs across the Agent Runtimes

Installation & Dependencies

Agent-sandbox is optional, installed separately by cluster admin (similar flow as community-supported Image Puller)

# CheCluster with agent runtimes
apiVersion: org.eclipse.che/v2
kind: CheCluster
metadata:
  name: eclipse-che
spec:
  agentRuntimes:
    enable: true
    namespace: agent-sandbox-system
    runtimeClassName: gvisor

If agentRuntimes.enable=true but agent-sandbox operator is not present, reconciliation logs a warning and skips agent runtime setup.

Backward Compatibility

• Agent runtime support is opt-in via spec.agentRuntimes.enable
• Existing CheCluster CRs without this field continue working unchanged
• No impact on DevWorkspace Operator integration

References

• agent-sandbox GitHub
• DevWorkspace Operator
• Eclipse Che Architecture
• gVisor
• Kata Containers
• OpenShell Gateway Operator

Progress

[DONE] Phase 1: Coexistence (Minimal Integration)

POC with Eclipse and OGO (OpenShift Gateway Operator) - that deploys and manages NVIDIA OpenShell Gateway instances has been successfully crafted by deploying the operator on the dedicated cluster - https://github.com/aknochow/ogo

Agent Sandbox CRD (agents.x-k8s.io) is a pre-req for the setup.

Eclipse Che configuration is described in the doc: https://github.com/aknochow/ogo/blob/main/docs/guides/devspaces.md

[ibuziuk]

@tolusha please, take a look at the Phase 2: API Integration during the next sprint