feat: add config profiles

- Add ConfigProfile and ConfigProfileInclude data models with migrations
- Implement profile resolver service with ordered includes and merge rules
- Add profile CRUD API with validation, compatibility, and cycle detection
- Add instance API plumbing for profile selection on create/start/restart
- Add resolved profile preview and default resolution APIs
- Add frontend config profile API client and management UI
- Add launch/restart profile selection UI
- Add backend integration and unit tests (31 passing)

OpenSpec: add-config-profiles
Quality gates: ruff, TypeScript compile, 31 tests passing

apps/api/src/api/config_profiles.py

@@ -0,0 +1,635 @@
+"""Config profile API endpoints."""
+
+import logging
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+from pydantic import BaseModel, Field, field_validator
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import selectinload
+
+from src.auth.dependencies import get_current_user_id, get_db_session
+from src.models.config_profile import ConfigProfile, ConfigProfileInclude
+from src.models.project import Project
+from src.models.tool_type import ToolType
+from src.services.config_profile_resolver import (
+    ConfigProfileCycleError,
+    check_include_cycle,
+    resolve_profile,
+    resolved_profile_to_dict,
+)
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/config-profiles", tags=["config-profiles"])
+
+MAX_PROFILE_SIZE_MB = 10
+MAX_PROFILE_SIZE_BYTES = MAX_PROFILE_SIZE_MB * 1024 * 1024
+
+
+def _validate_uuid(v: str | None) -> str | None:
+    if v is None:
+        return v
+    try:
+        uuid.UUID(v)
+    except ValueError:
+        raise ValueError(f"Invalid UUID: {v}")
+    return v
+
+
+def _calculate_profile_size(data: dict) -> int:
+    """Calculate approximate serialized size of profile data."""
+    total = 0
+    for key, value in data.get("env_vars", {}).items():
+        total += len(key.encode("utf-8")) + len(str(value).encode("utf-8"))
+    for key, value in data.get("runtime_hints", {}).items():
+        total += len(key.encode("utf-8")) + len(str(value).encode("utf-8"))
+    for mount in data.get("mounts", []):
+        total += len(str(mount.get("target", "")).encode("utf-8"))
+        total += len(str(mount.get("mode", "")).encode("utf-8"))
+        for path, content in mount.get("files", {}).items():
+            total += len(path.encode("utf-8")) + len(content.encode("utf-8"))
+    for path, content in data.get("files", {}).items():
+        total += len(path.encode("utf-8")) + len(content.encode("utf-8"))
+    return total
+
+
+class MountItem(BaseModel):
+    target: str = Field(description="Absolute mount target path")
+    mode: str = Field(default="rw", description="Mount mode: ro or rw")
+    files: dict = Field(default_factory=dict, description="Files as {relative_path: content}")
+
+    @field_validator("target")
+    @classmethod
+    def validate_target(cls, v: str) -> str:
+        if not v.startswith("/"):
+            raise ValueError("Mount target must be absolute (start with /)")
+        return v
+
+    @field_validator("mode")
+    @classmethod
+    def validate_mode(cls, v: str) -> str:
+        if v not in ("ro", "rw"):
+            raise ValueError("Mount mode must be 'ro' or 'rw'")
+        return v
+
+    @field_validator("files")
+    @classmethod
+    def validate_files(cls, v: dict) -> dict:
+        for path in v.keys():
+            if ".." in path or path.startswith("/") or not path:
+                raise ValueError(f"Invalid file path: {path}")
+        return v
+
+
+class ConfigProfileCreate(BaseModel):
+    name: str = Field(description="Profile name (unique per user)")
+    description: str | None = Field(default=None, description="Optional description")
+    project_id: str | None = Field(default=None, description="Optional project ID")
+    tool_type_id: str | None = Field(default=None, description="Optional tool type ID")
+    env_vars: dict = Field(default_factory=dict, description="Environment variables")
+    runtime_hints: dict = Field(default_factory=dict, description="Runtime hints")
+    mounts: list[MountItem] = Field(default_factory=list, description="Mount definitions")
+    files: dict = Field(default_factory=dict, description="Files as {relative_path: content}")
+    is_default: bool = Field(default=False, description="Whether this is the default profile for its scope")
+
+    @field_validator("project_id", "tool_type_id")
+    @classmethod
+    def validate_uuids(cls, v: str | None) -> str | None:
+        return _validate_uuid(v)
+
+    @field_validator("files")
+    @classmethod
+    def validate_files(cls, v: dict) -> dict:
+        for path in v.keys():
+            if ".." in path or path.startswith("/") or not path:
+                raise ValueError(f"Invalid file path: {path}")
+        return v
+
+    @field_validator("env_vars")
+    @classmethod
+    def validate_env_vars(cls, v: dict) -> dict:
+        if not isinstance(v, dict):
+            raise ValueError("env_vars must be a JSON object")
+        return v
+
+    @field_validator("runtime_hints")
+    @classmethod
+    def validate_runtime_hints(cls, v: dict) -> dict:
+        if not isinstance(v, dict):
+            raise ValueError("runtime_hints must be a JSON object")
+        return v
+
+    @field_validator("mounts")
+    @classmethod
+    def validate_mounts(cls, v: list) -> list:
+        if not isinstance(v, list):
+            raise ValueError("mounts must be a JSON array")
+        return v
+
+
+class ConfigProfileUpdate(BaseModel):
+    name: str | None = Field(default=None, description="Profile name")
+    description: str | None = Field(default=None, description="Optional description")
+    project_id: str | None = Field(default=None, description="Optional project ID")
+    tool_type_id: str | None = Field(default=None, description="Optional tool type ID")
+    env_vars: dict | None = Field(default=None, description="Environment variables")
+    runtime_hints: dict | None = Field(default=None, description="Runtime hints")
+    mounts: list[MountItem] | None = Field(default=None, description="Mount definitions")
+    files: dict | None = Field(default=None, description="Files as {relative_path: content}")
+    is_default: bool | None = Field(default=None, description="Whether this is the default profile")
+
+    @field_validator("project_id", "tool_type_id")
+    @classmethod
+    def validate_uuids(cls, v: str | None) -> str | None:
+        return _validate_uuid(v)
+
+    @field_validator("files")
+    @classmethod
+    def validate_files(cls, v: dict | None) -> dict | None:
+        if v is None:
+            return v
+        for path in v.keys():
+            if ".." in path or path.startswith("/") or not path:
+                raise ValueError(f"Invalid file path: {path}")
+        return v
+
+
+class ConfigProfileIncludeUpdate(BaseModel):
+    includes: list[str] = Field(description="Ordered list of included profile IDs")
+
+    @field_validator("includes")
+    @classmethod
+    def validate_includes(cls, v: list) -> list:
+        for item in v:
+            try:
+                uuid.UUID(item)
+            except ValueError:
+                raise ValueError(f"Invalid UUID in includes: {item}")
+        return v
+
+
+class ConfigProfileResponse(BaseModel):
+    id: str
+    user_id: str
+    name: str
+    description: str | None
+    project_id: str | None
+    tool_type_id: str | None
+    env_vars: dict
+    runtime_hints: dict
+    mounts: list
+    files: dict
+    is_default: bool
+    includes: list[dict]
+    created_at: str
+    updated_at: str
+
+
+async def _get_profile_with_includes(session: AsyncSession, profile_id: uuid.UUID) -> ConfigProfile | None:
+    """Fetch a profile with includes eagerly loaded."""
+    result = await session.execute(
+        select(ConfigProfile)
+        .where(ConfigProfile.id == profile_id)
+        .options(selectinload(ConfigProfile.includes))
+    )
+    return result.scalar_one_or_none()
+
+
+async def _check_access(
+    session: AsyncSession,
+    user_id: uuid.UUID,
+    project_id: uuid.UUID | None = None,
+    tool_type_id: uuid.UUID | None = None,
+) -> None:
+    """Verify user has access to referenced project and tool type."""
+    if project_id is not None:
+        project = await session.get(Project, project_id)
+        if project is None:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Project not found")
+        # Add ownership check if needed; for now just verify existence
+    if tool_type_id is not None:
+        tool_type = await session.get(ToolType, tool_type_id)
+        if tool_type is None:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Tool type not found")
+
+
+def _profile_to_response(profile: ConfigProfile, includes: list[ConfigProfileInclude] | None = None) -> dict:
+    return {
+        "id": str(profile.id),
+        "user_id": str(profile.user_id),
+        "name": profile.name,
+        "description": profile.description,
+        "project_id": str(profile.project_id) if profile.project_id else None,
+        "tool_type_id": str(profile.tool_type_id) if profile.tool_type_id else None,
+        "env_vars": profile.env_vars or {},
+        "runtime_hints": profile.runtime_hints or {},
+        "mounts": profile.mounts or [],
+        "files": profile.files or {},
+        "is_default": profile.is_default,
+        "includes": [
+            {
+                "id": str(inc.id),
+                "included_profile_id": str(inc.included_profile_id),
+                "order_index": inc.order_index,
+            }
+            for inc in (includes or profile.includes)
+        ],
+        "created_at": profile.created_at.isoformat() if profile.created_at else None,
+        "updated_at": profile.updated_at.isoformat() if profile.updated_at else None,
+    }
+
+
+@router.get("", response_model=list[ConfigProfileResponse])
+async def list_config_profiles(
+    project_id: str | None = Query(None, description="Filter by project compatibility"),
+    tool_type_id: str | None = Query(None, description="Filter by tool type compatibility"),
+    current_user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+):
+    """List config profiles, optionally filtered by compatibility."""
+    user_uuid = current_user_id
+    query = select(ConfigProfile).where(ConfigProfile.user_id == user_uuid).options(selectinload(ConfigProfile.includes))
+
+    if project_id or tool_type_id:
+        # Compatibility filter: include portable profiles and matching scoped profiles
+        project_uuid = uuid.UUID(project_id) if project_id else None
+        tool_uuid = uuid.UUID(tool_type_id) if tool_type_id else None
+
+        from sqlalchemy import or_
+
+        conditions: list = []
+        # Portable profiles (no project, no tool)
+        conditions.append(
+            (ConfigProfile.project_id.is_(None)) & (ConfigProfile.tool_type_id.is_(None))
+        )
+        if project_uuid:
+            # Profiles matching this project (with or without tool)
+            conditions.append(ConfigProfile.project_id == project_uuid)
+        if tool_uuid:
+            # Profiles matching this tool (with or without project)
+            conditions.append(ConfigProfile.tool_type_id == tool_uuid)
+        if project_uuid and tool_uuid:
+            # Exact match
+            conditions.append(
+                (ConfigProfile.project_id == project_uuid) & (ConfigProfile.tool_type_id == tool_uuid)
+            )
+
+        query = query.where(or_(*conditions))
+
+    result = await session.execute(query)
+    profiles = result.scalars().all()
+    return [_profile_to_response(p) for p in profiles]
+
+
+@router.post("", response_model=ConfigProfileResponse, status_code=status.HTTP_201_CREATED)
+async def create_config_profile(
+    data: ConfigProfileCreate,
+    current_user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+):
+    """Create a new config profile."""
+    user_uuid = current_user_id
+
+    # Check for duplicate name
+    existing = await session.execute(
+        select(ConfigProfile).where(
+            ConfigProfile.user_id == user_uuid,
+            ConfigProfile.name == data.name,
+        ).options(selectinload(ConfigProfile.includes))
+    )
+    if existing.scalar_one_or_none() is not None:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=f"Profile with name '{data.name}' already exists",
+        )
+
+    # Validate references
+    project_uuid = uuid.UUID(data.project_id) if data.project_id else None
+    tool_uuid = uuid.UUID(data.tool_type_id) if data.tool_type_id else None
+    await _check_access(session, user_uuid, project_uuid, tool_uuid)
+
+    # Check size
+    size = _calculate_profile_size(data.model_dump())
+    if size > MAX_PROFILE_SIZE_BYTES:
+        raise HTTPException(
+            status_code=status.HTTP_413_REQUEST_ENTITY_TOO_LARGE,
+            detail=f"Profile size exceeds {MAX_PROFILE_SIZE_MB}MB limit",
+        )
+
+    profile = ConfigProfile(
+        user_id=user_uuid,
+        name=data.name,
+        description=data.description,
+        project_id=project_uuid,
+        tool_type_id=tool_uuid,
+        env_vars=data.env_vars,
+        runtime_hints=data.runtime_hints,
+        mounts=[m.model_dump() for m in data.mounts],
+        files=data.files,
+        is_default=data.is_default,
+    )
+    session.add(profile)
+    await session.commit()
+
+    # Re-fetch with includes to avoid lazy loading issues
+    result = await session.execute(
+        select(ConfigProfile)
+        .where(ConfigProfile.id == profile.id)
+        .options(selectinload(ConfigProfile.includes))
+    )
+    profile = result.scalar_one()
+
+    logger.info("Created config profile %s for user %s", profile.id, user_uuid)
+    return _profile_to_response(profile)
+
+
+@router.get("/{profile_id}", response_model=ConfigProfileResponse)
+async def get_config_profile(
+    profile_id: str,
+    current_user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+):
+    """Get a config profile by ID."""
+    profile = await _get_profile_with_includes(session, uuid.UUID(profile_id))
+    if profile is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Profile not found")
+    if profile.user_id != current_user_id:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Not authorized")
+    return _profile_to_response(profile)
+
+
+@router.put("/{profile_id}", response_model=ConfigProfileResponse)
+async def update_config_profile(
+    profile_id: str,
+    data: ConfigProfileUpdate,
+    current_user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+):
+    """Update a config profile."""
+    profile = await _get_profile_with_includes(session, uuid.UUID(profile_id))
+    if profile is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Profile not found")
+    if profile.user_id != current_user_id:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Not authorized")
+
+    update_data = data.model_dump(exclude_unset=True)
+
+    # Handle name uniqueness
+    if "name" in update_data:
+        existing = await session.execute(
+            select(ConfigProfile).where(
+                ConfigProfile.user_id == profile.user_id,
+                ConfigProfile.name == update_data["name"],
+                ConfigProfile.id != profile.id,
+            )
+        )
+        if existing.scalar_one_or_none() is not None:
+            raise HTTPException(
+                status_code=status.HTTP_409_CONFLICT,
+                detail=f"Profile with name '{update_data['name']}' already exists",
+            )
+
+    # Validate references
+    project_uuid = (
+        uuid.UUID(update_data["project_id"])
+        if "project_id" in update_data and update_data["project_id"]
+        else (profile.project_id if "project_id" not in update_data else None)
+    )
+    tool_uuid = (
+        uuid.UUID(update_data["tool_type_id"])
+        if "tool_type_id" in update_data and update_data["tool_type_id"]
+        else (profile.tool_type_id if "tool_type_id" not in update_data else None)
+    )
+    await _check_access(session, profile.user_id, project_uuid, tool_uuid)
+
+    # Check size
+    current_data = _profile_to_response(profile)
+    merged = {**current_data, **update_data}
+    size = _calculate_profile_size(merged)
+    if size > MAX_PROFILE_SIZE_BYTES:
+        raise HTTPException(
+            status_code=status.HTTP_413_REQUEST_ENTITY_TOO_LARGE,
+            detail=f"Profile size exceeds {MAX_PROFILE_SIZE_MB}MB limit",
+        )
+
+    # Apply updates
+    for field_name, value in update_data.items():
+        if field_name in ("project_id", "tool_type_id"):
+            value = uuid.UUID(value) if value else None
+        elif field_name == "mounts" and value is not None:
+            value = [m.model_dump() for m in value]
+        setattr(profile, field_name, value)
+
+    await session.commit()
+
+    # Re-fetch with includes to avoid lazy loading issues
+    result = await session.execute(
+        select(ConfigProfile)
+        .where(ConfigProfile.id == profile.id)
+        .options(selectinload(ConfigProfile.includes))
+    )
+    profile = result.scalar_one()
+
+    logger.info("Updated config profile %s", profile.id)
+    return _profile_to_response(profile)
+
+
+@router.delete("/{profile_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_config_profile(
+    profile_id: str,
+    current_user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+):
+    """Delete a config profile."""
+    profile = await _get_profile_with_includes(session, uuid.UUID(profile_id))
+    if profile is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Profile not found")
+    if profile.user_id != current_user_id:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Not authorized")
+
+    await session.delete(profile)
+    await session.commit()
+
+    logger.info("Deleted config profile %s", profile_id)
+    return None
+
+
+@router.put("/{profile_id}/includes", response_model=ConfigProfileResponse)
+async def update_profile_includes(
+    profile_id: str,
+    data: ConfigProfileIncludeUpdate,
+    current_user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+):
+    """Update the ordered includes for a config profile."""
+    profile = await _get_profile_with_includes(session, uuid.UUID(profile_id))
+    if profile is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Profile not found")
+    if profile.user_id != current_user_id:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Not authorized")
+
+    # Validate all included profiles exist and belong to the user
+    included_uuids = [uuid.UUID(inc_id) for inc_id in data.includes]
+    for inc_uuid in included_uuids:
+        inc_profile = await session.get(ConfigProfile, inc_uuid)
+        if inc_profile is None:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Included profile not found: {inc_uuid}",
+            )
+        if inc_profile.user_id != current_user_id:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=f"Not authorized to include profile: {inc_uuid}",
+            )
+        if inc_uuid == profile.id:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Profile cannot include itself",
+            )
+
+    # Check for cycles
+    cycle = await check_include_cycle(session, profile.id, None)
+    if cycle is None and included_uuids:
+        # Check each new include would not create a cycle
+        for inc_uuid in included_uuids:
+            cycle = await check_include_cycle(session, profile.id, inc_uuid)
+            if cycle is not None:
+                break
+
+    if cycle is not None:
+        cycle_str = " -> ".join(str(c) for c in cycle)
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Include cycle detected: {cycle_str}",
+        )
+
+    # Remove existing includes
+    result = await session.execute(
+        select(ConfigProfileInclude).where(ConfigProfileInclude.profile_id == profile.id)
+    )
+    for existing in result.scalars().all():
+        await session.delete(existing)
+    await session.flush()
+
+    # Add new includes
+    for order_index, inc_uuid in enumerate(included_uuids):
+        include = ConfigProfileInclude(
+            profile_id=profile.id,
+            included_profile_id=inc_uuid,
+            order_index=order_index,
+        )
+        session.add(include)
+    await session.flush()
+
+    await session.commit()
+
+    # Re-fetch profile (includes loaded separately due to SQLite async issue)
+    result = await session.execute(
+        select(ConfigProfile).where(ConfigProfile.id == profile.id)
+    )
+    profile = result.scalar_one()
+
+    inc_result = await session.execute(
+        select(ConfigProfileInclude).where(ConfigProfileInclude.profile_id == profile.id)
+    )
+    direct_includes = inc_result.scalars().all()
+
+    logger.info("Updated includes for config profile %s", profile.id)
+    return _profile_to_response(profile, list(direct_includes))
+
+
+@router.get("/{profile_id}/preview")
+async def preview_config_profile(
+    profile_id: str,
+    current_user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+):
+    """Preview the resolved output of a config profile."""
+    profile = await _get_profile_with_includes(session, uuid.UUID(profile_id))
+    if profile is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Profile not found")
+    if profile.user_id != current_user_id:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Not authorized")
+
+    try:
+        resolved = await resolve_profile(session, profile.id)
+    except ConfigProfileCycleError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(exc),
+        )
+
+    return resolved_profile_to_dict(resolved)
+
+
+@router.get("/defaults/resolve")
+async def resolve_default_profile(
+    project_id: str = Query(..., description="Project ID"),
+    tool_type_id: str = Query(..., description="Tool type ID"),
+    current_user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+):
+    """Resolve the default config profile for a project/tool combination.
+
+    Selects by specificity:
+    1. project+tool explicit default
+    2. project explicit default
+    3. tool explicit default
+    4. global/user explicit default
+    5. first created compatible profile
+    6. none (returns null)
+    """
+    user_uuid = current_user_id
+    project_uuid = uuid.UUID(project_id)
+    tool_uuid = uuid.UUID(tool_type_id)
+
+    # Fetch all compatible profiles ordered by created_at
+    query = (
+        select(ConfigProfile)
+        .where(ConfigProfile.user_id == user_uuid)
+        .where(
+            (ConfigProfile.project_id.is_(None) & ConfigProfile.tool_type_id.is_(None))
+            | (ConfigProfile.project_id == project_uuid)
+            | (ConfigProfile.tool_type_id == tool_uuid)
+            | (
+                (ConfigProfile.project_id == project_uuid)
+                & (ConfigProfile.tool_type_id == tool_uuid)
+            )
+        )
+        .order_by(ConfigProfile.created_at)
+    )
+    result = await session.execute(query)
+    profiles = result.scalars().all()
+
+    if not profiles:
+        return {"profile_id": None, "profile_name": None}
+
+    # Check explicit defaults by specificity
+    explicit_defaults = [p for p in profiles if p.is_default]
+
+    # Most specific: project+tool
+    for p in explicit_defaults:
+        if p.project_id == project_uuid and p.tool_type_id == tool_uuid:
+            return {"profile_id": str(p.id), "profile_name": p.name}
+
+    # Next: project only
+    for p in explicit_defaults:
+        if p.project_id == project_uuid and p.tool_type_id is None:
+            return {"profile_id": str(p.id), "profile_name": p.name}
+
+    # Next: tool only
+    for p in explicit_defaults:
+        if p.project_id is None and p.tool_type_id == tool_uuid:
+            return {"profile_id": str(p.id), "profile_name": p.name}
+
+    # Next: global/user (no project, no tool)
+    for p in explicit_defaults:
+        if p.project_id is None and p.tool_type_id is None:
+            return {"profile_id": str(p.id), "profile_name": p.name}
+
+    # Fall back to first created compatible profile
+    first = profiles[0]
+    return {"profile_id": str(first.id), "profile_name": first.name}

