refactor: Replace MinIO with S3-compatible storage

- Updated configuration and environment variables to transition from MinIO to S3 storage, including changes to .env.example and Docker Compose files.
- Introduced a new S3Config class for managing S3 settings and removed the MinIO configuration.
- Refactored file management and state archival services to utilize the S3 client, ensuring compatibility with S3 operations.
- Adjusted health checks and service dependencies to reflect the new S3 storage integration.
- Updated documentation and comments throughout the codebase to replace references to MinIO with S3.

Author: usnavy13

.env.example

@@ -35,12 +35,13 @@ REDIS_PORT=6379
 # REDIS_PASSWORD=
 # REDIS_URL=redis://localhost:6379/0  # Alternative to individual settings
 
-# ── MinIO / S3 ─────────────────────────────────────────────────
-MINIO_ENDPOINT=localhost:9000
-MINIO_ACCESS_KEY=minioadmin
-MINIO_SECRET_KEY=minioadmin
-# MINIO_SECURE=false
-# MINIO_BUCKET=code-interpreter-files
+# ── S3 Storage (Garage) ────────────────────────────────────────
+S3_ENDPOINT=localhost:3900
+S3_ACCESS_KEY=minioadmin
+S3_SECRET_KEY=minioadmin
+# S3_SECURE=false
+# S3_BUCKET=code-interpreter-files
+# S3_REGION=garage
 
 # ── Execution Limits ───────────────────────────────────────────
 # MAX_EXECUTION_TIME=30    # Seconds (default: 30)

docker-compose.prod.yml

@@ -9,7 +9,7 @@ services:
       - SYS_ADMIN
       # NET_ADMIN required to install iptables egress rules for sandbox uid
       # when ENABLE_SANDBOX_NETWORK=true. Restricts sandbox traffic to the
-      # inline allowlist proxy and prevents SSRF to Redis/MinIO/etc.
+      # inline allowlist proxy and prevents SSRF to Redis/S3/etc.
       - NET_ADMIN
     security_opt:
       - apparmor:unconfined
@@ -19,7 +19,7 @@ services:
       - .env
     environment:
       - REDIS_HOST=redis
-      - MINIO_ENDPOINT=minio:9000
+      - S3_ENDPOINT=garage:3900
     volumes:
       - sandbox-data:/var/lib/code-interpreter/sandboxes
       # Persistent skill-deps cache: pip/npm/go/cargo install here when
@@ -34,8 +34,8 @@ services:
     depends_on:
       redis:
         condition: service_healthy
-      minio-init:
-        condition: service_completed_successfully
+      garage:
+        condition: service_healthy
     healthcheck:
       test: ["CMD-SHELL", "curl -fs http://localhost:8000/health || curl -fsk https://localhost:8000/health"]
       interval: 30s
@@ -63,43 +63,33 @@ services:
       timeout: 5s
       retries: 5
 
-  minio:
-    image: minio/minio:latest
-    container_name: code-interpreter-minio
+  # Garage S3-compatible object storage (replaces MinIO)
+  garage:
+    image: dxflrs/garage:v2.3.0
+    container_name: code-interpreter-garage
     restart: unless-stopped
+    command: >
+      server
+      --single-node
+      --default-bucket ${S3_BUCKET:-code-interpreter-files}
     ports:
-      - "127.0.0.1:${MINIO_PORT:-9000}:9000"
-      - "127.0.0.1:${MINIO_CONSOLE_PORT:-9001}:9001"
+      - "127.0.0.1:${S3_PORT:-3900}:3900"
+      - "127.0.0.1:${GARAGE_ADMIN_PORT:-3903}:3903"
     environment:
-      MINIO_ROOT_USER: ${MINIO_ACCESS_KEY:-minioadmin}
-      MINIO_ROOT_PASSWORD: ${MINIO_SECRET_KEY:-minioadmin}
-    command: server /data --console-address ":9001"
+      GARAGE_DEFAULT_ACCESS_KEY: ${S3_ACCESS_KEY:-minioadmin}
+      GARAGE_DEFAULT_SECRET_KEY: ${S3_SECRET_KEY:-minioadmin}
     volumes:
-      - minio-data:/data
+      - garage-data:/var/lib/garage
+      - ./garage.toml:/etc/garage.toml
     healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