apps/api/src/api/tool_instances.py

@@ -20,11 +20,11 @@ from src.auth.dependencies import get_db_session
 from src.models.git_repository import GitRepository
 from src.models.project import Project
 from src.models.ssh_key import SSHKey
+from src.models.config_profile import ConfigProfile
 from src.models.tool_config import ToolConfig
 from src.models.tool_instance import ToolInstance
 from src.models.tool_type import ToolType
 from src.models.user import User
-from src.models.config_folder import ConfigFolder
 from src.services.docker import (
     check_tunnel_health,
     connect_container_to_network,
@@ -43,10 +43,14 @@ from src.services.docker import (
     write_compose_file,
     write_config_files,
     write_env_file,
-    write_config_folder_files,
 )
 from src.services.clone import check_dirty_state, clone_repository, remove_clone_directory
 from src.services.docker_build import build_image
+from src.services.config_profile_resolver import (
+    ConfigProfileCycleError,
+    apply_resolved_profile,
+    resolve_profile,
+)
 from src.services.readiness_probe import execute_probe
 from src.services.ssh_keys import prepare_ssh_key_files, cleanup_ssh_key_files
 
@@ -63,6 +67,78 @@ class CreateInstanceRequest(BaseModel):
     clone_mode: str = Field(default="mount", description="Repository access mode: 'mount' or 'clone'")
     branch: str | None = Field(default="main", description="Branch to clone (when clone_mode='clone')")
     new_branch: str | None = Field(default=None, description="Create a new local branch after cloning")
+    config_profile_id: str | None = Field(default=None, description="Optional config profile ID for launch")
+
+
+class StartInstanceRequest(BaseModel):
+    """Request body for starting a tool instance."""
+
+    model_config = {"extra": "ignore"}
+
+    config_profile_id: str | None = Field(default=None, description="Config profile ID to apply, or null for none")
+
+
+async def _validate_config_profile(
+    session: AsyncSession,
+    profile_id: str | None,
+    user_id: uuid.UUID,
+    project_id: uuid.UUID,
+    tool_type_id: uuid.UUID,
+) -> uuid.UUID | None:
+    """Validate a config profile selection.
+
+    Args:
+        session: Database session.
+        profile_id: Profile ID string or None.
+        user_id: Authenticated user ID.
+        project_id: Project ID for compatibility check.
+        tool_type_id: Tool type ID for compatibility check.
+
+    Returns:
+        Validated UUID or None.
+
+    Raises:
+        HTTPException: If profile is not found, not owned, or incompatible.
+    """
+    if profile_id is None:
+        return None
+
+    try:
+        profile_uuid = uuid.UUID(profile_id)
+    except ValueError:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Invalid config profile ID: {profile_id}",
+        )
+
+    profile = await session.get(ConfigProfile, profile_uuid)
+    if profile is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Config profile not found: {profile_id}",
+        )
+
+    if profile.user_id != user_id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Not authorized to use this config profile",
+        )
+
+    # Check compatibility: profile must be portable or match project/tool
+    is_compatible = (
+        (profile.project_id is None and profile.tool_type_id is None)
+        or (profile.project_id == project_id)
+        or (profile.tool_type_id == tool_type_id)
+        or (profile.project_id == project_id and profile.tool_type_id == tool_type_id)
+    )
+
+    if not is_compatible:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Selected config profile is not compatible with this project and tool type",
+        )
+
+    return profile_uuid
 
 
 def _modify_compose_file(
@@ -199,6 +275,11 @@ async def create_instance(
             status_code=status.HTTP_404_NOT_FOUND, detail="tool type not found"
         )
 
+    # Validate config profile if provided
+    selected_profile_id = await _validate_config_profile(
+        session, data.config_profile_id, user_id, project_id, tool_type_id
+    )
+
     try:
         # Validate clone mode requirements
         if data.clone_mode == "clone":
@@ -386,6 +467,7 @@ services:
             port=tool_port,
             clone_mode=data.clone_mode,
             branch=data.new_branch if data.new_branch else (data.branch if data.clone_mode == "clone" else None),
+            selected_config_profile_id=selected_profile_id,
         )
         session.add(instance)
         await session.commit()