+      test: ["CMD-SHELL", "curl -sf http://localhost:3900 || exit 1"]
       interval: 10s
       timeout: 5s
       retries: 5
-
-  minio-init:
-    image: minio/mc:latest
-    depends_on:
-      minio:
-        condition: service_healthy
-    entrypoint: >
-      /bin/sh -c "
-      mc alias set myminio http://minio:9000 $${MINIO_ACCESS_KEY:-minioadmin} $${MINIO_SECRET_KEY:-minioadmin};
-      mc mb --ignore-existing myminio/$${MINIO_BUCKET:-code-interpreter-files};
-      exit 0;
-      "
-    environment:
-      MINIO_ACCESS_KEY: ${MINIO_ACCESS_KEY:-minioadmin}
-      MINIO_SECRET_KEY: ${MINIO_SECRET_KEY:-minioadmin}
-      MINIO_BUCKET: ${MINIO_BUCKET:-code-interpreter-files}
+      start_period: 10s
 
 volumes:
   sandbox-data:
   skill-deps:
   redis-data:
-  minio-data:
+  garage-data:

docker-compose.yml

@@ -23,7 +23,7 @@ services:
     environment:
       # Container-specific overrides (service discovery within compose network)
       - REDIS_HOST=redis
-      - MINIO_ENDPOINT=minio:9000
+      - S3_ENDPOINT=garage:3900
     volumes:
       - sandbox-data:/var/lib/code-interpreter/sandboxes
       # SSL_CERTS_PATH is a host path; SSL_CERT_FILE and SSL_KEY_FILE must point
@@ -34,8 +34,8 @@ services:
     depends_on:
       redis:
         condition: service_healthy
-      minio-init:
-        condition: service_completed_successfully
+      garage:
+        condition: service_healthy
     healthcheck:
       test: ["CMD-SHELL", "curl -fs http://localhost:8000/health || curl -fsk https://localhost:8000/health"]
       interval: 30s
@@ -65,44 +65,32 @@ services:
       timeout: 5s
       retries: 5
 
-  # MinIO for file storage
-  minio:
-    image: minio/minio:latest
-    container_name: code-interpreter-minio
+  # Garage S3-compatible object storage (replaces MinIO)
+  garage:
+    image: dxflrs/garage:v2.3.0
+    container_name: code-interpreter-garage
     restart: unless-stopped
+    command: >
+      server
+      --single-node
+      --default-bucket ${S3_BUCKET:-code-interpreter-files}
     ports:
-      - "127.0.0.1:${MINIO_PORT:-9000}:9000"
-      - "127.0.0.1:${MINIO_CONSOLE_PORT:-9001}:9001"
+      - "127.0.0.1:${S3_PORT:-3900}:3900"
+      - "127.0.0.1:${GARAGE_ADMIN_PORT:-3903}:3903"
     environment:
-      MINIO_ROOT_USER: ${MINIO_ACCESS_KEY:-minioadmin}
-      MINIO_ROOT_PASSWORD: ${MINIO_SECRET_KEY:-minioadmin}
-    command: server /data --console-address ":9001"
+      GARAGE_DEFAULT_ACCESS_KEY: ${S3_ACCESS_KEY:-minioadmin}
+      GARAGE_DEFAULT_SECRET_KEY: ${S3_SECRET_KEY:-minioadmin}
     volumes:
-      - minio-data:/data
+      - garage-data:/var/lib/garage
+      - ./garage.toml:/etc/garage.toml
     healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
+      test: ["CMD-SHELL", "curl -sf http://localhost:3900 || exit 1"]
       interval: 10s
       timeout: 5s
       retries: 5
-
-  # MinIO bucket initialization
-  minio-init:
-    image: minio/mc:latest
-    depends_on:
-      minio:
-        condition: service_healthy
-    entrypoint: >
-      /bin/sh -c "
-      mc alias set myminio http://minio:9000 $${MINIO_ACCESS_KEY:-minioadmin} $${MINIO_SECRET_KEY:-minioadmin};
-      mc mb --ignore-existing myminio/$${MINIO_BUCKET:-code-interpreter-files};
-      exit 0;
-      "
-    environment:
-      MINIO_ACCESS_KEY: ${MINIO_ACCESS_KEY:-minioadmin}
-      MINIO_SECRET_KEY: ${MINIO_SECRET_KEY:-minioadmin}
-      MINIO_BUCKET: ${MINIO_BUCKET:-code-interpreter-files}
+      start_period: 10s
 
 volumes:
   sandbox-data:
   redis-data:
-  minio-data:
+  garage-data:

garage.toml

@@ -0,0 +1,11 @@
+metadata_dir = "/var/lib/garage/meta"
+data_dir = "/var/lib/garage/data"
+db_engine = "sqlite"
+replication_factor = 1
+
+[s3_api]
+s3_region = "garage"
+api_bind_addr = "[::]:3900"
+
+[admin]
+api_bind_addr = "[::]:3903"

requirements.txt

@@ -16,8 +16,8 @@ redis==7.2.0
 # SQLite async support for metrics
 aiosqlite>=0.19.0
 
-# MinIO/S3 client
-minio==7.2.20
+# S3 storage client (Garage/any S3-compatible backend)
+boto3>=1.35.0
 
 # Date/time parsing utilities
 python-dateutil==2.9.0.post0

src/api/exec.py

@@ -64,7 +64,7 @@ async def execute_code(
     within the same session, whether the caller supplies `session_id` directly
     or the orchestrator reuses a session through same-user file references or
     `entity_id` continuity. State is stored in Redis (2 hour TTL) with
-    automatic archival to MinIO for long-term storage (7 day TTL).
+    automatic archival to S3 for long-term storage (configurable TTL).
 
     Returns a streaming response that sends keepalive whitespace before the
     JSON body to prevent client socket timeouts during long operations.

src/api/files.py

@@ -135,7 +135,7 @@ async def upload_file(
             # Sanitize filename to match what will be used in container
             sanitized_name = OutputProcessor.sanitize_filename(file.filename)
 
-            # Store with sanitized name so MinIO, sandbox, and cleanup all use the same name
+            # Store with sanitized name so S3, sandbox, and cleanup all use the same name
             file_id = await file_service.store_uploaded_file(
                 session_id=session_id,
                 filename=sanitized_name,

src/api/health.py

@@ -116,25 +116,25 @@ async def redis_health_check(_: str = Depends(verify_api_key)):
         )
 
 
-@router.get("/health/minio", summary="MinIO health check")
-async def minio_health_check(_: str = Depends(verify_api_key)):
-    """Check MinIO/S3 connectivity and performance."""
+@router.get("/health/s3", summary="S3 storage health check")
+async def s3_health_check(_: str = Depends(verify_api_key)):
+    """Check S3 storage connectivity and performance."""
     try:
-        result = await health_service.check_minio()
+        result = await health_service.check_s3()
 
         if result.status == HealthStatus.UNHEALTHY:
             return JSONResponse(status_code=503, content=result.to_dict())
         else:
             return JSONResponse(status_code=200, content=result.to_dict())
 
     except Exception as e:
-        logger.error("MinIO health check failed", error=str(e))
+        logger.error("S3 health check failed", error=str(e))
         return JSONResponse(
             status_code=503,
             content={
-                "service": "minio",
+                "service": "s3",
                 "status": "unhealthy",
-                "error": str(e) if settings.api_debug else "MinIO check failed",
+                "error": str(e) if settings.api_debug else "S3 check failed",
             },
         )
 

src/config/__init__.py

@@ -29,7 +29,7 @@
 # Import grouped configurations
 from .api import APIConfig
 from .redis import RedisConfig
-from .minio import MinIOConfig
+from .s3 import S3Config
 from .security import SecurityConfig
 from .resources import ResourcesConfig
 from .logging import LoggingConfig
@@ -143,12 +143,13 @@ class Settings(BaseSettings):
     redis_socket_timeout: int = Field(default=5, ge=1)
     redis_socket_connect_timeout: int = Field(default=5, ge=1)
 
-    # MinIO/S3 Configuration
-    minio_endpoint: str = Field(default="localhost:9000")
-    minio_access_key: str = Field(default="test-access-key", min_length=3)
-    minio_secret_key: str = Field(default="test-secret-key", min_length=8)
-    minio_secure: bool = Field(default=False)
-    minio_bucket: str = Field(default="code-interpreter-files")
+    # S3 Storage Configuration
+    s3_endpoint: str = Field(default="localhost:3900")
+    s3_access_key: str = Field(default="test-access-key", min_length=3)
+    s3_secret_key: str = Field(default="test-secret-key", min_length=8)
+    s3_secure: bool = Field(default=False)
+    s3_bucket: str = Field(default="code-interpreter-files")
+    s3_region: str = Field(default="garage")
 
     # Sandbox (nsjail) Configuration
     nsjail_binary: str = Field(
@@ -196,7 +197,7 @@ class Settings(BaseSettings):
     # Session Configuration
     session_ttl_hours: int = Field(default=24, ge=1, le=168)
     session_cleanup_interval_minutes: int = Field(default=60, ge=1, le=1440)
-    enable_orphan_minio_cleanup: bool = Field(default=True)
+    enable_orphan_s3_cleanup: bool = Field(default=True)
 
     # Sandbox Pool Configuration
     sandbox_pool_enabled: bool = Field(default=True)
@@ -250,24 +251,24 @@ class Settings(BaseSettings):
         default=100,
         ge=1,
         le=500,
-        description="Max state size (MB, raw bytes) for Redis storage. Larger states go directly to MinIO",
+        description="Max state size (MB, raw bytes) for Redis storage. Larger states go directly to S3 cold storage",
     )
 
-    # State Archival Configuration - Hybrid Redis + MinIO storage
+    # State Archival Configuration - Hybrid Redis + S3 storage
     state_archive_enabled: bool = Field(
-        default=True, description="Enable archiving inactive states from Redis to MinIO"
+        default=True, description="Enable archiving inactive states from Redis to S3"
     )
     state_archive_after_seconds: int = Field(
         default=3600,
         ge=300,
         le=86400,
-        description="Archive state to MinIO after this many seconds of inactivity. Default: 1 hour",
+        description="Archive state to S3 after this many seconds of inactivity. Default: 1 hour",
     )
     state_archive_ttl_days: int = Field(
         default=1,
         ge=1,
         le=30,
-        description="Keep archived states in MinIO for N days. Default: 1 (24 hours)",
+        description="Keep archived states in S3 for N days. Default: 1 (24 hours)",
     )
     state_archive_check_interval_seconds: int = Field(
         default=300,
@@ -449,12 +450,12 @@ def parse_api_keys(cls, v):
         """Parse comma-separated API keys into a list."""
         return [key.strip() for key in v.split(",") if key.strip()] if v else None
 
-    @validator("minio_endpoint")
-    def validate_minio_endpoint(cls, v):
-        """Ensure MinIO endpoint doesn't include protocol."""
+    @validator("s3_endpoint")
+    def validate_s3_endpoint(cls, v):
+        """Ensure S3 endpoint doesn't include protocol."""
         if v.startswith(("http://", "https://")):
             raise ValueError(
-                "MinIO endpoint should not include protocol (use minio_secure instead)"
+                "S3 endpoint should not include protocol (use s3_secure instead)"
             )
         return v
 
@@ -505,14 +506,15 @@ def redis(self) -> RedisConfig:
         )
 
     @property
-    def minio(self) -> MinIOConfig:
-        """Access MinIO configuration group."""
-        return MinIOConfig(
-            minio_endpoint=self.minio_endpoint,
-            minio_access_key=self.minio_access_key,
-            minio_secret_key=self.minio_secret_key,
-            minio_secure=self.minio_secure,
-            minio_bucket=self.minio_bucket,
+    def s3(self) -> S3Config:
+        """Access S3 storage configuration group."""
+        return S3Config(
+            s3_endpoint=self.s3_endpoint,
+            s3_access_key=self.s3_access_key,
+            s3_secret_key=self.s3_secret_key,
+            s3_secure=self.s3_secure,
+            s3_bucket=self.s3_bucket,
+            s3_region=self.s3_region,
         )
 
     @property
@@ -539,7 +541,7 @@ def resources(self) -> ResourcesConfig:
             max_filename_length=self.max_filename_length,
             session_ttl_hours=self.session_ttl_hours,
             session_cleanup_interval_minutes=self.session_cleanup_interval_minutes,
-            enable_orphan_minio_cleanup=self.enable_orphan_minio_cleanup,
+            enable_orphan_s3_cleanup=self.enable_orphan_s3_cleanup,
         )
 
     @property
@@ -612,7 +614,7 @@ def is_file_allowed(self, filename: str) -> bool:
     # Grouped configs
     "APIConfig",
     "RedisConfig",
-    "MinIOConfig",
+    "S3Config",
     "SecurityConfig",
     "ResourcesConfig",
     "LoggingConfig",