@@ -399,6 +481,7 @@ services:
             "status": instance.status,
             "clone_mode": instance.clone_mode,
             "branch": instance.branch,
+            "selected_config_profile_id": str(instance.selected_config_profile_id) if instance.selected_config_profile_id else None,
             "created_at": instance.created_at.isoformat(),
         }
     except Exception as exc:
@@ -525,6 +608,7 @@ async def get_instance(
         "port": instance.port,
         "clone_mode": instance.clone_mode,
         "branch": instance.branch,
+        "selected_config_profile_id": str(instance.selected_config_profile_id) if instance.selected_config_profile_id else None,
         "last_started_at": instance.last_started_at.isoformat() if instance.last_started_at else None,
         "last_stopped_at": instance.last_stopped_at.isoformat() if instance.last_stopped_at else None,
         "created_at": instance.created_at.isoformat(),
@@ -540,6 +624,7 @@ async def start_instance(
     project_id: uuid.UUID,
     repo_id: uuid.UUID,
     instance_id: uuid.UUID,
+    data: StartInstanceRequest | None = None,
     user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> dict:
@@ -549,6 +634,7 @@ async def start_instance(
         project_id: UUID of the project.
         repo_id: UUID of the repository.
         instance_id: UUID of the instance to start.
+        data: Optional start configuration including config profile selection.
         user_id: ID of the authenticated user.
         session: Database session.
 
@@ -564,6 +650,14 @@ async def start_instance(
             status_code=status.HTTP_404_NOT_FOUND, detail="instance not found"
         )
 
+    # Validate and store config profile selection
+    if data and data.config_profile_id is not None:
+        selected_profile_id = await _validate_config_profile(
+            session, data.config_profile_id, user_id, project_id, instance.tool_type_id
+        )
+        instance.selected_config_profile_id = selected_profile_id
+        await session.commit()
+
     if not instance.compose_path or not os.path.exists(instance.compose_path):
         raise HTTPException(
             status_code=status.HTTP_400_BAD_REQUEST, detail="compose file not found"
@@ -614,17 +708,45 @@ async def start_instance(
     # Merge extra env vars
     env_vars.update(extra_env_vars)
     
-    # Fetch active config folders for this user
-    folder_query = select(ConfigFolder).where(
-        ConfigFolder.user_id == user_id,
-        ConfigFolder.is_active == True,
-    )
-    folder_result = await session.execute(folder_query)
-    config_folders = folder_result.scalars().all()
-    logger.info("Found %d active config folders for instance %s", len(config_folders), instance.id)
+    # Apply selected config profile if any
+    instance_dir = os.path.dirname(instance.compose_path)
+    if instance.selected_config_profile_id is not None:
+        try:
+            resolved = await resolve_profile(session, instance.selected_config_profile_id)
+            profile_env, profile_files, profile_mounts, profile_hints = apply_resolved_profile(
+                instance_dir, resolved
+            )
+            # Profile env vars override tool config env vars
+            env_vars.update(profile_env)
+            # Profile files are written by apply_resolved_profile
+            config_files.update(profile_files)
+            # Profile mounts are added to extra volumes
+            extra_volumes.extend(profile_mounts)
+            # Profile runtime hints override tool config values
+            if profile_hints.get("start_command"):
+                start_command = profile_hints["start_command"]
+            if profile_hints.get("working_directory"):
+                working_directory = profile_hints["working_directory"]
+            if profile_hints.get("port_override"):
+                port_override = profile_hints["port_override"]
+            logger.info(
+                "Applied config profile %s to instance %s (env=%d, files=%d, mounts=%d)",
+                resolved.profile_name,
+                instance.id,
+                len(profile_env),
+                len(profile_files),
+                len(profile_mounts),
+            )
+        except ConfigProfileCycleError as exc:
+            logger.error("Cycle detected in config profile for instance %s: %s", instance.id, exc)
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=f"Config profile cycle detected: {exc}",
+            )
+    else:
+        logger.info("No config profile selected for instance %s", instance.id)
     
     # Write env file and config files
-    instance_dir = os.path.dirname(instance.compose_path)
     env_file_path = None
     
     if env_vars:
@@ -635,12 +757,6 @@ async def start_instance(
         write_config_files(instance_dir, config_files)
         logger.info("Wrote %d config files for instance %s", len(config_files), instance.id)
     
-    # Write config folder files
-    if config_folders:
-        folder_volumes = write_config_folder_files(instance_dir, config_folders, str(project_id))
-        extra_volumes.extend(folder_volumes)
-        logger.info("Wrote config folders with %d volume mounts for instance %s", len(folder_volumes), instance.id)
-    
     # Mount SSH key for clone-mode instances
     if instance.clone_mode == "clone":
         repo = await session.get(GitRepository, instance.repository_id)
@@ -958,7 +1074,30 @@ async def restart_instance(
         except Exception as exc:
             logger.warning("Failed to stop old tunnel for instance %s: %s", instance.id, exc)
 
+    # Re-apply stored config profile on restart
     if instance.compose_path and os.path.exists(instance.compose_path):
+        instance_dir = os.path.dirname(instance.compose_path)
+        if instance.selected_config_profile_id is not None:
+            try:
+                resolved = await resolve_profile(session, instance.selected_config_profile_id)
+                profile_env, profile_files, profile_mounts, profile_hints = apply_resolved_profile(
+                    instance_dir, resolved
+                )
+                # Write env file with resolved profile env vars
+                if profile_env:
+                    write_env_file(instance_dir, profile_env)
+                    logger.info(
+                        "Re-applied config profile %s on restart for instance %s",
+                        resolved.profile_name,
+                        instance.id,
+                    )
+            except ConfigProfileCycleError as exc:
+                logger.error(
+                    "Cycle detected in stored config profile for instance %s: %s",
+                    instance.id,
+                    exc,
+                )
+
         returncode, stdout, stderr = execute_compose_command(
             instance.compose_path, "restart"
         )
@@ -1483,6 +1622,7 @@ async def get_user_sessions(
             "url": instance.url,
             "clone_mode": instance.clone_mode,
             "branch": instance.branch,
+            "selected_config_profile_id": str(instance.selected_config_profile_id) if instance.selected_config_profile_id else None,
             "created_at": instance.created_at.isoformat() if instance.created_at else None,
         })
 

apps/api/src/auth/session.py

@@ -2,7 +2,7 @@ import hmac
 import hashlib
 import json
 import base64
-from datetime import UTC, datetime, timedelta
+from datetime import datetime, timedelta, timezone
 from typing import Any
 
 from src.config import Settings
@@ -23,7 +23,7 @@ def create_session_cookie(*, settings: Settings, user_id: str) -> str:
     """Create a signed session cookie value."""
     payload = {
         "user_id": user_id,
-        "exp": int((datetime.now(UTC) + timedelta(hours=settings.session_ttl_hours)).timestamp()),
+        "exp": int((datetime.now(timezone.utc) + timedelta(hours=settings.session_ttl_hours)).timestamp()),
     }
     
     header = _base64url_encode(json.dumps({"alg": "HS256", "typ": "session"}).encode())
@@ -65,7 +65,7 @@ def decode_session_cookie(*, settings: Settings, cookie_value: str) -> dict[str,
     payload = json.loads(payload_bytes)
     
     # Check expiry
-    if payload.get("exp", 0) < int(datetime.now(UTC).timestamp()):
+    if payload.get("exp", 0) < int(datetime.now(timezone.utc).timestamp()):
         raise ValueError("session expired")
     
     return payload

apps/api/src/main.py

@@ -18,6 +18,7 @@ from src.api.ssh_keys import router as ssh_keys_router
 from src.api.terminal import router as terminal_router
 from src.api.instance_proxy import router as instance_proxy_router
 from src.api.config_folders import router as config_folders_router
+from src.api.config_profiles import router as config_profiles_router
 from src.api.tool_configs import router as tool_configs_router
 from src.api.tool_instances import router as tool_instances_router
 from src.api.tool_instances import sessions_router
@@ -125,6 +126,7 @@ app.include_router(git_repositories_router)
 app.include_router(user_config_router)
 app.include_router(tool_types_router)
 app.include_router(config_folders_router)
+app.include_router(config_profiles_router)
 app.include_router(tool_instances_router)
 app.include_router(tool_configs_router)
 app.include_router(sessions_router)

apps/api/src/models/__init__.py

@@ -1,5 +1,6 @@
 from src.models.base import Base
 from src.models.config_folder import ConfigFolder
+from src.models.config_profile import ConfigProfile, ConfigProfileInclude
 from src.models.git_repository import GitRepository
 from src.models.project import Project
 from src.models.ssh_key import SSHKey
@@ -8,4 +9,4 @@ from src.models.tool_type import ToolType
 from src.models.user import User
 from src.models.user_config import UserConfig
 
-__all__ = ["Base", "ConfigFolder", "GitRepository", "Project", "SSHKey", "ToolInstance", "ToolType", "User", "UserConfig"]
+__all__ = ["Base", "ConfigFolder", "ConfigProfile", "ConfigProfileInclude", "GitRepository", "Project", "SSHKey", "ToolInstance", "ToolType", "User", "UserConfig"]

apps/api/src/models/config_profile.py

@@ -0,0 +1,74 @@
+import uuid
+from typing import TYPE_CHECKING
+
+from sqlalchemy import ForeignKey, JSON, Integer, String, Text, Boolean
+from sqlalchemy import Uuid as UUID
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from src.models.base import Base, TimestampMixin, UUIDPrimaryKeyMixin
+
+if TYPE_CHECKING:
+    from src.models.project import Project
+    from src.models.tool_type import ToolType
+    from src.models.user import User
+
+
+class ConfigProfile(UUIDPrimaryKeyMixin, TimestampMixin, Base):
+    __tablename__ = "config_profiles"
+
+    user_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(), ForeignKey("users.id", ondelete="CASCADE"), nullable=False
+    )
+    name: Mapped[str] = mapped_column(String(255), nullable=False)
+    description: Mapped[str | None] = mapped_column(Text, nullable=True)
+    project_id: Mapped[uuid.UUID | None] = mapped_column(
+        UUID(), ForeignKey("projects.id", ondelete="CASCADE"), nullable=True
+    )
+    tool_type_id: Mapped[uuid.UUID | None] = mapped_column(
+        UUID(), ForeignKey("tool_types.id", ondelete="CASCADE"), nullable=True
+    )
+    env_vars: Mapped[dict] = mapped_column(
+        JSON, default=dict, nullable=False
+    )  # {"VAR_NAME": "value", ...}
+    runtime_hints: Mapped[dict] = mapped_column(
+        JSON, default=dict, nullable=False
+    )  # {"start_command": "...", "working_dir": "...", ...}
+    mounts: Mapped[list] = mapped_column(
+        JSON, default=list, nullable=False
+    )  # [{"target": "/path", "mode": "rw", "files": {"rel/path": "content"}}, ...]
+    files: Mapped[dict] = mapped_column(
+        JSON, default=dict, nullable=False
+    )  # {"rel/path": "content", ...}
+    is_default: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
+
+    user: Mapped["User"] = relationship()
+    project: Mapped["Project | None"] = relationship()
+    tool_type: Mapped["ToolType | None"] = relationship()
+    includes: Mapped[list["ConfigProfileInclude"]] = relationship(
+        "ConfigProfileInclude",
+        foreign_keys="ConfigProfileInclude.profile_id",
+        order_by="ConfigProfileInclude.order_index",
+        cascade="all, delete-orphan",
+    )
+
+
+class ConfigProfileInclude(UUIDPrimaryKeyMixin, TimestampMixin, Base):
+    __tablename__ = "config_profile_includes"
+
+    profile_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(), ForeignKey("config_profiles.id", ondelete="CASCADE"), nullable=False
+    )
+    included_profile_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(), ForeignKey("config_profiles.id", ondelete="CASCADE"), nullable=False
+    )
+    order_index: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+
+    profile: Mapped["ConfigProfile"] = relationship(
+        "ConfigProfile",
+        foreign_keys=[profile_id],
+        back_populates="includes",
+    )
+    included_profile: Mapped["ConfigProfile"] = relationship(
+        "ConfigProfile",
+        foreign_keys=[included_profile_id],
+    )

apps/api/src/models/tool_instance.py

@@ -9,6 +9,7 @@ from sqlalchemy.orm import Mapped, mapped_column, relationship
 from src.models.base import Base, TimestampMixin, UUIDPrimaryKeyMixin
 
 if TYPE_CHECKING:
+    from src.models.config_profile import ConfigProfile
     from src.models.git_repository import GitRepository
     from src.models.project import Project
     from src.models.tool_type import ToolType
@@ -71,8 +72,12 @@ class ToolInstance(UUIDPrimaryKeyMixin, TimestampMixin, Base):
     branch: Mapped[str | None] = mapped_column(
         String(255), nullable=True, default="main"
     )
+    selected_config_profile_id: Mapped[uuid.UUID | None] = mapped_column(
+        UUID(), ForeignKey("config_profiles.id", ondelete="SET NULL"), nullable=True
+    )
 
     tool_type: Mapped["ToolType"] = relationship()
     repository: Mapped["GitRepository"] = relationship()
     project: Mapped["Project"] = relationship()
     owner: Mapped["User"] = relationship()
+    selected_config_profile: Mapped["ConfigProfile | None"] = relationship()

apps/api/src/services/config_profile_resolver.py

@@ -0,0 +1,453 @@
+"""Config profile resolver service.
+
+Provides recursive ordered include resolution with deterministic merge rules
+and cycle protection.
+"""
+
+import logging
+import uuid
+from dataclasses import dataclass, field
+from typing import Any
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from src.models.config_profile import ConfigProfile, ConfigProfileInclude
+
+logger = logging.getLogger(__name__)
+
+
+class ConfigProfileCycleError(Exception):
+    """Raised when a cycle is detected in profile includes."""
+
+    pass
+
+
+class ConfigProfileNotFoundError(Exception):
+    """Raised when a referenced profile is not found."""
+
+    pass
+
+
+@dataclass
+class ResolvedMount:
+    """A resolved mount with merged files and final mode."""
+
+    target: str
+    mode: str
+    files: dict[str, str] = field(default_factory=dict)
+    overridden_files: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass
+class ResolvedProfile:
+    """The fully resolved output of a config profile."""
+
+    profile_id: uuid.UUID
+    profile_name: str
+    env_vars: dict[str, str] = field(default_factory=dict)
+    runtime_hints: dict[str, Any] = field(default_factory=dict)
+    mounts: dict[str, ResolvedMount] = field(default_factory=dict)
+    files: dict[str, str] = field(default_factory=dict)
+    env_overrides: dict[str, str] = field(default_factory=dict)
+    hint_overrides: dict[str, str] = field(default_factory=dict)
+    file_overrides: dict[str, str] = field(default_factory=dict)
+    mount_overrides: dict[str, str] = field(default_factory=dict)
+    included_profiles: list[dict[str, Any]] = field(default_factory=list)
+
+
+def _detect_cycle(profile_id: uuid.UUID, visited: set[uuid.UUID], path: list[uuid.UUID]) -> bool:
+    """Detect if adding profile_id to path would create a cycle.
+
+    Args:
+        profile_id: The profile ID to check.
+        visited: Set of already-visited profile IDs in current resolution.
+        path: Current resolution path for error reporting.
+
+    Returns:
+        True if a cycle would be created.
+    """
+    if profile_id in visited:
+        return True
+    return False
+
+
+def _merge_env_vars(
+    base: dict[str, str],
+    overlay: dict[str, str],
+    overrides: dict[str, str],
+    source_name: str,
+) -> dict[str, str]:
+    """Merge env vars, tracking overrides.
+
+    Later values replace earlier values.
+    """
+    result = dict(base)
+    for key, value in overlay.items():
+        if key in result and result[key] != value:
+            overrides[key] = source_name
+        result[key] = value
+    return result
+
+
+def _merge_runtime_hints(
+    base: dict[str, Any],
+    overlay: dict[str, Any],
+    overrides: dict[str, str],
+    source_name: str,
+) -> dict[str, Any]:
+    """Merge runtime hints, tracking overrides.
+
+    Later values replace earlier values.
+    """
+    result = dict(base)
+    for key, value in overlay.items():
+        if key in result and result[key] != value:
+            overrides[key] = source_name
+        result[key] = value
+    return result
+
+
+def _merge_files(
+    base: dict[str, str],
+    overlay: dict[str, str],
+    overrides: dict[str, str],
+    source_name: str,
+) -> dict[str, str]:
+    """Merge file maps, tracking overrides.
+
+    Later relative file paths win.
+    """
+    result = dict(base)
+    for path, content in overlay.items():
+        if path in result and result[path] != content:
+            overrides[path] = source_name
+        result[path] = content
+    return result
+
+
+def _merge_mounts(
+    base: dict[str, ResolvedMount],
+    overlay: list[dict[str, Any]],
+    overrides: dict[str, str],
+    source_name: str,
+) -> dict[str, ResolvedMount]:
+    """Merge mounts, tracking overrides.
+
+    Mounts with the same target path have their file maps merged and later
+    relative file paths win. Mode conflicts: later layer wins.
+    """
+    result = dict(base)
+    for mount_data in overlay:
+        target = mount_data["target"]
+        mode = mount_data.get("mode", "rw")
+        files = mount_data.get("files", {})
+
+        if target in result:
+            existing = result[target]
+            merged_files = dict(existing.files)
+            file_overrides = dict(existing.overridden_files)
+            for rel_path, content in files.items():
+                if rel_path in merged_files and merged_files[rel_path] != content:
+                    file_overrides[rel_path] = source_name
+                merged_files[rel_path] = content
+            if existing.mode != mode:
+                overrides[target] = source_name
+            result[target] = ResolvedMount(
+                target=target,
+                mode=mode,
+                files=merged_files,
+                overridden_files=file_overrides,
+            )
+        else:
+            result[target] = ResolvedMount(
+                target=target,
+                mode=mode,
+                files=dict(files),
+            )
+    return result
+
+
+async def _resolve_profile_recursive(
+    session: AsyncSession,
+    profile_id: uuid.UUID,
+    visited: set[uuid.UUID],
+    path: list[uuid.UUID],
+) -> ResolvedProfile:
+    """Recursively resolve a profile and its includes.
+
+    Args:
+        session: Database session.
+        profile_id: Profile ID to resolve.
+        visited: Set of already-visited profile IDs in current resolution chain.
+        path: Current resolution path for error reporting.
+
+    Returns:
+        ResolvedProfile with all includes merged.
+
+    Raises:
+        ConfigProfileCycleError: If a cycle is detected.
+        ConfigProfileNotFoundError: If the profile is not found.
+    """
+    if _detect_cycle(profile_id, visited, path):
+        cycle_path = " -> ".join(str(p) for p in path + [profile_id])
+        raise ConfigProfileCycleError(f"Cycle detected in profile includes: {cycle_path}")
+
+    profile = await session.get(ConfigProfile, profile_id)
+    if profile is None:
+        raise ConfigProfileNotFoundError(f"Config profile not found: {profile_id}")
+
+    new_visited = visited | {profile_id}
+    new_path = path + [profile_id]
+
+    result = ResolvedProfile(
+        profile_id=profile.id,
+        profile_name=profile.name,
+    )
+
+    # Resolve includes in order
+    include_query = (
+        select(ConfigProfileInclude)
+        .where(ConfigProfileInclude.profile_id == profile_id)
+        .order_by(ConfigProfileInclude.order_index)
+    )
+    include_result = await session.execute(include_query)
+    includes = include_result.scalars().all()
+
+    for include in includes:
+        included = await _resolve_profile_recursive(
+            session, include.included_profile_id, new_visited, new_path
+        )
+        result.included_profiles.append({
+            "id": str(included.profile_id),
+            "name": included.profile_name,
+        })
+
+        result.env_vars = _merge_env_vars(
+            result.env_vars, included.env_vars, result.env_overrides, included.profile_name
+        )
+        result.runtime_hints = _merge_runtime_hints(
+            result.runtime_hints,
+            included.runtime_hints,
+            result.hint_overrides,
+            included.profile_name,
+        )
+        result.files = _merge_files(
+            result.files, included.files, result.file_overrides, included.profile_name
+        )
+        result.mounts = _merge_mounts(
+            result.mounts,
+            [
+                {"target": m.target, "mode": m.mode, "files": m.files}
+                for m in included.mounts.values()
+            ],
+            result.mount_overrides,
+            included.profile_name,
+        )
+
+    # Apply the profile's own settings (selected profile overrides includes)
+    result.env_vars = _merge_env_vars(
+        result.env_vars,
+        profile.env_vars or {},
+        result.env_overrides,
+        profile.name,
+    )
+    result.runtime_hints = _merge_runtime_hints(
+        result.runtime_hints,
+        profile.runtime_hints or {},
+        result.hint_overrides,
+        profile.name,
+    )
+    result.files = _merge_files(
+        result.files,
+        profile.files or {},
+        result.file_overrides,
+        profile.name,
+    )
+    result.mounts = _merge_mounts(
+        result.mounts,
+        profile.mounts or [],
+        result.mount_overrides,
+        profile.name,
+    )
+
+    return result
+
+
+async def resolve_profile(
+    session: AsyncSession,
+    profile_id: uuid.UUID,
+) -> ResolvedProfile:
+    """Resolve a config profile with all includes.
+
+    Args:
+        session: Database session.
+        profile_id: Profile ID to resolve.
+
+    Returns:
+        ResolvedProfile with merged env vars, runtime hints, mounts, and files.
+
+    Raises:
+        ConfigProfileCycleError: If a cycle is detected in includes.
+        ConfigProfileNotFoundError: If the profile is not found.
+    """
+    return await _resolve_profile_recursive(session, profile_id, set(), [])
+
+
+async def check_include_cycle(
+    session: AsyncSession,
+    profile_id: uuid.UUID,
+    new_include_id: uuid.UUID | None = None,
+) -> list[uuid.UUID] | None:
+    """Check if adding an include would create a cycle.
+
+    Used at save time to validate include relationships before persisting.
+
+    Args:
+        session: Database session.
+        profile_id: The profile that would receive the new include.
+        new_include_id: Optional new profile to include. If None, checks existing includes.
+
+    Returns:
+        The cycle path as a list of UUIDs if a cycle exists, otherwise None.
+    """
+
+    async def _check_from(
+        current_id: uuid.UUID,
+        target_id: uuid.UUID,
+        visited: set[uuid.UUID],
+        path: list[uuid.UUID],
+    ) -> list[uuid.UUID] | None:
+        if current_id in visited:
+            if current_id == target_id:
+                return path + [current_id]
+            return None
+        if current_id == target_id and path:
+            return path + [current_id]
+
+        new_visited = visited | {current_id}
+        new_path = path + [current_id]
+
+        include_query = (
+            select(ConfigProfileInclude)
+            .where(ConfigProfileInclude.profile_id == current_id)
+            .order_by(ConfigProfileInclude.order_index)
+        )
+        include_result = await session.execute(include_query)
+        includes = include_result.scalars().all()
+
+        for include in includes:
+            cycle = await _check_from(
+                include.included_profile_id, target_id, new_visited, new_path
+            )
+            if cycle is not None:
+                return cycle
+        return None
+
+    # Check if new_include_id can reach profile_id (would create cycle)
+    if new_include_id is not None:
+        cycle = await _check_from(new_include_id, profile_id, set(), [])
+        if cycle is not None:
+            return cycle
+
+    # Also check existing includes for cycles
+    cycle = await _check_from(profile_id, profile_id, set(), [])
+    if cycle is not None and len(cycle) > 1:
+        return cycle
+
+    return None
+
+
+def apply_resolved_profile(
+    instance_dir: str,
+    resolved: ResolvedProfile,
+) -> tuple[dict[str, str], dict[str, str], list[dict], dict[str, Any]]:
+    """Apply a resolved profile to an instance directory.
+
+    Stages files, writes env vars, and prepares mount volumes.
+
+    Args:
+        instance_dir: Path to the instance directory.
+        resolved: The resolved profile.
+
+    Returns:
+        Tuple of (env_vars, files, volume_mounts, runtime_hints).
+        env_vars: Merged environment variables.
+        files: Relative file paths to content for the instance.
+        volume_mounts: List of Docker volume mount dicts.
+        runtime_hints: Extracted runtime hints.
+    """
+    from pathlib import Path
+
+    instance_path = Path(instance_dir)
+    env_vars = dict(resolved.env_vars)
+    files = dict(resolved.files)
+    volume_mounts = []
+
+    # Write profile files to instance directory
+    for file_path, content in files.items():
+        full_path = instance_path / file_path
+        try:
+            full_path.resolve().relative_to(instance_path.resolve())
+        except ValueError:
+            logger.warning("Profile file path escapes instance directory: %s", file_path)
+            continue
+        full_path.parent.mkdir(parents=True, exist_ok=True)
+        full_path.write_text(content)
+
+    # Stage mount files and prepare volume mounts
+    for mount in resolved.mounts.values():
+        mount_dir = instance_path / "mounts" / mount.target.lstrip("/").replace("/", "_")
+        mount_dir.mkdir(parents=True, exist_ok=True)
+
+        for file_path, content in mount.files.items():
+            full_path = mount_dir / file_path
+            try:
+                full_path.resolve().relative_to(mount_dir.resolve())
+            except ValueError:
+                logger.warning("Mount file path escapes mount directory: %s", file_path)
+                continue
+            full_path.parent.mkdir(parents=True, exist_ok=True)
+            full_path.write_text(content)
+
+        volume_mounts.append({
+            "source": str(mount_dir),
+            "target": mount.target,
+            "type": "bind",
+        })
+
+    return env_vars, files, volume_mounts, resolved.runtime_hints
+
+
+def resolved_profile_to_dict(resolved: ResolvedProfile) -> dict[str, Any]:
+    """Convert a ResolvedProfile to a plain dict for serialization.
+
+    Args:
+        resolved: The resolved profile.
+
+    Returns:
+        Dict with env_vars, runtime_hints, mounts, files, and metadata.
+    """
+    return {
+        "profile_id": str(resolved.profile_id),
+        "profile_name": resolved.profile_name,
+        "env_vars": resolved.env_vars,
+        "runtime_hints": resolved.runtime_hints,
+        "mounts": [
+            {
+                "target": m.target,
+                "mode": m.mode,
+                "files": m.files,
+                "overridden_files": m.overridden_files,
+            }
+            for m in resolved.mounts.values()
+        ],
+        "files": resolved.files,
+        "overrides": {
+            "env_vars": resolved.env_overrides,
+            "runtime_hints": resolved.hint_overrides,
+            "files": resolved.file_overrides,
+            "mounts": resolved.mount_overrides,
+        },
+        "included_profiles": resolved.included_profiles,
+    }

apps/api/src/services/docker.py

@@ -92,59 +92,6 @@ def write_config_files(instance_dir: str, files: dict[str, str]) -> None:
         full_path.write_text(content)
 
 
-def write_config_folder_files(instance_dir: str, folders: list, project_id: str | None = None) -> list[dict]:
-    """Write config folder files to the instance directory and return volume mounts.
-
-    Args:
-        instance_dir: Path to instance directory
-        folders: List of ConfigFolder objects
-        project_id: Optional project ID for applying overrides
-
-    Returns:
-        List of volume mount dicts [{"source": "...", "target": "...", "type": "..."}]
-    """
-    instance_path = Path(instance_dir)
-    volume_mounts = []
-
-    for folder in folders:
-        # Determine mount path (with project override if applicable)
-        mount_path = folder.mount_path
-        files = folder.files.copy()
-        
-        if project_id and folder.project_overrides:
-            override = folder.project_overrides.get(str(project_id))
-            if override:
-                if override.get("mount_path"):
-                    mount_path = override["mount_path"]
-                if override.get("files"):
-                    files.update(override["files"])
-        
-        # Write files to instance directory
-        folder_dir = instance_path / "volumes" / folder.name
-        folder_dir.mkdir(parents=True, exist_ok=True)
-        
-        for file_path, content in files.items():
-            # Security: ensure path doesn't escape folder_dir
-            full_path = folder_dir / file_path
-            try:
-                full_path.resolve().relative_to(folder_dir.resolve())
-            except ValueError:
-                logger.warning("Config folder file path escapes directory: %s", file_path)
-                continue
-            
-            full_path.parent.mkdir(parents=True, exist_ok=True)
-            full_path.write_text(content)
-        
-        # Add volume mount
-        volume_mounts.append({
-            "source": str(folder_dir),
-            "target": mount_path,
-            "type": "bind",
-        })
-    
-    return volume_mounts
-
-
 def execute_compose_command(
     compose_path: str, action: str, timeout: int = 60, env_file: str | None = None
 ) -> tuple[int, str, str]: