fix: mobile terminal back and X buttons navigate to /sessions

Terminal sessions are opened in a new tab via window.open with
noopener,noreferrer. In a new tab, window.history has no previous
entry, so navigate(-1) silently does nothing. Both the back arrow
and the X button in the mobile terminal overlay called navigate(-1),
which made them appear broken.

Change both buttons to navigate('/sessions') so they always exit
to a sensible page regardless of how the terminal was opened.

Quality gates: tsc --noEmit (pass), build (pass)

.atl/.skill-registry.cache.json

@@ -1,3 +1,3 @@
 {
-  "fingerprint": "c324de9e9faf30231900c691aca5f3a07c7db099"
+  "fingerprint": "c36b11ec5edebc02aa51b1113a7a11dc2559e812"
 }

.atl/skill-registry.md

@@ -2,11 +2,12 @@
 
 <!-- Auto-generated by gentle-pi extensions/skill-registry.ts. Run /skill-registry:refresh to regenerate. -->
 
-Last updated: 2026-05-27
+Last updated: 2026-06-02
 
 ## Sources scanned
 
 - .opencode/skills
+- .claude/skills
 - /home/alex/.config/opencode/skills
 
 ## Contract
@@ -20,11 +21,11 @@ Last updated: 2026-05-27
 | Skill | Trigger / description | Scope | Path |
 | --- | --- | --- | --- |
 | `auto-commit` | Use when you are making multiple edits or completing significant work in a git repository to automatically create commits | user | `/home/alex/.config/opencode/skills/auto-commit/SKILL.md` |
-| `openspec` | Use OpenSpec as the source of truth for planning, implementation, verification, and archive discipline. | user | `/home/alex/.config/opencode/skills/openspec/SKILL.md` |
 | `openspec-apply-change` | Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks. | project | `/home/alex/projects/headquarter/.opencode/skills/openspec-apply-change/SKILL.md` |
 | `openspec-archive-change` | Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete. | project | `/home/alex/projects/headquarter/.opencode/skills/openspec-archive-change/SKILL.md` |
 | `openspec-explore` | Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change. | project | `/home/alex/projects/headquarter/.opencode/skills/openspec-explore/SKILL.md` |
 | `openspec-propose` | Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation. | project | `/home/alex/projects/headquarter/.opencode/skills/openspec-propose/SKILL.md` |
+| `sift-backlog` | Triage and organize backlog tasks into actionable plans. Use when asked to review the backlog, prioritize tasks, create plans from backlog items, or move tasks from backlog to open status. Handles the full workflow of listing backlog tasks, grouping related tasks into plans, setting priorities and dependencies, activating plans, and changing task status from backlog to open. | project | `/home/alex/projects/headquarter/.claude/skills/sift-backlog/SKILL.md` |
 
 ## Loading protocol
 

AGENTS.md

@@ -4,6 +4,10 @@
 
 OpenSpec is the source of truth. Superpowers is the default workflow. Keep changes small, scoped, and verified.
 
+## Communication
+
+All agent output, code comments, commit messages, documentation, and artifacts must be in **English** unless the user explicitly requests another language.
+
 ## Priority order
 
 1. Current user instruction
@@ -71,6 +75,7 @@ Do not:
 * Introduce new dependencies without clear justification.
 * Treat existing code as more authoritative than OpenSpec for intended behavior.
 * Decide product behavior silently when the spec is unclear.
+* Run `docker compose` commands (build, up, down, etc.) without explicit user approval and proper isolation (e.g., feature branches, separate worktrees, or staged rollouts). Docker Compose operations are deployment-level changes that can affect running services, shared volumes, and network state. Always ask first.
 
 If scope must change, propose an OpenSpec update first.
 

apps/api/.dockerignore

@@ -0,0 +1,42 @@
+# Python cache
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Test artifacts
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Git
+.git/
+.gitignore
+
+# Local env files
+.env
+.env.local
+
+# Alembic cache
+alembic/versions/__pycache__/
+
+# Pi lens cache
+.pi-lens/
+
+# Documentation
+docs/
+*.md
+
+# Scripts not needed in container
+scripts/

apps/api/Dockerfile

@@ -50,8 +50,8 @@ ENV PATH=/root/.local/bin:$PATH
 # Copy application code
 COPY --chown=appuser:appgroup . .
 
-# Create directories for repo and instance storage
-RUN mkdir -p /data/repos /data/instances && chown -R appuser:appgroup /data
+# Create directories for repo, instance, and workspace storage
+RUN mkdir -p /data/repos /data/instances /data/working-copies && chown -R appuser:appgroup /data
 
 # Copy wait-for-db script
 COPY wait-for-db.sh /usr/local/bin/wait-for-db.sh

apps/api/alembic/versions/0013_add_config_profiles.py

@@ -0,0 +1,204 @@
+"""add config profiles, includes, mounts, and tool instance profile selection
+
+Revision ID: 0013_add_config_profiles
+Revises: 0012_default_port_req
+Create Date: 2026-05-24 12:00:00.000000
+
+"""
+from collections.abc import Sequence
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision: str = "0013_add_config_profiles"
+down_revision: str | None = "0012_default_port_req"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def _table_exists(table_name: str) -> bool:
+    return sa.inspect(op.get_bind()).has_table(table_name)
+
+
+def _column_exists(table_name: str, column_name: str) -> bool:
+    if not _table_exists(table_name):
+        return False
+    return column_name in {
+        column["name"] for column in sa.inspect(op.get_bind()).get_columns(table_name)
+    }
+
+
+def _index_exists(table_name: str, index_name: str) -> bool:
+    if not _table_exists(table_name):
+        return False
+    return index_name in {
+        index["name"] for index in sa.inspect(op.get_bind()).get_indexes(table_name)
+    }
+
+
+def _foreign_key_exists(
+    table_name: str,
+    constrained_columns: list[str],
+    referred_table: str,
+) -> bool:
+    if not _table_exists(table_name):
+        return False
+    for foreign_key in sa.inspect(op.get_bind()).get_foreign_keys(table_name):
+        if (
+            foreign_key.get("constrained_columns") == constrained_columns
+            and foreign_key.get("referred_table") == referred_table
+        ):
+            return True
+    return False
+
+
+def upgrade() -> None:
+    # Earlier branches may already have created config_profiles. Keep this
+    # migration defensive so databases can converge onto the current graph.
+    if not _table_exists("config_profiles"):
+        op.create_table(
+            "config_profiles",
+            sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False),
+            sa.Column("user_id", postgresql.UUID(as_uuid=True), nullable=False),
+            sa.Column("name", sa.String(length=255), nullable=False),
+            sa.Column("description", sa.Text(), nullable=True),
+            sa.Column(
+                "created_at",
+                sa.DateTime(timezone=True),
+                server_default=sa.text("NOW()"),
+                nullable=False,
+            ),
+            sa.Column(
+                "updated_at",
+                sa.DateTime(timezone=True),
+                server_default=sa.text("NOW()"),
+                nullable=False,
+            ),
+            sa.ForeignKeyConstraint(["user_id"], ["users.id"], ondelete="CASCADE"),
+            sa.PrimaryKeyConstraint("id"),
+            sa.UniqueConstraint(
+                "user_id", "name", name="uq_config_profiles_user_name"
+            ),
+        )
+    if not _index_exists("config_profiles", "idx_config_profiles_user"):
+        op.create_index("idx_config_profiles_user", "config_profiles", ["user_id"])
+
+    if not _table_exists("config_includes"):
+        op.create_table(
+            "config_includes",
+            sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False),
+            sa.Column("profile_id", postgresql.UUID(as_uuid=True), nullable=False),
+            sa.Column(
+                "included_profile_id", postgresql.UUID(as_uuid=True), nullable=False
+            ),
+            sa.Column("order_index", sa.Integer(), nullable=False, server_default="0"),
+            sa.Column(
+                "created_at",
+                sa.DateTime(timezone=True),
+                server_default=sa.text("NOW()"),
+                nullable=False,
+            ),
+            sa.Column(
+                "updated_at",
+                sa.DateTime(timezone=True),
+                server_default=sa.text("NOW()"),
+                nullable=False,
+            ),
+            sa.ForeignKeyConstraint(
+                ["profile_id"], ["config_profiles.id"], ondelete="CASCADE"
+            ),
+            sa.ForeignKeyConstraint(
+                ["included_profile_id"],
+                ["config_profiles.id"],
+                ondelete="CASCADE",
+            ),
+            sa.PrimaryKeyConstraint("id"),
+            sa.UniqueConstraint(
+                "profile_id", "included_profile_id", name="uq_config_includes_pair"
+            ),
+        )
+    if not _index_exists("config_includes", "idx_config_includes_profile"):
+        op.create_index("idx_config_includes_profile", "config_includes", ["profile_id"])
+    if not _index_exists("config_includes", "idx_config_includes_included"):
+        op.create_index(
+            "idx_config_includes_included", "config_includes", ["included_profile_id"]
+        )
+
+    if not _table_exists("config_mounts"):
+        op.create_table(
+            "config_mounts",
+            sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False),
+            sa.Column("profile_id", postgresql.UUID(as_uuid=True), nullable=False),
+            sa.Column("mount_path", sa.String(length=1024), nullable=False),
+            sa.Column("content", sa.Text(), nullable=True),
+            sa.Column("source_profile_id", postgresql.UUID(as_uuid=True), nullable=True),
+            sa.Column("order_index", sa.Integer(), nullable=False, server_default="0"),
+            sa.Column(
+                "created_at",
+                sa.DateTime(timezone=True),
+                server_default=sa.text("NOW()"),
+                nullable=False,
+            ),
+            sa.Column(
+                "updated_at",
+                sa.DateTime(timezone=True),
+                server_default=sa.text("NOW()"),
+                nullable=False,
+            ),
+            sa.ForeignKeyConstraint(
+                ["profile_id"], ["config_profiles.id"], ondelete="CASCADE"
+            ),
+            sa.ForeignKeyConstraint(
+                ["source_profile_id"], ["config_profiles.id"], ondelete="SET NULL"
+            ),
+            sa.PrimaryKeyConstraint("id"),
+        )
+    if not _index_exists("config_mounts", "idx_config_mounts_profile"):
+        op.create_index("idx_config_mounts_profile", "config_mounts", ["profile_id"])
+
+    if not _column_exists("tool_instances", "selected_profile_id"):
+        op.add_column(
+            "tool_instances",
+            sa.Column("selected_profile_id", postgresql.UUID(as_uuid=True), nullable=True),
+        )
+    if not _foreign_key_exists(
+        "tool_instances", ["selected_profile_id"], "config_profiles"
+    ):
+        op.create_foreign_key(
+            "fk_tool_instances_selected_profile",
+            "tool_instances",
+            "config_profiles",
+            ["selected_profile_id"],
+            ["id"],
+            ondelete="SET NULL",
+        )
+    if not _index_exists("tool_instances", "idx_tool_instances_selected_profile"):
+        op.create_index(
+            "idx_tool_instances_selected_profile",
+            "tool_instances",
+            ["selected_profile_id"],
+        )
+
+
+def downgrade() -> None:
+    # Remove selected_profile_id from tool_instances
+    op.drop_index("idx_tool_instances_selected_profile", table_name="tool_instances")
+    op.drop_constraint(
+        "fk_tool_instances_selected_profile", "tool_instances", type_="foreignkey"
+    )
+    op.drop_column("tool_instances", "selected_profile_id")
+
+    # Drop config_mounts
+    op.drop_index("idx_config_mounts_profile", table_name="config_mounts")
+    op.drop_table("config_mounts")
+
+    # Drop config_includes
+    op.drop_index("idx_config_includes_included", table_name="config_includes")
+    op.drop_index("idx_config_includes_profile", table_name="config_includes")
+    op.drop_table("config_includes")
+
+    # Drop config_profiles
+    op.drop_index("idx_config_profiles_user", table_name="config_profiles")
+    op.drop_table("config_profiles")

apps/api/alembic/versions/0014_add_profile_resolver_fields.py

@@ -0,0 +1,180 @@
+"""add profile resolver fields to config profiles and mounts
+
+Revision ID: 0014_add_profile_resolver_fields
+Revises: 0013_add_config_profiles
+Create Date: 2026-05-24 14:00:00.000000
+
+"""
+from collections.abc import Sequence
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision: str = "0014_add_profile_resolver_fields"
+down_revision: str | None = "0013_add_config_profiles"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def _table_exists(table_name: str) -> bool:
+    return sa.inspect(op.get_bind()).has_table(table_name)
+
+
+def _column_exists(table_name: str, column_name: str) -> bool:
+    if not _table_exists(table_name):
+        return False
+    return column_name in {
+        column["name"] for column in sa.inspect(op.get_bind()).get_columns(table_name)
+    }
+
+
+def _index_exists(table_name: str, index_name: str) -> bool:
+    if not _table_exists(table_name):
+        return False
+    return index_name in {
+        index["name"] for index in sa.inspect(op.get_bind()).get_indexes(table_name)
+    }
+
+
+def _foreign_key_exists(
+    table_name: str,
+    constrained_columns: list[str],
+    referred_table: str,
+) -> bool:
+    if not _table_exists(table_name):
+        return False
+    for foreign_key in sa.inspect(op.get_bind()).get_foreign_keys(table_name):
+        if (
+            foreign_key.get("constrained_columns") == constrained_columns
+            and foreign_key.get("referred_table") == referred_table
+        ):
+            return True
+    return False
+
+
+def _foreign_key_names_for_column(table_name: str, column_name: str) -> list[str]:
+    if not _table_exists(table_name):
+        return []
+    names: list[str] = []
+    for foreign_key in sa.inspect(op.get_bind()).get_foreign_keys(table_name):
+        if column_name in foreign_key.get("constrained_columns", []):
+            name = foreign_key.get("name")
+            if name:
+                names.append(name)
+    return names
+
+
+def upgrade() -> None:
+    if not _column_exists("config_profiles", "project_id"):
+        op.add_column(
+            "config_profiles",
+            sa.Column("project_id", postgresql.UUID(as_uuid=True), nullable=True),
+        )
+    if not _column_exists("config_profiles", "tool_type_id"):
+        op.add_column(
+            "config_profiles",
+            sa.Column("tool_type_id", postgresql.UUID(as_uuid=True), nullable=True),
+        )
+    if not _column_exists("config_profiles", "environment_variables"):
+        op.add_column(
+            "config_profiles",
+            sa.Column("environment_variables", sa.JSON(), nullable=True),
+        )
+    if not _column_exists("config_profiles", "start_command"):
+        op.add_column(
+            "config_profiles",
+            sa.Column("start_command", sa.Text(), nullable=True),
+        )
+    if not _column_exists("config_profiles", "working_directory"):
+        op.add_column(
+            "config_profiles",
+            sa.Column("working_directory", sa.Text(), nullable=True),
+        )
+    if not _column_exists("config_profiles", "port"):
+        op.add_column("config_profiles", sa.Column("port", sa.Integer(), nullable=True))
+    if not _column_exists("config_profiles", "is_default"):
+        op.add_column(
+            "config_profiles",
+            sa.Column("is_default", sa.Boolean(), nullable=False, server_default="false"),
+        )
+
+    if not _foreign_key_exists("config_profiles", ["project_id"], "projects"):
+        op.create_foreign_key(
+            "fk_config_profiles_project",
+            "config_profiles",
+            "projects",
+            ["project_id"],
+            ["id"],
+            ondelete="CASCADE",
+        )
+    if not _foreign_key_exists("config_profiles", ["tool_type_id"], "tool_types"):
+        op.create_foreign_key(
+            "fk_config_profiles_tool_type",
+            "config_profiles",
+            "tool_types",
+            ["tool_type_id"],
+            ["id"],
+            ondelete="CASCADE",
+        )
+
+    if not _index_exists("config_profiles", "idx_config_profiles_project"):
+        op.create_index("idx_config_profiles_project", "config_profiles", ["project_id"])
+    if not _index_exists("config_profiles", "idx_config_profiles_tool_type"):
+        op.create_index(
+            "idx_config_profiles_tool_type", "config_profiles", ["tool_type_id"]
+        )
+
+    if _column_exists("config_mounts", "mount_path") and not _column_exists(
+        "config_mounts", "target_path"
+    ):
+        op.alter_column("config_mounts", "mount_path", new_column_name="target_path")
+    if not _column_exists("config_mounts", "mode"):
+        op.add_column(
+            "config_mounts",
+            sa.Column("mode", sa.String(length=10), nullable=False, server_default="rw"),
+        )
+    if not _column_exists("config_mounts", "files"):
+        op.add_column(
+            "config_mounts",
+            sa.Column("files", sa.JSON(), nullable=True),
+        )
+    for constraint_name in _foreign_key_names_for_column(
+        "config_mounts", "source_profile_id"
+    ):
+        op.drop_constraint(constraint_name, "config_mounts", type_="foreignkey")
+    if _column_exists("config_mounts", "content"):
+        op.drop_column("config_mounts", "content")
+    if _column_exists("config_mounts", "source_profile_id"):
+        op.drop_column("config_mounts", "source_profile_id")
+
+
+def downgrade() -> None:
+    # Restore config_mounts
+    op.add_column(
+        "config_mounts",
+        sa.Column("source_profile_id", postgresql.UUID(as_uuid=True), nullable=True),
+    )
+    op.add_column(
+        "config_mounts",
+        sa.Column("content", sa.Text(), nullable=True),
+    )
+    op.drop_column("config_mounts", "files")
+    op.drop_column("config_mounts", "mode")
+    op.alter_column("config_mounts", "target_path", new_column_name="mount_path")
+
+    # Restore config_profiles
+    op.drop_index("idx_config_profiles_tool_type", table_name="config_profiles")
+    op.drop_index("idx_config_profiles_project", table_name="config_profiles")
+    op.drop_constraint(
+        "fk_config_profiles_tool_type", "config_profiles", type_="foreignkey"
+    )
+    op.drop_constraint("fk_config_profiles_project", "config_profiles", type_="foreignkey")
+    op.drop_column("config_profiles", "is_default")
+    op.drop_column("config_profiles", "port")
+    op.drop_column("config_profiles", "working_directory")
+    op.drop_column("config_profiles", "start_command")
+    op.drop_column("config_profiles", "environment_variables")
+    op.drop_column("config_profiles", "tool_type_id")
+    op.drop_column("config_profiles", "project_id")

apps/api/alembic/versions/069d3da4dc9b_add_ssh_key_id_to_config_profiles.py

@@ -0,0 +1,32 @@
+"""add_ssh_key_id_to_config_profiles
+
+Revision ID: 069d3da4dc9b
+Revises: 2026_05_29_add_notifications_table
+Create Date: 2026-05-29 12:30:16.580532
+"""
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision = "069d3da4dc9b"
+down_revision = "2026_05_29_add_notifications_table"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "config_profiles",
+        sa.Column(
+            "ssh_key_id",
+            sa.Uuid(),
+            sa.ForeignKey("ssh_keys.id", ondelete="SET NULL"),
+            nullable=True,
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("config_profiles", "ssh_key_id")

apps/api/alembic/versions/2026_05_28_add_monitoring_tables.py

@@ -0,0 +1,122 @@
+"""add monitoring tables
+
+Revision ID: 2026_05_28_add_monitoring_tables
+Revises: 2026_05_28_drop_tool_configs_and_config_folders
+Create Date: 2026-05-28
+
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision: str = "2026_05_28_add_monitoring_tables"
+down_revision: str | None = "2026_05_28_drop_tool_configs_and_config_folders"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "instance_events",
+        sa.Column("id", sa.Uuid(), nullable=False),
+        sa.Column(
+            "instance_id",
+            sa.Uuid(),
+            nullable=False,
+        ),
+        sa.Column("event_type", sa.String(length=50), nullable=False),
+        sa.Column("status", sa.String(length=50), nullable=True),
+        sa.Column("message", sa.Text(), nullable=True),
+        sa.Column("created_by", sa.Uuid(), nullable=True),
+        sa.Column(
+            "metadata",
+            sa.JSON(),
+            nullable=False,
+            server_default="{}",
+        ),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+        sa.ForeignKeyConstraint(
+            ["instance_id"],
+            ["tool_instances.id"],
+            ondelete="CASCADE",
+        ),
+        sa.ForeignKeyConstraint(
+            ["created_by"],
+            ["users.id"],
+            ondelete="SET NULL",
+        ),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(
+        "idx_instance_events_instance_id",
+        "instance_events",
+        ["instance_id"],
+    )
+    op.create_index(
+        "idx_instance_events_created_at",
+        "instance_events",
+        ["created_at"],
+        postgresql_using="btree",
+    )
+    op.create_index(
+        "idx_instance_events_event_type",
+        "instance_events",
+        ["event_type"],
+    )
+
+    op.create_table(
+        "health_checks",
+        sa.Column("id", sa.Uuid(), nullable=False),
+        sa.Column(
+            "instance_id",
+            sa.Uuid(),
+            nullable=False,
+        ),
+        sa.Column("container_status", sa.String(length=50), nullable=True),
+        sa.Column("container_healthy", sa.Boolean(), nullable=True),
+        sa.Column("tunnel_healthy", sa.Boolean(), nullable=True),
+        sa.Column("exit_code", sa.Integer(), nullable=True),
+        sa.Column("probe_status", sa.String(length=50), nullable=True),
+        sa.Column("probe_output", sa.Text(), nullable=True),
+        sa.Column(
+            "checked_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+        sa.ForeignKeyConstraint(
+            ["instance_id"],
+            ["tool_instances.id"],
+            ondelete="CASCADE",
+        ),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(
+        "idx_health_checks_instance_id",
+        "health_checks",
+        ["instance_id"],
+    )
+    op.create_index(
+        "idx_health_checks_checked_at",
+        "health_checks",
+        ["checked_at"],
+        postgresql_using="btree",
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("idx_health_checks_checked_at", table_name="health_checks")
+    op.drop_index("idx_health_checks_instance_id", table_name="health_checks")
+    op.drop_table("health_checks")
+    op.drop_index("idx_instance_events_event_type", table_name="instance_events")
+    op.drop_index("idx_instance_events_created_at", table_name="instance_events")
+    op.drop_index("idx_instance_events_instance_id", table_name="instance_events")
+    op.drop_table("instance_events")

apps/api/alembic/versions/2026_05_28_add_tool_definition_manifests.py

@@ -232,14 +232,6 @@ def upgrade() -> None:
                             "writable": True,
                             "owner": "user",
                         },
-                        {
-                            "name": "ssh_keys",
-                            "target": "/home/user/.ssh",
-                            "source_type": "ssh_key",
-                            "mode": "0700",
-                            "file_mode": "0600",
-                            "readonly": True,
-                        },
                         {
                             "name": "pi_state",
                             "target": "/tmp/.pi/agents",

apps/api/alembic/versions/2026_05_29_add_notifications_table.py

@@ -0,0 +1,69 @@
+"""add notifications table
+
+Revision ID: 2026_05_29_add_notifications_table
+Revises: 2026_05_28_add_monitoring_tables
+Create Date: 2026-05-29
+
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "2026_05_29_add_notifications_table"
+down_revision: str | None = "2026_05_28_add_monitoring_tables"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "notifications",
+        sa.Column("id", sa.Uuid(), nullable=False),
+        sa.Column("user_id", sa.Uuid(), nullable=False),
+        sa.Column("category", sa.String(length=32), nullable=False),
+        sa.Column("severity", sa.String(length=16), nullable=False),
+        sa.Column("title", sa.String(length=255), nullable=False),
+        sa.Column("message", sa.Text(), nullable=True),
+        sa.Column("source_type", sa.String(length=64), nullable=True),
+        sa.Column("source_id", sa.Uuid(), nullable=True),
+        sa.Column(
+            "metadata",
+            sa.JSON(),
+            nullable=False,
+            server_default="{}",
+        ),
+        sa.Column("read_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("dismissed_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+        sa.ForeignKeyConstraint(
+            ["user_id"],
+            ["users.id"],
+            ondelete="CASCADE",
+        ),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(
+        "idx_notifications_user_created_at",
+        "notifications",
+        ["user_id", sa.text("created_at DESC")],
+    )
+    op.create_index(
+        "idx_notifications_user_unread",
+        "notifications",
+        ["user_id", "read_at"],
+        postgresql_where=sa.text("read_at IS NULL"),
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("idx_notifications_user_unread", table_name="notifications")
+    op.drop_index("idx_notifications_user_created_at", table_name="notifications")
+    op.drop_table("notifications")

apps/api/alembic/versions/2026_05_29_add_ssh_key_ids_to_tool_instances.py

@@ -0,0 +1,27 @@
+"""add_ssh_key_ids_to_tool_instances
+
+Revision ID: 2026_05_29_add_ssh_key_ids_to_tool_instances
+Revises: 2026_05_29_drop_ssh_key_id_from_config_profiles
+Create Date: 2026-05-29 12:46:00.000000
+"""
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision = "2026_05_29_add_ssh_key_ids_to_tool_instances"
+down_revision = "2026_05_29_drop_ssh_key_id_from_config_profiles"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "tool_instances",
+        sa.Column("ssh_key_ids", sa.JSON(), nullable=True),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("tool_instances", "ssh_key_ids")

apps/api/alembic/versions/2026_05_29_drop_ssh_key_id_from_config_profiles.py

@@ -0,0 +1,32 @@
+"""drop_ssh_key_id_from_config_profiles
+
+Revision ID: 2026_05_29_drop_ssh_key_id_from_config_profiles
+Revises: 069d3da4dc9b
+Create Date: 2026-05-29 12:45:00.000000
+"""
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision = "2026_05_29_drop_ssh_key_id_from_config_profiles"
+down_revision = "069d3da4dc9b"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.drop_column("config_profiles", "ssh_key_id")
+
+
+def downgrade() -> None:
+    op.add_column(
+        "config_profiles",
+        sa.Column(
+            "ssh_key_id",
+            sa.Uuid(),
+            sa.ForeignKey("ssh_keys.id", ondelete="SET NULL"),
+            nullable=True,
+        ),
+    )

apps/api/alembic/versions/2026_05_29_fix_code_server_bind_addr.py

@@ -0,0 +1,54 @@
+"""fix code-server bind-addr to host in DB template
+
+Revision ID: 2026_05_29_fix_code_server_bind_addr
+Revises: 2026_05_29_fix_web_tool_bind_address
+Create Date: 2026-05-29 15:00:00.000000
+
+"""
+
+from typing import Sequence
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision: str = "2026_05_29_fix_code_server_bind_addr"
+down_revision: str | None = "2026_05_29_fix_web_tool_bind_address"
+branch_labels: Sequence[str] | None = None
+depends_on: Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+
+    # Find code-server tool types with broken --bind-addr in compose template
+    result = conn.execute(
+        sa.text("""
+            SELECT id, compose_template
+            FROM tool_types
+            WHERE name = 'code-server'
+            AND compose_template LIKE '%--bind-addr%'
+        """)
+    ).fetchall()
+
+    for tool_id, compose_template in result:
+        updated = compose_template.replace(
+            "--bind-addr 0.0.0.0:8443", "--host 0.0.0.0"
+        ).replace("--bind-addr", "--host 0.0.0.0")
+
+        conn.execute(
+            sa.text("""
+                UPDATE tool_types
+                SET compose_template = :compose_template
+                WHERE id = :id
+            """),
+            {"compose_template": updated, "id": tool_id},
+        )
+
+        print(
+            f"Fixed code-server template ({tool_id}): replaced --bind-addr with --host"
+        )
+
+
+def downgrade() -> None:
+    pass

apps/api/alembic/versions/2026_05_29_fix_code_server_bind_addr_port.py

@@ -0,0 +1,148 @@
+"""Fix code-server bind address to include port
+
+Revision ID: 2026_05_29_fix_code_server_bind_addr_port
+Revises: 2026_05_29_remove_lsio_command_override
+Create Date: 2026-05-29 18:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+import yaml
+
+# revision identifiers, used by Alembic.
+revision: str = "2026_05_29_fix_code_server_bind_addr_port"
+down_revision: Union[str, None] = "2026_05_29_remove_lsio_command_override"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def _fix_tool_type_templates(conn) -> None:
+    """Fix code-server tool type templates with broken --host override."""
+    result = conn.execute(
+        sa.text("""
+            SELECT id, compose_template, default_port
+            FROM tool_types
+            WHERE name = 'code-server'
+            AND compose_template LIKE '%--host%'
+        """)
+    ).fetchall()
+
+    for tool_id, compose_template, default_port in result:
+        port = default_port or 8443
+        expected = f"--bind-addr 0.0.0.0:{port}"
+
+        # Replace any line containing --host with the correct bind-addr
+        lines = compose_template.split("\n")
+        new_lines = []
+        modified = False
+        for line in lines:
+            if "command:" in line and "--host" in line:
+                indent = line[: len(line) - len(line.lstrip())]
+                new_lines.append(f"{indent}command: {expected}")
+                modified = True
+            else:
+                new_lines.append(line)
+
+        if not modified:
+            continue
+
+        updated = "\n".join(new_lines)
+        conn.execute(
+            sa.text("""
+                UPDATE tool_types
+                SET compose_template = :compose_template
+                WHERE id = :id
+            """),
+            {"compose_template": updated, "id": tool_id},
+        )
+        print(f"Fixed code-server template ({tool_id}): replaced --host with {expected}")
+
+
+def _fix_instance_compose_files(conn) -> None:
+    """Fix existing instance compose files on disk with broken --host override."""
+    from pathlib import Path
+
+    # Use information_schema to check if compose_path column exists
+    col_result = conn.execute(
+        sa.text("""
+            SELECT column_name
+            FROM information_schema.columns
+            WHERE table_name = 'tool_instances'
+            AND column_name = 'compose_path'
+        """)
+    ).fetchone()
+
+    if not col_result:
+        print("compose_path column not found, skipping instance file fixes")
+        return
+
+    result = conn.execute(
+        sa.text("""
+            SELECT id, compose_path, tool_type_id
+            FROM tool_instances
+            WHERE compose_path IS NOT NULL
+        """)
+    ).fetchall()
+
+    for instance_id, compose_path, tool_type_id in result:
+        path = Path(compose_path)
+        if not path.exists():
+            continue
+
+        try:
+            content = path.read_text()
+        except Exception:
+            continue
+
+        if "--host" not in content:
+            continue
+
+        # Get default_port from tool_type
+        port_result = conn.execute(
+            sa.text("""
+                SELECT default_port FROM tool_types WHERE id = :id
+            """),
+            {"id": tool_type_id},
+        ).fetchone()
+        port = port_result[0] if port_result and port_result[0] else 8443
+        expected = f"--bind-addr 0.0.0.0:{port}"
+
+        try:
+            data = yaml.safe_load(content)
+        except Exception:
+            continue
+
+        if not data or "services" not in data:
+            continue
+
+        modified = False
+        for svc in data["services"].values():
+            if "command" in svc:
+                cmd = svc["command"]
+                if "--host" in cmd:
+                    svc["command"] = expected
+                    modified = True
+
+        if not modified:
+            continue
+
+        try:
+            path.write_text(yaml.dump(data, default_flow_style=False))
+            print(
+                f"Fixed code-server instance compose ({instance_id}): "
+                f"replaced --host with {expected}"
+            )
+        except Exception as exc:
+            print(f"Failed to fix instance {instance_id}: {exc}")
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    _fix_tool_type_templates(conn)
+    _fix_instance_compose_files(conn)
+
+
+def downgrade() -> None:
+    pass

apps/api/alembic/versions/2026_05_29_fix_web_tool_bind_address.py

@@ -0,0 +1,140 @@
+"""fix web tool bind address to 0.0.0.0
+
+Revision ID: 2026_05_29_fix_web_tool_bind_address
+Revises: 2026_05_29_remove_ssh_keys_mount_from_manifest
+Create Date: 2026-05-29 14:00:00.000000
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision: str = "2026_05_29_fix_web_tool_bind_address"
+down_revision: Union[str, None] = "2026_05_29_remove_ssh_keys_mount_from_manifest"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def _fix_code_server_compose(conn) -> None:
+    """Update code-server compose template to bind to 0.0.0.0."""
+    result = conn.execute(
+        sa.text("""
+            SELECT id, compose_template, definition_type
+            FROM tool_types
+            WHERE name = 'code-server'
+        """)
+    ).fetchone()
+
+    if result is None:
+        return
+
+    tool_id, compose_template, definition_type = result
+
+    if definition_type != "compose" or not compose_template:
+        return
+
+    # Fix or add command to bind to 0.0.0.0
+    lines = compose_template.split("\n")
+    new_lines = []
+    image_line_idx = -1
+    command_fixed = False
+    for i, line in enumerate(lines):
+        # Replace broken --bind-addr with correct --host
+        if "command:" in line and "--bind-addr" in line:
+            indent = line[: len(line) - len(line.lstrip())]
+            new_lines.append(f"{indent}command: --host 0.0.0.0")
+            command_fixed = True
+            continue
+        new_lines.append(line)
+        if "image:" in line and image_line_idx == -1:
+            image_line_idx = i
+
+    # If no command line exists, insert one after image
+    if not command_fixed and image_line_idx != -1:
+        image_line = lines[image_line_idx]
+        indent = image_line[: len(image_line) - len(image_line.lstrip())]
+        # Insert after the image line in new_lines
+        insert_idx = new_lines.index(image_line) + 1
+        new_lines.insert(insert_idx, f"{indent}command: --host 0.0.0.0")
+        command_fixed = True
+
+    if not command_fixed:
+        return
+
+    updated_compose = "\n".join(new_lines)
+
+    conn.execute(
+        sa.text("""
+            UPDATE tool_types
+            SET compose_template = :compose_template
+            WHERE id = :id
+        """),
+        {"compose_template": updated_compose, "id": tool_id},
+    )
+
+    print(f"Updated code-server tool type ({tool_id}) to bind to 0.0.0.0")
+
+
+def _fix_jupyter_compose(conn) -> None:
+    """Update jupyter-notebook compose template to bind to 0.0.0.0."""
+    result = conn.execute(
+        sa.text("""
+            SELECT id, compose_template, definition_type
+            FROM tool_types
+            WHERE name = 'jupyter-notebook'
+        """)
+    ).fetchone()
+
+    if result is None:
+        return
+
+    tool_id, compose_template, definition_type = result
+
+    if definition_type != "compose" or not compose_template:
+        return
+
+    if "command:" in compose_template:
+        return
+
+    lines = compose_template.split("\n")
+    new_lines = []
+    image_line_idx = -1
+    for i, line in enumerate(lines):
+        new_lines.append(line)
+        if "image:" in line and image_line_idx == -1:
+            image_line_idx = i
+            indent = line[: len(line) - len(line.lstrip())]
+            # Jupyter needs --ip=0.0.0.0 to bind to all interfaces
+            new_lines.append(
+                f"{indent}command: start-notebook.sh --ip=0.0.0.0 --port=8888 --no-browser"
+            )
+
+    if image_line_idx == -1:
+        return
+
+    updated_compose = "\n".join(new_lines)
+
+    conn.execute(
+        sa.text("""
+            UPDATE tool_types
+            SET compose_template = :compose_template
+            WHERE id = :id
+        """),
+        {"compose_template": updated_compose, "id": tool_id},
+    )
+
+    print(f"Updated jupyter-notebook tool type ({tool_id}) to bind to 0.0.0.0:8888")
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    _fix_code_server_compose(conn)
+    _fix_jupyter_compose(conn)
+
+
+def downgrade() -> None:
+    # Cannot safely downgrade without knowing the original compose_template
+    pass

apps/api/alembic/versions/2026_05_29_remove_lsio_command_override.py

@@ -0,0 +1,121 @@
+"""Remove broken command override from LSIO code-server templates
+
+Revision ID: 2026_05_29_remove_lsio_command_override
+Revises: 2026_05_29_fix_code_server_bind_addr
+Create Date: 2026-05-29 15:05:00.000000
+
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision: str = "2026_05_29_remove_lsio_command_override"
+down_revision: str | None = "2026_05_29_fix_code_server_bind_addr"
+branch_labels: Sequence[str] | None = None
+depends_on: Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+
+    # Fix tool_types templates in DB
+    result = conn.execute(
+        sa.text("""
+            SELECT id, compose_template
+            FROM tool_types
+            WHERE name = 'code-server'
+        """)
+    ).fetchall()
+
+    import yaml
+    from pathlib import Path
+
+    for tool_id, compose_template in result:
+        try:
+            data = yaml.safe_load(compose_template)
+        except Exception:
+            continue
+
+        if not data or "services" not in data:
+            continue
+
+        modified = False
+        for svc in data["services"].values():
+            image = svc.get("image", "")
+            if not image or "linuxserver" not in image:
+                continue
+            if "command" in svc:
+                cmd = svc["command"]
+                if "--bind-addr" in cmd or "--host" in cmd:
+                    del svc["command"]
+                    modified = True
+
+        if modified:
+            updated = yaml.dump(data, default_flow_style=False)
+            conn.execute(
+                sa.text("""
+                    UPDATE tool_types
+                    SET compose_template = :compose_template
+                    WHERE id = :id
+                """),
+                {"compose_template": updated, "id": tool_id},
+            )
+            print(f"Removed broken command override from LSIO template ({tool_id})")
+
+    # Fix existing instance compose files on disk
+    # Use information_schema to check if compose_path column exists
+    col_result = conn.execute(
+        sa.text("""
+            SELECT column_name
+            FROM information_schema.columns
+            WHERE table_name = 'tool_instances'
+            AND column_name = 'compose_path'
+        """)
+    ).fetchone()
+
+    if col_result:
+        result = conn.execute(
+            sa.text("""
+                SELECT id, compose_path
+                FROM tool_instances
+                WHERE compose_path IS NOT NULL
+            """)
+        ).fetchall()
+
+        for instance_id, compose_path in result:
+            path = Path(compose_path)
+            if not path.exists():
+                continue
+            try:
+                content = path.read_text()
+                data = yaml.safe_load(content)
+            except Exception:
+                continue
+
+            if not data or "services" not in data:
+                continue
+
+            modified = False
+            for svc in data["services"].values():
+                image = svc.get("image", "")
+                if not image or "linuxserver" not in image:
+                    continue
+                if "command" in svc:
+                    cmd = svc["command"]
+                    if "--bind-addr" in cmd or "--host" in cmd:
+                        del svc["command"]
+                        modified = True
+
+            if modified:
+                path.write_text(yaml.dump(data, default_flow_style=False))
+                print(
+                    f"Removed broken command override from instance compose "
+                    f"({instance_id})"
+                )
+
+
+def downgrade() -> None:
+    pass

apps/api/alembic/versions/2026_05_29_remove_ssh_keys_mount_from_manifest.py

@@ -0,0 +1,105 @@
+"""remove ssh_keys mount from pi-agent manifest
+
+Revision ID: 2026_05_29_remove_ssh_keys_mount_from_manifest
+Revises: 2026_05_29_add_ssh_key_ids_to_tool_instances
+Create Date: 2026-05-29 14:00:00.000000
+
+"""
+
+import json
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision: str = "2026_05_29_remove_ssh_keys_mount_from_manifest"
+down_revision: Union[str, None] = "2026_05_29_add_ssh_key_ids_to_tool_instances"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Remove the ssh_keys mount from the pi-agent manifest."""
+    conn = op.get_bind()
+
+    # Get the pi-agent manifest
+    result = conn.execute(
+        sa.text(
+            "SELECT id, manifest FROM tool_definition_manifests WHERE name = 'pi-agent'"
+        )
+    )
+    row = result.fetchone()
+    if not row:
+        return
+
+    manifest_id, manifest_json = row
+    manifest = (
+        manifest_json if isinstance(manifest_json, dict) else json.loads(manifest_json)
+    )
+
+    mounts = manifest.get("mounts", [])
+    original_count = len(mounts)
+
+    # Remove any mount named "ssh_keys"
+    filtered_mounts = [m for m in mounts if m.get("name") != "ssh_keys"]
+
+    if len(filtered_mounts) < original_count:
+        manifest["mounts"] = filtered_mounts
+        conn.execute(
+            sa.text(
+                "UPDATE tool_definition_manifests SET manifest = :manifest WHERE id = :id"
+            ),
+            {
+                "manifest": json.dumps(manifest),
+                "id": manifest_id,
+            },
+        )
+
+
+def downgrade() -> None:
+    """Restore the ssh_keys mount to the pi-agent manifest."""
+    conn = op.get_bind()
+
+    result = conn.execute(
+        sa.text(
+            "SELECT id, manifest FROM tool_definition_manifests WHERE name = 'pi-agent'"
+        )
+    )
+    row = result.fetchone()
+    if not row:
+        return
+
+    manifest_id, manifest_json = row
+    manifest = (
+        manifest_json if isinstance(manifest_json, dict) else json.loads(manifest_json)
+    )
+
+    mounts = manifest.get("mounts", [])
+
+    # Check if ssh_keys mount already exists
+    if any(m.get("name") == "ssh_keys" for m in mounts):
+        return
+
+    # Add the ssh_keys mount back
+    mounts.append(
+        {
+            "name": "ssh_keys",
+            "target": "/home/user/.ssh",
+            "source_type": "ssh_key",
+            "mode": "0700",
+            "file_mode": "0600",
+            "readonly": True,
+        }
+    )
+    manifest["mounts"] = mounts
+
+    conn.execute(
+        sa.text(
+            "UPDATE tool_definition_manifests SET manifest = :manifest WHERE id = :id"
+        ),
+        {
+            "manifest": json.dumps(manifest),
+            "id": manifest_id,
+        },
+    )

apps/api/alembic/versions/2026_06_01_add_workspaces.py

@@ -0,0 +1,81 @@
+"""add workspaces table
+
+Revision ID: 2026_06_01_add_workspaces
+Revises: 2026_05_29_fix_code_server_bind_addr_port
+Create Date: 2026-06-01 10:00:00.000000
+
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision: str = "2026_06_01_add_workspaces"
+down_revision: str | None = "2026_05_29_fix_code_server_bind_addr_port"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    # Create workspaces table
+    op.create_table(
+        "workspaces",
+        sa.Column("id", sa.Uuid(as_uuid=True), primary_key=True),
+        sa.Column("name", sa.String(255), nullable=False),
+        sa.Column(
+            "repo_id",
+            sa.Uuid(as_uuid=True),
+            sa.ForeignKey("git_repositories.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column(
+            "user_id",
+            sa.Uuid(as_uuid=True),
+            sa.ForeignKey("users.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column("branch", sa.String(255), nullable=False, server_default="main"),
+        sa.Column("path", sa.String(2048), nullable=False),
+        sa.Column("status", sa.String(16), nullable=False, server_default="ready"),
+        sa.Column("last_sync_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.UniqueConstraint("repo_id", "name", name="uq_workspace_repo_name"),
+        if_not_exists=True,
+    )
+
+    op.create_index("idx_workspaces_repo_id", "workspaces", ["repo_id"])
+    op.create_index("idx_workspaces_user_id", "workspaces", ["user_id"])
+    op.create_index("idx_workspaces_status", "workspaces", ["status"])
+
+    # Add workspace_id to tool_instances
+    op.add_column(
+        "tool_instances",
+        sa.Column(
+            "workspace_id",
+            sa.Uuid(as_uuid=True),
+            sa.ForeignKey("workspaces.id", ondelete="SET NULL"),
+            nullable=True,
+        ),
+    )
+    op.create_index(
+        "idx_tool_instances_workspace_id", "tool_instances", ["workspace_id"]
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("idx_tool_instances_workspace_id", table_name="tool_instances")
+    op.drop_column("tool_instances", "workspace_id")
+    op.drop_table("workspaces")

apps/api/alembic/versions/86cec91fdb00_merge_profile_resolver_and_workspaces_.py

@@ -0,0 +1,20 @@
+"""merge profile resolver and workspaces heads
+
+Revision ID: 86cec91fdb00
+Revises: 0014_add_profile_resolver_fields, 2026_06_01_add_workspaces
+Create Date: 2026-06-03 12:48:36.145702
+"""
+
+# revision identifiers, used by Alembic.
+revision = "86cec91fdb00"
+down_revision = ("0014_add_profile_resolver_fields", "2026_06_01_add_workspaces")
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    pass
+
+
+def downgrade() -> None:
+    pass

apps/api/src/api/__init__.py

@@ -1,4 +1 @@
-from src.api.auth import router as auth_router
-from src.api.users import router as users_router
-
-__all__ = ["auth_router", "users_router"]
+"""API routers package."""

apps/api/src/api/config/__init__.py

@@ -0,0 +1,6 @@
+"""Config API routers module."""
+
+from src.api.config.config_profiles import router as config_profiles_router
+from src.api.config.user_config import router as user_config_router
+
+__all__ = ["config_profiles_router", "user_config_router"]

apps/api/src/api/config/config_profiles.py

@@ -1,25 +1,37 @@
 """Config profile API endpoints."""
 
 import logging
+import os
+import subprocess
 import uuid
+from typing import Any
 
 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.api.shared_validators import validate_env_vars as _validate_env_vars
 from src.auth.dependencies import get_current_user_id, get_db_session
-from src.models.config_profile import ConfigProfile, ConfigProfileInclude
+from src.models import ConfigProfile, ConfigProfileInclude
 from src.models.project import Project
-from src.models.tool_type import ToolType
-from src.services.config_profile_resolver import (
+from src.models import ToolType
+from src.models import UserConfig
+from src.schemas.config import (
+    ConfigProfileCreate,
+    ConfigProfileIncludeUpdate,
+    ConfigProfileResponse,
+    ConfigProfileUpdate,
+    DefaultProfilesUpdate,
+    ValidateGitUrlRequest,
+    ValidateGitUrlResponse,
+)
+from src.services.config.config_profile_resolver import (
     ConfigProfileCycleError,
     check_include_cycle,
     resolve_profile,
     resolved_profile_to_dict,
 )
+from src.utils.git_url_parser import parse_git_url
 
 logger = logging.getLogger(__name__)
 
@@ -29,16 +41,6 @@ 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
@@ -56,183 +58,9 @@ def _calculate_profile_size(data: dict) -> int:
     return total
 
 
-class GitMountItem(BaseModel):
-    remote_url: str = Field(description="Git remote URL (HTTPS or SSH)")
-    source_path: str = Field(default=".", description="Path within repository (supports glob patterns)")
-    target_path: str = Field(description="Absolute path inside container")
-    branch: str | None = Field(default=None, description="Optional branch or tag name")
-
-    @field_validator("remote_url")
-    @classmethod
-    def validate_remote_url(cls, v: str) -> str:
-        if not v.startswith(("http://", "https://", "git@", "ssh://")):
-            raise ValueError("remote_url must be a valid git URL (https://, git@, or ssh://)")
-        return v
-
-    @field_validator("source_path")
-    @classmethod
-    def validate_source_path(cls, v: str) -> str:
-        if v.startswith("/"):
-            raise ValueError("source_path must be relative (no leading /)")
-        if ".." in v:
-            raise ValueError("source_path cannot contain path traversal (..)")
-        return v
-
-    @field_validator("target_path")
-    @classmethod
-    def validate_target_path(cls, v: str) -> str:
-        if ".." in v:
-            raise ValueError("target_path cannot contain path traversal (..)")
-        return v
-
-
-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 not path:
-                raise ValueError(f"Invalid file path: {path}")
-            if path.startswith("/"):
-                raise ValueError(
-                    f"Mount file paths must be relative (got: {path}). "
-                    f"The mount target defines the absolute container 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}")
-    git_mounts: list[GitMountItem] = Field(default_factory=list, description="Git repository mounts")
-    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 not path:
-                raise ValueError(f"Invalid file path: {path}")
-            if path.startswith("/"):
-                raise ValueError(
-                    f"File paths must be relative (got: {path}). "
-                    f"Use Mounts for absolute container paths."
-                )
-        return v
-
-    @field_validator("env_vars")
-    @classmethod
-    def validate_env_vars(cls, v: dict) -> dict:
-        result = _validate_env_vars(v)
-        if result is None:
-            raise ValueError("env_vars must be a JSON object")
-        return result
-
-    @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}")
-    git_mounts: list[GitMountItem] | None = Field(default=None, description="Git repository mounts")
-    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
-    git_mounts: list
-    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:
+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)
@@ -252,22 +80,26 @@ async def _check_access(
     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")
+            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")
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND, detail="Tool type not found"
+            )
 
 
 async def _validate_git_mounts(
     session: AsyncSession,
     user_id: uuid.UUID,
-    git_mounts: list[dict],
+    git_mounts: list[Any],
     project_id: uuid.UUID | None = None,
 ) -> None:
     """Validate git mount URLs.
-    
+
     Simply checks that remote_url looks like a valid git URL.
     Actual clone validation happens at instance startup time.
     """
@@ -278,7 +110,7 @@ async def _validate_git_mounts(
                 status_code=status.HTTP_400_BAD_REQUEST,
                 detail="Git mount missing remote_url",
             )
-        
+
         if not remote_url.startswith(("http://", "https://", "git@", "ssh://")):
             raise HTTPException(
                 status_code=status.HTTP_400_BAD_REQUEST,
@@ -286,7 +118,9 @@ async def _validate_git_mounts(
             )
 
 
-def _profile_to_response(profile: ConfigProfile, includes: list[ConfigProfileInclude] | None = None) -> dict:
+def _profile_to_response(
+    profile: ConfigProfile, includes: list[ConfigProfileInclude] | None = None
+) -> dict:
     return {
         "id": str(profile.id),
         "user_id": str(profile.user_id),
@@ -316,13 +150,19 @@ def _profile_to_response(profile: ConfigProfile, includes: list[ConfigProfileInc
 @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"),
+    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))
+    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
@@ -334,7 +174,8 @@ async def list_config_profiles(
         conditions: list = []
         # Portable profiles (no project, no tool)
         conditions.append(
-            (ConfigProfile.project_id.is_(None)) & (ConfigProfile.tool_type_id.is_(None))
+            (ConfigProfile.project_id.is_(None))
+            & (ConfigProfile.tool_type_id.is_(None))
         )
         if project_uuid:
             # Profiles matching this project (with or without tool)
@@ -345,7 +186,8 @@ async def list_config_profiles(
         if project_uuid and tool_uuid:
             # Exact match
             conditions.append(
-                (ConfigProfile.project_id == project_uuid) & (ConfigProfile.tool_type_id == tool_uuid)
+                (ConfigProfile.project_id == project_uuid)
+                & (ConfigProfile.tool_type_id == tool_uuid)
             )
 
         query = query.where(or_(*conditions))
@@ -355,7 +197,9 @@ async def list_config_profiles(
     return [_profile_to_response(p) for p in profiles]
 
 
-@router.post("", response_model=ConfigProfileResponse, status_code=status.HTTP_201_CREATED)
+@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),
@@ -366,10 +210,12 @@ async def create_config_profile(
 
     # Check for duplicate name
     existing = await session.execute(
-        select(ConfigProfile).where(
+        select(ConfigProfile)
+        .where(
             ConfigProfile.user_id == user_uuid,
             ConfigProfile.name == data.name,
-        ).options(selectinload(ConfigProfile.includes))
+        )
+        .options(selectinload(ConfigProfile.includes))
     )
     if existing.scalar_one_or_none() is not None:
         raise HTTPException(
@@ -381,10 +227,12 @@ async def create_config_profile(
     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)
-    
+
     # Validate git mounts reference existing repositories
     if data.git_mounts:
-        git_mounts_data = [m.model_dump() if hasattr(m, "model_dump") else m for m in data.git_mounts]
+        git_mounts_data = [
+            m.model_dump() if hasattr(m, "model_dump") else m for m in data.git_mounts
+        ]
         await _validate_git_mounts(session, user_uuid, git_mounts_data, project_uuid)
 
     # Check size
@@ -432,9 +280,13 @@ async def get_config_profile(
     """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")
+        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")
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN, detail="Not authorized"
+        )
     return _profile_to_response(profile)
 
 
@@ -448,9 +300,13 @@ async def update_config_profile(
     """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")
+        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")
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN, detail="Not authorized"
+        )
 
     update_data = data.model_dump(exclude_unset=True)
 
@@ -481,14 +337,16 @@ async def update_config_profile(
         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)
-    
+
     # Validate git mounts reference existing repositories
     if "git_mounts" in update_data and update_data["git_mounts"] is not None:
         git_mounts_data = [
-            m.model_dump() if hasattr(m, "model_dump") else m 
+            m.model_dump() if hasattr(m, "model_dump") else m
             for m in update_data["git_mounts"]
         ]
-        await _validate_git_mounts(session, profile.user_id, git_mounts_data, project_uuid)
+        await _validate_git_mounts(
+            session, profile.user_id, git_mounts_data, project_uuid
+        )
 
     # Check size
     current_data = _profile_to_response(profile)
@@ -533,9 +391,13 @@ async def delete_config_profile(
     """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")
+        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")
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN, detail="Not authorized"
+        )
 
     await session.delete(profile)
     await session.commit()
@@ -554,9 +416,13 @@ async def update_profile_includes(
     """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")
+        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")
+        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]
@@ -596,7 +462,9 @@ async def update_profile_includes(
 
     # Remove existing includes
     result = await session.execute(
-        select(ConfigProfileInclude).where(ConfigProfileInclude.profile_id == profile.id)
+        select(ConfigProfileInclude).where(
+            ConfigProfileInclude.profile_id == profile.id
+        )
     )
     for existing in result.scalars().all():
         await session.delete(existing)
@@ -621,7 +489,9 @@ async def update_profile_includes(
     profile = result.scalar_one()
 
     inc_result = await session.execute(
-        select(ConfigProfileInclude).where(ConfigProfileInclude.profile_id == profile.id)
+        select(ConfigProfileInclude).where(
+            ConfigProfileInclude.profile_id == profile.id
+        )
     )
     direct_includes = inc_result.scalars().all()
 
@@ -638,9 +508,13 @@ async def preview_config_profile(
     """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")
+        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")
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN, detail="Not authorized"
+        )
 
     try:
         resolved = await resolve_profile(session, profile.id)
@@ -721,3 +595,248 @@ async def resolve_default_profile(
     # Fall back to first created compatible profile
     first = profiles[0]
     return {"profile_id": str(first.id), "profile_name": first.name}
+
+
+# ---------------------------------------------------------------------------
+# Default profile management
+# ---------------------------------------------------------------------------
+
+
+async def _get_or_create_user_config(
+    session: AsyncSession,
+    user_id: uuid.UUID,
+) -> UserConfig:
+    """Get existing user config or create a new one."""
+    result = await session.execute(
+        select(UserConfig).where(UserConfig.user_id == user_id)
+    )
+    user_config = result.scalar_one_or_none()
+    if user_config is None:
+        user_config = UserConfig(user_id=user_id, config={})
+        session.add(user_config)
+    return user_config
+
+
+async def _validate_default_profiles(
+    session: AsyncSession,
+    user_id: uuid.UUID,
+    default_profiles: dict[str, str],
+) -> None:
+    """Validate that all profile IDs in default_profiles belong to the user."""
+    for tool_type_id, profile_id_str in default_profiles.items():
+        try:
+            profile_uuid = uuid.UUID(profile_id_str)
+        except ValueError:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=f"Invalid profile ID for tool type {tool_type_id}: {profile_id_str}",
+            )
+        profile = await session.get(ConfigProfile, profile_uuid)
+        if profile is None:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Profile not found: {profile_id_str}",
+            )
+        if profile.user_id != user_id:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=f"Profile does not belong to user: {profile_id_str}",
+            )
+
+
+@router.get("/defaults")
+async def get_default_profiles_endpoint(
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Get all default profile mappings for the current user."""
+    result = await session.execute(
+        select(UserConfig).where(UserConfig.user_id == user_id)
+    )
+    user_config = result.scalar_one_or_none()
+    return {"default_profiles": user_config.default_profiles if user_config else {}}
+
+
+@router.put("/defaults")
+async def set_default_profiles_endpoint(
+    data: DefaultProfilesUpdate,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Set default profile mappings for the current user."""
+    await _validate_default_profiles(session, user_id, data.default_profiles)
+    user_config = await _get_or_create_user_config(session, user_id)
+    user_config.config = {
+        **user_config.config,
+        "default_profiles": data.default_profiles,
+    }
+    await session.commit()
+    await session.refresh(user_config)
+    return {"default_profiles": user_config.default_profiles}
+
+
+@router.get("/defaults/{tool_type_id}")
+async def get_default_profile_for_tool_type_endpoint(
+    tool_type_id: str,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Get the default profile ID for a specific tool type."""
+    result = await session.execute(
+        select(UserConfig).where(UserConfig.user_id == user_id)
+    )
+    user_config = result.scalar_one_or_none()
+    profile_id = user_config.default_profiles.get(tool_type_id) if user_config else None
+    return {"tool_type_id": tool_type_id, "profile_id": profile_id}
+
+
+@router.post("/validate-git-url", response_model=ValidateGitUrlResponse)
+async def validate_git_url(
+    data: ValidateGitUrlRequest,
+    current_user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> ValidateGitUrlResponse:
+    """Validate a git remote URL and list available branches.
+
+    Parses the URL, suggests corrections for browser URLs, and runs
+    git ls-remote to verify reachability and enumerate branches.
+    """
+    parse_result = parse_git_url(data.url)
+    original_url = data.url.strip()
+    url_to_check = parse_result.get("base_url") or original_url
+
+    if not url_to_check:
+        return ValidateGitUrlResponse(
+            valid=False,
+            error=parse_result.get("message", "Invalid URL"),
+            error_code=parse_result.get("error_code", "INVALID_URL"),
+        )
+
+    # If the URL needed parsing, return suggestion without checking remote
+    if parse_result.get("needs_parsing") and url_to_check != original_url:
+        return ValidateGitUrlResponse(
+            valid=False,
+            suggested_url=url_to_check,
+            error=parse_result.get("message"),
+            error_code=parse_result.get("error_code", "URL_NEEDS_PARSING"),
+        )
+
+    # Optional SSH key for private repos
+    env = None
+    key_path = None
+    if data.ssh_key_id:
+        from src.models import SSHKey
+        from src.services.shared.ssh_keys import _get_fernet
+
+        try:
+            ssh_key_uuid = uuid.UUID(data.ssh_key_id)
+        except ValueError:
+            return ValidateGitUrlResponse(
+                valid=False,
+                error="Invalid SSH key ID format",
+                error_code="INVALID_SSH_KEY",
+            )
+
+        ssh_key = await session.get(SSHKey, ssh_key_uuid)
+        if ssh_key is None or ssh_key.user_id != current_user_id:
+            return ValidateGitUrlResponse(
+                valid=False,
+                error="SSH key not found or not authorized",
+                error_code="SSH_KEY_NOT_FOUND",
+            )
+
+        import tempfile
+
+        fernet = _get_fernet()
+        private_key = fernet.decrypt(ssh_key.private_key_encrypted.encode()).decode()
+        fd, key_path = tempfile.mkstemp(prefix="ssh_key_")
+        try:
+            os.write(fd, private_key.encode())
+        finally:
+            os.close(fd)
+        os.chmod(key_path, 0o600)
+        env = {
+            "GIT_SSH_COMMAND": f"ssh -i {key_path} -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null"
+        }
+
+    try:
+        result = subprocess.run(
+            ["git", "ls-remote", "--heads", url_to_check],
+            capture_output=True,
+            text=True,
+            timeout=30,
+            env={**os.environ, **env} if env else None,
+        )
+    except subprocess.TimeoutExpired:
+        if key_path and os.path.exists(key_path):
+            os.unlink(key_path)
+        return ValidateGitUrlResponse(
+            valid=False,
+            error="Remote repository check timed out",
+            error_code="TIMEOUT",
+        )
+    except FileNotFoundError:
+        if key_path and os.path.exists(key_path):
+            os.unlink(key_path)
+        return ValidateGitUrlResponse(
+            valid=False,
+            error="git command not found on server",
+            error_code="GIT_NOT_FOUND",
+        )
+    finally:
+        if key_path and os.path.exists(key_path):
+            os.unlink(key_path)
+
+    if result.returncode != 0:
+        stderr = result.stderr.strip()
+        if (
+            "could not resolve" in stderr.lower()
+            or "unable to access" in stderr.lower()
+        ):
+            error_msg = "Could not reach repository. Check the URL and network access."
+            error_code = "UNREACHABLE"
+        elif (
+            "authentication" in stderr.lower() or "permission denied" in stderr.lower()
+        ):
+            error_msg = (
+                "Authentication failed. Provide an SSH key for private repositories."
+            )
+            error_code = "AUTH_FAILED"
+        else:
+            error_msg = f"Repository not accessible: {stderr[:200]}"
+            error_code = "REMOTE_ERROR"
+        return ValidateGitUrlResponse(
+            valid=False,
+            error=error_msg,
+            error_code=error_code,
+        )
+
+    # Parse branches from ls-remote output
+    branches: list[str] = []
+    default_branch = "main"
+    for line in result.stdout.strip().split("\n"):
+        if not line.strip():
+            continue
+        parts = line.split()
+        if len(parts) == 2:
+            ref = parts[1]
+            # refs/heads/branch-name
+            if ref.startswith("refs/heads/"):
+                branch_name = ref[len("refs/heads/") :]
+                branches.append(branch_name)
+                if branch_name in ("main", "master"):
+                    default_branch = branch_name
+
+    if not branches:
+        return ValidateGitUrlResponse(
+            valid=False,
+            error="No branches found in remote repository",
+            error_code="NO_BRANCHES",
+        )
+
+    return ValidateGitUrlResponse(
+        valid=True,
+        suggested_url=url_to_check if url_to_check != original_url else None,
+        branches=branches,
+        default_branch=default_branch,
+    )

apps/api/src/api/config/user_config.py

@@ -2,19 +2,21 @@ import logging
 import uuid
 
 from fastapi import APIRouter, Depends
-from pydantic import BaseModel, ConfigDict
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from src.auth.dependencies import _get_user, get_current_user_id, get_db_session
-from src.models.user_config import UserConfig
+from src.models import UserConfig
+from src.schemas.user import UserConfigResponse, UserConfigUpdate
 
 logger = logging.getLogger(__name__)
 
 router = APIRouter(prefix="/users/me", tags=["user-config"])
 
 
-async def _get_or_create_config(session: AsyncSession, user_id: uuid.UUID) -> UserConfig:
+async def _get_or_create_config(
+    session: AsyncSession, user_id: uuid.UUID
+) -> UserConfig:
     """Get or create user config record.
 
     Args:
@@ -24,7 +26,9 @@ async def _get_or_create_config(session: AsyncSession, user_id: uuid.UUID) -> Us
     Returns:
         The user's config, creating a new one if it doesn't exist.
     """
-    result = await session.execute(select(UserConfig).where(UserConfig.user_id == user_id))
+    result = await session.execute(
+        select(UserConfig).where(UserConfig.user_id == user_id)
+    )
     config = result.scalar_one_or_none()
     if config is None:
         config = UserConfig(user_id=user_id, config={})
@@ -34,24 +38,6 @@ async def _get_or_create_config(session: AsyncSession, user_id: uuid.UUID) -> Us
     return config
 
 
-class UserConfigResponse(BaseModel):
-    model_config = ConfigDict(from_attributes=True)
-
-    default_editor: str | None = None
-    theme: str = "system"
-    git_user_name: str | None = None
-    git_user_email: str | None = None
-    last_session_id: str | None = None
-
-
-class UserConfigUpdate(BaseModel):
-    default_editor: str | None = None
-    theme: str | None = None
-    git_user_name: str | None = None
-    git_user_email: str | None = None
-    last_session_id: str | None = None
-
-
 @router.get(
     "/config",
     response_model=UserConfigResponse,

apps/api/src/api/project/__init__.py

@@ -0,0 +1,6 @@
+"""Project API routers module."""
+
+from src.api.project.git_repositories import router as git_repositories_router
+from src.api.project.projects import router as projects_router
+
+__all__ = ["git_repositories_router", "projects_router"]

apps/api/src/api/project/git_repositories.py

@@ -3,17 +3,28 @@ import os
 import shutil
 import subprocess
 import uuid
-from datetime import datetime
 
 from fastapi import APIRouter, Depends, HTTPException, Response, status
-from pydantic import BaseModel, ConfigDict
+from pydantic import BaseModel
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from src.auth.dependencies import _get_owned_project, _get_user, get_current_user_id, get_db_session
+from src.auth.dependencies import (
+    _get_owned_project,
+    _get_user,
+    get_current_user_id,
+    get_db_session,
+)
 from src.config import Settings
-from src.models.git_repository import GitRepository
-from src.models.ssh_key import SSHKey
+from src.models import GitRepository
+from src.models import SSHKey
+from src.schemas.project import (
+    GitRepositoryCreate,
+    GitRepositoryResponse,
+    URLParseRequest,
+    URLParseResponse,
+    UpdateSSHKeyRequest,
+)
 from src.utils.git_files import (
     commit_file,
     get_file_content,
@@ -33,7 +44,7 @@ from src.utils.git_control import (
 )
 from src.utils.git_history import get_commit_detail, get_commit_history
 from src.utils.git_url_parser import parse_git_url
-from src.services.ssh_keys import _get_fernet
+from src.services.shared.ssh_keys import _get_fernet
 
 router = APIRouter(prefix="/projects", tags=["git-repositories"])
 
@@ -62,19 +73,19 @@ def _build_provider_clone_url(owner: str, repo: str) -> str:
 
 def _prepare_ssh_env(ssh_key: SSHKey | None) -> dict | None:
     """Prepare environment variables for git commands with SSH authentication.
-    
+
     Returns a dict of extra env vars, or None if no SSH key provided.
     The caller is responsible for cleaning up the temporary key file.
     """
     if ssh_key is None:
         return None
-    
+
     import tempfile
-    
+
     # Decrypt private key
     fernet = _get_fernet()
     private_key = fernet.decrypt(ssh_key.private_key_encrypted.encode()).decode()
-    
+
     # Write to temp file with restricted permissions
     fd, key_path = tempfile.mkstemp(prefix="ssh_key_")
     try:
@@ -82,7 +93,7 @@ def _prepare_ssh_env(ssh_key: SSHKey | None) -> dict | None:
     finally:
         os.close(fd)
     os.chmod(key_path, 0o600)
-    
+
     # Return env vars and the key path for cleanup
     env = {
         "GIT_SSH_COMMAND": f"ssh -i {key_path} -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null"
@@ -90,16 +101,18 @@ def _prepare_ssh_env(ssh_key: SSHKey | None) -> dict | None:
     return env, key_path
 
 
-def _preflight_remote_repository(remote_url: str, ssh_key: SSHKey | None = None) -> None:
+def _preflight_remote_repository(
+    remote_url: str, ssh_key: SSHKey | None = None
+) -> None:
     """Verify a remote repository is reachable before cloning."""
     env = None
     key_path = None
-    
+
     if ssh_key is not None:
         ssh_result = _prepare_ssh_env(ssh_key)
         if ssh_result:
             env, key_path = ssh_result
-    
+
     try:
         result = subprocess.run(
             ["git", "ls-remote", remote_url],
@@ -109,30 +122,40 @@ def _preflight_remote_repository(remote_url: str, ssh_key: SSHKey | None = None)
             env={**os.environ, **env} if env else None,
         )
     except subprocess.TimeoutExpired:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="remote repository check timed out")
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="remote repository check timed out",
+        )
     except FileNotFoundError:
-        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="git command not found")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="git command not found",
+        )
     finally:
         if key_path and os.path.exists(key_path):
             os.unlink(key_path)
 
     if result.returncode != 0:
-        logger.error("Preflight check failed for %s: stderr=%s", remote_url, result.stderr)
+        logger.error(
+            "Preflight check failed for %s: stderr=%s", remote_url, result.stderr
+        )
         raise HTTPException(
             status_code=status.HTTP_400_BAD_REQUEST,
             detail=f"repository not found or inaccessible: {result.stderr}",
         )
 
 
-def _clone_working_repository(remote_url: str, repo_path: str, ssh_key: SSHKey | None = None) -> None:
+def _clone_working_repository(
+    remote_url: str, repo_path: str, ssh_key: SSHKey | None = None
+) -> None:
     env = None
     key_path = None
-    
+
     if ssh_key is not None:
         ssh_result = _prepare_ssh_env(ssh_key)
         if ssh_result:
             env, key_path = ssh_result
-    
+
     try:
         result = subprocess.run(
             ["git", "clone", remote_url, repo_path],
@@ -142,9 +165,14 @@ def _clone_working_repository(remote_url: str, repo_path: str, ssh_key: SSHKey |
             env={**os.environ, **env} if env else None,
         )
     except subprocess.TimeoutExpired:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="clone operation timed out")
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST, detail="clone operation timed out"
+        )
     except FileNotFoundError:
-        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="git command not found")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="git command not found",
+        )
     finally:
         if key_path and os.path.exists(key_path):
             os.unlink(key_path)
@@ -165,7 +193,10 @@ def _init_working_repository(repo_path: str) -> None:
             text=True,
         )
     except FileNotFoundError:
-        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="git command not found")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="git command not found",
+        )
 
     if result.returncode == 0:
         return
@@ -193,43 +224,6 @@ def _init_working_repository(repo_path: str) -> None:
         )
 
 
-class GitRepositoryCreate(BaseModel):
-    name: str
-    remote_url: str | None = None
-    force_original_url: bool = False
-    ssh_key_id: str | None = None
-
-
-class URLParseRequest(BaseModel):
-    url: str
-
-
-class URLParseResponse(BaseModel):
-    original_url: str
-    base_url: str | None
-    is_valid_clone_url: bool
-    needs_parsing: bool
-    host: str | None
-    message: str
-    error_code: str | None
-
-
-class GitRepositoryResponse(BaseModel):
-    model_config = ConfigDict(from_attributes=True)
-
-    id: uuid.UUID
-    name: str
-    path: str
-    project_id: uuid.UUID | None
-    owner_id: uuid.UUID
-    is_mirror: bool
-    remote_url: str | None
-    last_push: datetime | None
-    ssh_key_id: uuid.UUID | None
-    created_at: datetime
-    updated_at: datetime
-
-
 @router.get(
     "/repositories",
     response_model=list[GitRepositoryResponse],
@@ -310,7 +304,10 @@ async def create_external_repository(
         )
     )
     if existing.scalar_one_or_none():
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="repository name already exists")
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="repository name already exists",
+        )
 
     # Validate and potentially correct the URL
     remote_url = data.remote_url
@@ -336,13 +333,21 @@ async def create_external_repository(
         try:
             ssh_key_id = uuid.UUID(data.ssh_key_id)
         except ValueError:
-            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="invalid ssh_key_id format")
-        
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="invalid ssh_key_id format",
+            )
+
         ssh_key = await session.get(SSHKey, ssh_key_id)
         if ssh_key is None:
-            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="ssh key not found")
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND, detail="ssh key not found"
+            )
         if ssh_key.user_id != user_id:
-            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="ssh key does not belong to user")
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="ssh key does not belong to user",
+            )
 
     if remote_url:
         _preflight_remote_repository(remote_url, ssh_key)
@@ -369,7 +374,10 @@ async def create_external_repository(
             repo.is_mirror = False
         except Exception as exc:
             await session.rollback()
-            raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=f"Failed to clone repository: {exc}")
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail=f"Failed to clone repository: {exc}",
+            )
     else:
         # Initialize empty repo
         os.makedirs(repo_path, exist_ok=True)
@@ -438,7 +446,9 @@ async def delete_repository(
 
     repo = await session.get(GitRepository, repo_id)
     if repo is None or repo.project_id != project_id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="repository not found")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="repository not found"
+        )
 
     # Remove from disk
     if os.path.exists(repo.path):
@@ -484,7 +494,10 @@ async def create_repository(
         )
     )
     if existing.scalar_one_or_none():
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="repository name already exists")
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="repository name already exists",
+        )
 
     # Validate and potentially correct the URL
     remote_url = data.remote_url
@@ -511,13 +524,21 @@ async def create_repository(
         try:
             ssh_key_id = uuid.UUID(data.ssh_key_id)
         except ValueError:
-            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="invalid ssh_key_id format")
-        
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="invalid ssh_key_id format",
+            )
+
         ssh_key = await session.get(SSHKey, ssh_key_id)
         if ssh_key is None:
-            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="ssh key not found")
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND, detail="ssh key not found"
+            )
         if ssh_key.user_id != user_id and ssh_key.project_id != project_id:
-            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="ssh key does not belong to user or project")
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="ssh key does not belong to user or project",
+            )
 
     if remote_url:
         _preflight_remote_repository(remote_url, ssh_key)
@@ -547,10 +568,6 @@ async def create_repository(
     return repo
 
 
-class UpdateSSHKeyRequest(BaseModel):
-    ssh_key_id: str | None = None
-
-
 @router.patch(
     "/{project_id}/repositories/{repo_id}/ssh-key",
     response_model=GitRepositoryResponse,
@@ -581,20 +598,30 @@ async def update_repository_ssh_key(
 
     repo = await session.get(GitRepository, repo_id)
     if repo is None or repo.project_id != project_id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="repository not found")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="repository not found"
+        )
 
     # Validate SSH key if provided
     if data.ssh_key_id:
         try:
             ssh_key_id = uuid.UUID(data.ssh_key_id)
         except ValueError:
-            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="invalid ssh_key_id format")
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="invalid ssh_key_id format",
+            )
 
         ssh_key = await session.get(SSHKey, ssh_key_id)
         if ssh_key is None:
-            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="ssh key not found")
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND, detail="ssh key not found"
+            )
         if ssh_key.user_id != user_id and ssh_key.project_id != project_id:
-            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="ssh key does not belong to user or project")
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="ssh key does not belong to user or project",
+            )
 
         repo.ssh_key_id = ssh_key_id
     else:
@@ -640,16 +667,24 @@ async def get_repository_history(
 
     repo = await session.get(GitRepository, repo_id)
     if repo is None or repo.project_id != project_id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="repository not found")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="repository not found"
+        )
 
     if not os.path.exists(repo.path):
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="repository not found on disk")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="repository not found on disk"
+        )
 
     try:
-        history = get_commit_history(repo.path, branch=branch, limit=limit, offset=offset)
+        history = get_commit_history(
+            repo.path, branch=branch, limit=limit, offset=offset
+        )
         return history
     except RuntimeError as e:
-        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=str(e))
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=str(e)
+        )
 
 
 @router.get(
@@ -681,10 +716,14 @@ async def get_repository_commit(
 
     repo = await session.get(GitRepository, repo_id)
     if repo is None or repo.project_id != project_id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="repository not found")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="repository not found"
+        )
 
     if not os.path.exists(repo.path):
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="repository not found on disk")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="repository not found on disk"
+        )
 
     try:
         detail = get_commit_detail(repo.path, commit_hash)
@@ -763,10 +802,14 @@ async def list_repository_files(
 
     repo = await session.get(GitRepository, repo_id)
     if repo is None or repo.project_id != project_id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="repository not found")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="repository not found"
+        )
 
     if not os.path.exists(repo.path):
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="repository not found on disk")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="repository not found on disk"
+        )
 
     try:
         entries = list_tree(repo.path, branch=branch, path=path)
@@ -829,10 +872,14 @@ async def get_repository_file_content(
 
     repo = await session.get(GitRepository, repo_id)
     if repo is None or repo.project_id != project_id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="repository not found")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="repository not found"
+        )
 
     if not os.path.exists(repo.path):
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="repository not found on disk")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="repository not found on disk"
+        )
 
     try:
         file_content = get_file_content(repo.path, branch=branch, path=path)
@@ -847,7 +894,9 @@ async def get_repository_file_content(
             last_commit=file_content.last_commit,
         )
     except FileNotFoundError:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="file not found")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="file not found"
+        )
     except RuntimeError as e:
         raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
 
@@ -880,32 +929,104 @@ async def get_repository_branches(
 
     repo = await session.get(GitRepository, repo_id)
     if repo is None or repo.project_id != project_id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="repository not found")
-
-    if not os.path.exists(repo.path):
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="repository not found on disk")
-
-    try:
-        branches, default_branch = list_branches(repo.path)
-        return BranchesResponse(
-            branches=[
-                {
-                    "name": b.name,
-                    "is_default": b.is_default,
-                    "last_commit": b.last_commit,
-                }
-                for b in branches
-            ],
-            default_branch=default_branch,
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="repository not found"
         )
-    except RuntimeError as e:
-        logger.error(
-            "Failed to list branches for repo %s: %s",
-            repo_id,
-            str(e),
-            exc_info=True,
-        )
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
+
+    # Try local repo first (.git subdir for normal repos, HEAD for bare)
+    is_valid_git_repo = os.path.isdir(
+        os.path.join(repo.path, ".git")
+    ) or os.path.isfile(os.path.join(repo.path, "HEAD"))
+
+    if is_valid_git_repo:
+        try:
+            branches, default_branch = list_branches(repo.path)
+            return BranchesResponse(
+                branches=[
+                    {
+                        "name": b.name,
+                        "is_default": b.is_default,
+                        "last_commit": b.last_commit,
+                    }
+                    for b in branches
+                ],
+                default_branch=default_branch,
+            )
+        except RuntimeError as e:
+            logger.error(
+                "Failed to list branches for repo %s: %s",
+                repo_id,
+                str(e),
+                exc_info=True,
+            )
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=str(e)
+            ) from e
+
+    # Local repo missing/corrupt — try remote if available
+    if repo.remote_url:
+        ssh_key = None
+        if repo.ssh_key_id:
+            ssh_key = await session.get(SSHKey, repo.ssh_key_id)
+
+        ssh_result = _prepare_ssh_env(ssh_key)
+        env = None
+        key_path = None
+        if ssh_result:
+            env, key_path = ssh_result
+
+        try:
+            result = subprocess.run(
+                ["git", "ls-remote", "--heads", repo.remote_url],
+                capture_output=True,
+                text=True,
+                timeout=30,
+                env={**os.environ, **env} if env else None,
+            )
+            if result.returncode == 0:
+                remote_branches = []
+                default_branch = "main"
+                for line in result.stdout.strip().split("\n"):
+                    if line:
+                        parts = line.split("\t")
+                        if len(parts) == 2:
+                            ref = parts[1]
+                            if ref.startswith("refs/heads/"):
+                                branch_name = ref[len("refs/heads/") :]
+                                remote_branches.append(branch_name)
+                                if branch_name in ("main", "master"):
+                                    default_branch = branch_name
+                if remote_branches:
+                    return BranchesResponse(
+                        branches=[
+                            {
+                                "name": b,
+                                "is_default": b == default_branch,
+                                "last_commit": None,
+                            }
+                            for b in remote_branches
+                        ],
+                        default_branch=default_branch,
+                    )
+            else:
+                logger.warning(
+                    "ls-remote returned %d for repo %s: %s",
+                    result.returncode,
+                    repo_id,
+                    result.stderr,
+                )
+        except subprocess.TimeoutExpired:
+            logger.warning("ls-remote timed out for repo %s", repo_id)
+        except Exception as e:
+            logger.warning("ls-remote failed for repo %s: %s", repo_id, str(e))
+        finally:
+            if key_path and os.path.exists(key_path):
+                os.unlink(key_path)
+
+    raise HTTPException(
+        status_code=status.HTTP_404_NOT_FOUND,
+        detail="repository not found on disk — re-clone or re-create the repository",
+    )
 
 
 @router.post(
@@ -938,10 +1059,14 @@ async def update_repository_file(
 
     repo = await session.get(GitRepository, repo_id)
     if repo is None or repo.project_id != project_id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="repository not found")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="repository not found"
+        )
 
     if not os.path.exists(repo.path):
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="repository not found on disk")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="repository not found on disk"
+        )
 
     # Get user info for commit
     user = await _get_user(session, user_id)
@@ -1009,10 +1134,14 @@ async def get_repository_status(
 
     repo = await session.get(GitRepository, repo_id)
     if repo is None or repo.project_id != project_id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="repository not found")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="repository not found"
+        )
 
     if not os.path.exists(repo.path):
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="repository not found on disk")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="repository not found on disk"
+        )
 
     try:
         status_result = get_status(repo.path)
@@ -1068,10 +1197,14 @@ async def create_repository_branch(
 
     repo = await session.get(GitRepository, repo_id)
     if repo is None or repo.project_id != project_id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="repository not found")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="repository not found"
+        )
 
     if not os.path.exists(repo.path):
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="repository not found on disk")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="repository not found on disk"
+        )
 
     try:
         create_branch(repo.path, data.name, data.base_branch)
@@ -1111,10 +1244,14 @@ async def delete_repository_branch(
 
     repo = await session.get(GitRepository, repo_id)
     if repo is None or repo.project_id != project_id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="repository not found")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="repository not found"
+        )
 
     if not os.path.exists(repo.path):
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="repository not found on disk")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="repository not found on disk"
+        )
 
     try:
         delete_branch(repo.path, branch_name, force)
@@ -1152,10 +1289,14 @@ async def checkout_repository_branch(
 
     repo = await session.get(GitRepository, repo_id)
     if repo is None or repo.project_id != project_id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="repository not found")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="repository not found"
+        )
 
     if not os.path.exists(repo.path):
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="repository not found on disk")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="repository not found on disk"
+        )
 
     try:
         checkout_branch(repo.path, data.branch)
@@ -1204,10 +1345,14 @@ async def commit_repository_changes(
 
     repo = await session.get(GitRepository, repo_id)
     if repo is None or repo.project_id != project_id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="repository not found")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="repository not found"
+        )
 
     if not os.path.exists(repo.path):
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="repository not found on disk")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="repository not found on disk"
+        )
 
     # Get user info for commit
     user = await _get_user(session, user_id)
@@ -1262,10 +1407,14 @@ async def fetch_repository(
 
     repo = await session.get(GitRepository, repo_id)
     if repo is None or repo.project_id != project_id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="repository not found")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="repository not found"
+        )
 
     if not os.path.exists(repo.path):
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="repository not found on disk")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="repository not found on disk"
+        )
 
     try:
         fetch(repo.path)
@@ -1308,10 +1457,14 @@ async def pull_repository(
 
     repo = await session.get(GitRepository, repo_id)
     if repo is None or repo.project_id != project_id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="repository not found")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="repository not found"
+        )
 
     if not os.path.exists(repo.path):
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="repository not found on disk")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="repository not found on disk"
+        )
 
     try:
         pull(repo.path, branch)
@@ -1354,10 +1507,14 @@ async def push_repository(
 
     repo = await session.get(GitRepository, repo_id)
     if repo is None or repo.project_id != project_id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="repository not found")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="repository not found"
+        )
 
     if not os.path.exists(repo.path):
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="repository not found on disk")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="repository not found on disk"
+        )
 
     try:
         push(repo.path, branch)
@@ -1407,10 +1564,14 @@ async def merge_repository_branches(
 
     repo = await session.get(GitRepository, repo_id)
     if repo is None or repo.project_id != project_id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="repository not found")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="repository not found"
+        )
 
     if not os.path.exists(repo.path):
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="repository not found on disk")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="repository not found on disk"
+        )
 
     try:
         commit_hash = merge(

apps/api/src/api/project/projects.py

@@ -3,42 +3,29 @@ import shutil
 import uuid
 
 from fastapi import APIRouter, Depends, HTTPException, Response, status
-from pydantic import BaseModel, ConfigDict
-from sqlalchemy import select
+from sqlalchemy import func, select
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from src.auth.dependencies import _get_owned_project, _get_user, get_current_user_id, get_db_session
-from src.models.git_repository import GitRepository
+from src.auth.dependencies import (
+    _get_owned_project,
+    _get_user,
+    get_current_user_id,
+    get_db_session,
+)
+from src.models import GitRepository
 from src.models.project import Project
-from src.models.ssh_key import SSHKey
+from src.models import SSHKey
+from src.models import ToolInstance
+from src.schemas.project import (
+    ProjectCreate,
+    ProjectResponse,
+    ProjectUpdate,
+    SetDefaultSSHKeyRequest,
+)
 
 router = APIRouter(prefix="/projects", tags=["projects"])
 
 
-class ProjectCreate(BaseModel):
-    name: str
-    description: str | None = None
-
-
-class ProjectUpdate(BaseModel):
-    name: str | None = None
-    description: str | None = None
-
-
-class ProjectResponse(BaseModel):
-    model_config = ConfigDict(from_attributes=True)
-
-    id: uuid.UUID
-    name: str
-    description: str | None
-    owner_id: uuid.UUID
-    default_ssh_key_id: uuid.UUID | None
-
-
-class SetDefaultSSHKeyRequest(BaseModel):
-    ssh_key_id: uuid.UUID
-
-
 @router.post(
     "",
     response_model=ProjectResponse,
@@ -76,26 +63,77 @@ async def create_project(
 
 @router.get(
     "",
-    response_model=list[ProjectResponse],
     summary="List all projects",
-    description="Retrieve all projects owned by the authenticated user.",
+    description="Retrieve all projects owned by the authenticated user with repositories and workspaces.",
 )
 async def list_projects(
     user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
-) -> list[Project]:
+) -> list[dict]:
     """List all projects for the authenticated user.
 
-    Args:
-        user_id: ID of the authenticated user.
-        session: Database session.
-
-    Returns:
-        List of projects owned by the user.
+    Returns projects with nested repositories and workspaces for inline display.
     """
     user = await _get_user(session, user_id)
-    result = await session.execute(select(Project).where(Project.owner_id == user.id))
-    return list(result.scalars().all())
+    result = await session.execute(
+        select(Project)
+        .where(Project.owner_id == user.id)
+        .order_by(Project.created_at.desc())
+    )
+    projects = result.scalars().all()
+
+    from src.models import Workspace
+
+    enriched = []
+    for project in projects:
+        repos_result = await session.execute(
+            select(GitRepository).where(GitRepository.project_id == project.id)
+        )
+        repositories = []
+        for repo in repos_result.scalars().all():
+            ws_result = await session.execute(
+                select(Workspace).where(Workspace.repo_id == repo.id)
+            )
+            workspaces = []
+            for ws in ws_result.scalars().all():
+                # Count instances
+                inst_result = await session.execute(
+                    select(func.count()).where(ToolInstance.workspace_id == ws.id)
+                )
+                instance_count = inst_result.scalar() or 0
+                workspaces.append(
+                    {
+                        "id": str(ws.id),
+                        "name": ws.name,
+                        "branch": ws.branch,
+                        "status": ws.status,
+                        "instance_count": instance_count,
+                    }
+                )
+
+            repositories.append(
+                {
+                    "id": str(repo.id),
+                    "name": repo.name,
+                    "remote_url": repo.remote_url,
+                    "workspaces": workspaces,
+                }
+            )
+
+        enriched.append(
+            {
+                "id": str(project.id),
+                "name": project.name,
+                "description": project.description,
+                "owner_id": str(project.owner_id),
+                "repositories": repositories,
+                "created_at": project.created_at.isoformat()
+                if project.created_at
+                else None,
+            }
+        )
+
+    return enriched
 
 
 @router.get(
@@ -184,7 +222,9 @@ async def delete_project(
     project = await _get_owned_project(project_id, user_id, session)
 
     # Delete repositories from disk and database
-    result = await session.execute(select(GitRepository).where(GitRepository.project_id == project_id))
+    result = await session.execute(
+        select(GitRepository).where(GitRepository.project_id == project_id)
+    )
     repositories = result.scalars().all()
     for repo in repositories:
         if os.path.exists(repo.path):

apps/api/src/api/system/__init__.py

@@ -0,0 +1,17 @@
+"""System API routers module."""
+
+from src.api.system.dashboard import router as dashboard_router
+from src.api.system.events import router as events_router
+from src.api.system.health import router as health_router
+from src.api.system.instance_proxy import router as instance_proxy_router
+from src.api.system.notifications import router as notifications_router
+from src.api.system.terminal import router as terminal_router
+
+__all__ = [
+    "dashboard_router",
+    "events_router",
+    "health_router",
+    "instance_proxy_router",
+    "notifications_router",
+    "terminal_router",
+]

apps/api/src/api/system/dashboard.py

@@ -5,9 +5,9 @@ from sqlalchemy import func, select
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from src.auth.dependencies import get_current_user_id, get_db_session
-from src.models.git_repository import GitRepository
+from src.models import GitRepository
 from src.models.project import Project
-from src.models.ssh_key import SSHKey
+from src.models import SSHKey
 
 router = APIRouter(prefix="/dashboard", tags=["dashboard"])
 

apps/api/src/api/system/events.py

@@ -0,0 +1,80 @@
+"""SSE streaming endpoint for instance events."""
+
+import asyncio
+import contextlib
+import json
+import uuid
+from collections.abc import AsyncGenerator
+
+from fastapi import APIRouter, Depends, HTTPException, Request, status
+from fastapi.responses import StreamingResponse
+
+from src.auth.dependencies import get_current_user_id
+from src.services.instance.event_bus import InstanceEventBus, InstanceEventPayload
+
+router = APIRouter(prefix="/events", tags=["events"])
+
+# In-memory connection counter per user (single-process assumption)
+_connection_counts: dict[uuid.UUID, int] = {}
+MAX_CONNECTIONS_PER_USER = 20
+
+
+@router.get("/stream")
+async def events_stream(
+    request: Request,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+) -> StreamingResponse:
+    """Stream instance events via Server-Sent Events.
+
+    Enforces a maximum of 5 concurrent connections per user.
+    """
+    current = _connection_counts.get(user_id, 0)
+    if current >= MAX_CONNECTIONS_PER_USER:
+        raise HTTPException(
+            status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+            detail="Too many SSE connections",
+        )
+
+    _connection_counts[user_id] = current + 1
+
+    async def event_generator() -> AsyncGenerator[str, None]:
+        event_bus = InstanceEventBus()
+        queue: asyncio.Queue[InstanceEventPayload] = asyncio.Queue(maxsize=100)
+
+        async def on_event(payload: InstanceEventPayload) -> None:
+            try:
+                queue.put_nowait(payload)
+            except asyncio.QueueFull:
+                # Drop oldest event to make room
+                with contextlib.suppress(asyncio.QueueEmpty):
+                    queue.get_nowait()
+                with contextlib.suppress(asyncio.QueueFull):
+                    queue.put_nowait(payload)
+
+        unsubscribe = event_bus.subscribe("*", on_event)
+
+        try:
+            while True:
+                try:
+                    payload = await asyncio.wait_for(queue.get(), timeout=30.0)
+                    yield f"event: {payload['event']}\ndata: {json.dumps(payload)}\n\n"
+                except asyncio.TimeoutError:
+                    yield ":ping\n\n"
+        except asyncio.CancelledError:
+            # Client disconnected
+            raise
+        finally:
+            unsubscribe()
+            _connection_counts[user_id] = max(0, _connection_counts.get(user_id, 1) - 1)
+            if _connection_counts[user_id] == 0:
+                _connection_counts.pop(user_id, None)
+
+    return StreamingResponse(
+        event_generator(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+            "X-Accel-Buffering": "no",
+        },
+    )

apps/api/src/api/system/health.py

@@ -5,10 +5,16 @@ from datetime import datetime, timezone
 from typing import Any
 
 from fastapi import APIRouter
-from pydantic import BaseModel, Field
 from sqlalchemy import text
 
 from src.database import SessionLocal
+from src.schemas.system import (
+    DatabaseHealth,
+    DatabaseHealthResponse,
+    DiskHealth,
+    HealthChecks,
+    HealthResponse,
+)
 
 router = APIRouter()
 
@@ -16,45 +22,6 @@ router = APIRouter()
 _start_time = time.time()
 
 
-class DatabaseHealth(BaseModel):
-    """Database health check result."""
-
-    status: str = Field(description="Database health status", examples=["healthy"])
-    response_time_ms: float = Field(description="Query response time in milliseconds", examples=[5.2])
-
-
-class DiskHealth(BaseModel):
-    """Disk space health check result."""
-
-    status: str = Field(description="Disk health status", examples=["healthy"])
-    free_gb: float = Field(description="Free disk space in GB", examples=[45.2])
-    total_gb: float = Field(description="Total disk space in GB", examples=[100.0])
-
-
-class HealthChecks(BaseModel):
-    """Individual health checks."""
-
-    database: DatabaseHealth | None = None
-    disk: DiskHealth | None = None
-
-
-class HealthResponse(BaseModel):
-    """Overall health check response."""
-
-    status: str = Field(description="Overall health status", examples=["healthy"])
-    timestamp: str = Field(description="ISO 8601 timestamp", examples=["2026-05-19T12:00:00Z"])
-    version: str = Field(description="API version", examples=["0.1.0"])
-    checks: HealthChecks = Field(description="Individual health checks")
-    uptime_seconds: float = Field(description="Server uptime in seconds", examples=[3600.0])
-
-
-class DatabaseHealthResponse(BaseModel):
-    """Database-specific health check response."""
-
-    status: str = Field(description="Database health status", examples=["healthy"])
-    response_time_ms: float = Field(description="Query response time in milliseconds", examples=[5.2])
-
-
 @router.get(
     "/health",
     response_model=HealthResponse,

apps/api/src/api/system/instance_proxy.py

@@ -8,8 +8,8 @@ from fastapi import APIRouter, Depends, HTTPException, Request, Response, status
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from src.auth.dependencies import get_current_user_id, get_db_session
-from src.models.tool_instance import ToolInstance
-from src.models.tool_type import ToolType
+from src.models import ToolInstance
+from src.models import ToolType
 
 logger = logging.getLogger(__name__)
 

apps/api/src/api/system/notifications.py

@@ -0,0 +1,161 @@
+"""Notification API endpoints."""
+
+import uuid
+from datetime import datetime
+
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+from pydantic import BaseModel, ConfigDict, Field
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from src.auth.dependencies import get_current_user, get_db_session
+from src.models.user import User
+from src.models import UserConfig
+from src.services.shared.notification_service import notification_service
+
+router = APIRouter(prefix="/notifications", tags=["notifications"])
+
+
+class NotificationItem(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: uuid.UUID
+    user_id: uuid.UUID
+    category: str
+    severity: str
+    title: str
+    message: str | None
+    source_type: str | None
+    source_id: uuid.UUID | None
+    notification_metadata: dict = Field(serialization_alias="metadata")
+    read_at: datetime | None
+    dismissed_at: datetime | None
+    created_at: datetime
+
+
+class NotificationListResponse(BaseModel):
+    items: list[NotificationItem]
+    total: int
+    limit: int
+    offset: int
+
+
+class UnreadCountResponse(BaseModel):
+    count: int
+
+
+class MarkAllReadResponse(BaseModel):
+    marked_count: int
+
+
+class ClearAllResponse(BaseModel):
+    cleared_count: int
+
+
+async def _get_mute_categories(
+    session: AsyncSession,
+    user_id: uuid.UUID,
+) -> list[str]:
+    """Read notification mute categories from user config."""
+    from sqlalchemy import select
+
+    result = await session.execute(
+        select(UserConfig).where(UserConfig.user_id == user_id)
+    )
+    config = result.scalar_one_or_none()
+    if config is None:
+        return []
+    mute_categories = config.config.get("notification_mute_categories", [])
+    if isinstance(mute_categories, list):
+        return mute_categories
+    return []
+
+
+@router.get("", response_model=NotificationListResponse)
+async def list_notifications(
+    limit: int = Query(20, ge=1, le=100),
+    offset: int = Query(0, ge=0),
+    unread_only: bool = Query(False),
+    user: User = Depends(get_current_user),
+    session: AsyncSession = Depends(get_db_session),
+) -> NotificationListResponse:
+    """List notifications for the authenticated user."""
+    mute_categories = await _get_mute_categories(session, user.id)
+    items, total = await notification_service.list_notifications(
+        session,
+        user.id,
+        limit=limit,
+        offset=offset,
+        unread_only=unread_only,
+        mute_categories=mute_categories,
+    )
+    return NotificationListResponse(
+        items=[NotificationItem.model_validate(item) for item in items],
+        total=total,
+        limit=limit,
+        offset=offset,
+    )
+
+
+@router.get("/unread", response_model=UnreadCountResponse)
+async def get_unread_count(
+    user: User = Depends(get_current_user),
+    session: AsyncSession = Depends(get_db_session),
+) -> UnreadCountResponse:
+    """Get unread notification count for the authenticated user."""
+    count = await notification_service.get_unread_count(session, user.id)
+    return UnreadCountResponse(count=count)
+
+
+@router.patch("/{notification_id}/read", response_model=NotificationItem)
+async def mark_notification_read(
+    notification_id: uuid.UUID,
+    user: User = Depends(get_current_user),
+    session: AsyncSession = Depends(get_db_session),
+) -> NotificationItem:
+    """Mark a single notification as read."""
+    try:
+        notification = await notification_service.mark_read(
+            session, notification_id, user.id
+        )
+    except ValueError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Notification not found",
+        ) from exc
+    return NotificationItem.model_validate(notification)
+
+
+@router.post("/mark-all-read", response_model=MarkAllReadResponse)
+async def mark_all_read(
+    user: User = Depends(get_current_user),
+    session: AsyncSession = Depends(get_db_session),
+) -> MarkAllReadResponse:
+    """Mark all unread notifications as read."""
+    marked = await notification_service.mark_all_read(session, user.id)
+    return MarkAllReadResponse(marked_count=marked)
+
+
+@router.delete("", status_code=status.HTTP_200_OK)
+async def clear_all_notifications(
+    user: User = Depends(get_current_user),
+    session: AsyncSession = Depends(get_db_session),
+) -> ClearAllResponse:
+    """Dismiss all notifications for the authenticated user."""
+    cleared = await notification_service.dismiss_all(session, user.id)
+    return ClearAllResponse(cleared_count=cleared)
+
+
+@router.delete("/{notification_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def dismiss_notification(
+    notification_id: uuid.UUID,
+    user: User = Depends(get_current_user),
+    session: AsyncSession = Depends(get_db_session),
+) -> None:
+    """Soft-delete (dismiss) a single notification."""
+    try:
+        await notification_service.dismiss(session, notification_id, user.id)
+    except ValueError as exc:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Notification not found",
+        ) from exc

apps/api/src/api/system/terminal.py

@@ -12,10 +12,10 @@ from sqlalchemy.ext.asyncio import AsyncSession
 from starlette.websockets import WebSocketDisconnect
 
 from src.auth.dependencies import get_current_user_id, get_db_session
-from src.models.terminal_session import TerminalSessionModel
-from src.models.tool_instance import ToolInstance
-from src.models.tool_type import ToolType
-from src.services.terminal_manager import MaxSessionsExceededError, terminal_manager
+from src.models import TerminalSessionModel
+from src.models import ToolInstance
+from src.models import ToolType
+from src.services.terminal.terminal_manager import MaxSessionsExceededError, terminal_manager
 
 router = APIRouter()
 logger = logging.getLogger(__name__)
@@ -124,6 +124,21 @@ async def _handle_terminal_websocket(
 
     logger.debug("Terminal auth passed for instance %s, user %s", instance_id, user_id)
 
+    # Verify the container actually exists (may have been removed/recreated)
+    from src.services.docker import get_container_status
+
+    container_status = get_container_status(instance.container_id)
+    if container_status["status"] == "not_found":
+        logger.error(
+            "Container %s for instance %s not found (may have been removed)",
+            instance.container_id,
+            instance_id,
+        )
+        await websocket.close(
+            code=4004, reason="Container not found — restart the tool instance"
+        )
+        return
+
     # Fetch tool type to get startup_command
     tool_type = await db_session.get(ToolType, instance.tool_type_id)
     startup_command = tool_type.startup_command if tool_type else None
@@ -207,8 +222,7 @@ async def _handle_terminal_websocket(
         # Use mutable session reference so loops can survive reset
         session_ref = SessionRef(session, slot_session_id)
 
-        # Start I/O loops and heartbeat
-        read_task = asyncio.create_task(_read_loop(session_ref, websocket))
+        # Start write loop and heartbeat (read is now event-driven in TerminalSession)
         write_task = asyncio.create_task(
             _write_loop(session_ref, websocket, instance_id)
         )
@@ -217,7 +231,7 @@ async def _handle_terminal_websocket(
 
         # Wait for either task to complete (indicating disconnect or error)
         done, pending = await asyncio.wait(
-            [read_task, write_task, heartbeat_task],
+            [write_task, heartbeat_task],
             return_when=asyncio.FIRST_COMPLETED,
         )
 
@@ -252,28 +266,6 @@ async def _handle_terminal_websocket(
                 )
 
 
-async def _read_loop(session_ref: SessionRef, websocket) -> None:
-    """Read output from the container and send to WebSocket."""
-    try:
-        while True:
-            session = session_ref.session
-            if not session.is_alive() or session._closed:
-                await asyncio.sleep(0.1)
-                continue
-            data = await session.read_output()
-            if data:
-                try:
-                    await websocket.send_bytes(data)
-                except WebSocketDisconnect:
-                    break
-                except Exception:
-                    break
-            else:
-                await asyncio.sleep(0.01)
-    except Exception:
-        pass
-
-
 async def _write_loop(session_ref: SessionRef, websocket, instance_id: str) -> None:
     """Read input from WebSocket and send to container."""
     try:
@@ -304,6 +296,10 @@ async def _write_loop(session_ref: SessionRef, websocket, instance_id: str) -> N
                                     rows,
                                 )
                                 await session.resize(cols, rows)
+                            elif msg_type == "ack":
+                                char_count = ctrl.get("chars", 0)
+                                if char_count > 0:
+                                    session.acknowledge_data(char_count)
                             elif msg_type == "reset":
                                 # Reset terminal session (scoped to current slot)
                                 logger.debug(

apps/api/src/api/tool/__init__.py

@@ -0,0 +1,13 @@
+"""Tool API routers module."""
+
+from src.api.tool.sessions import sessions_router
+from src.api.tool.tool_definitions import router as tool_definitions_router
+from src.api.tool.tool_instances import router as tool_instances_router
+from src.api.tool.tool_types import router as tool_types_router
+
+__all__ = [
+    "sessions_router",
+    "tool_definitions_router",
+    "tool_instances_router",
+    "tool_types_router",
+]

apps/api/src/api/tool/sessions.py

@@ -0,0 +1,80 @@
+"""Sessions API endpoints (running instances for current user)."""
+
+import uuid
+
+from fastapi import APIRouter, Depends
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from src.auth.dependencies import _get_user, get_current_user_id, get_db_session
+from src.models import GitRepository
+from src.models import Project
+from src.models import ToolInstance
+from src.models import ToolType
+
+sessions_router = APIRouter(prefix="/users", tags=["sessions"])
+
+
+@sessions_router.get(
+    "/me/sessions",
+    summary="Get user sessions",
+    description="Get all active sessions (running instances) for the current user.",
+)
+async def get_user_sessions(
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Get all active sessions for the current user.
+
+    Args:
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        Dictionary containing list of active sessions with instance details.
+    """
+    _user = await _get_user(session, user_id)
+
+    result = await session.execute(
+        select(ToolInstance)
+        .where(ToolInstance.owner_id == user_id)
+        .where(
+            ToolInstance.status.in_(
+                ["running", "building", "pending", "stopped", "error"]
+            )
+        )
+        .order_by(ToolInstance.created_at.desc())
+    )
+    instances = result.scalars().all()
+
+    sessions = []
+    for instance in instances:
+        tool_type = await session.get(ToolType, instance.tool_type_id)
+        repo = await session.get(GitRepository, instance.repository_id)
+        project = await session.get(Project, instance.project_id)
+
+        sessions.append(
+            {
+                "id": str(instance.id),
+                "display_name": instance.display_name,
+                "tool_type_name": tool_type.name if tool_type else "unknown",
+                "tool_icon": tool_type.name if tool_type else "code",
+                "tool_type_interfaces": [tool_type.interface_type] if tool_type else [],
+                "repository_name": repo.name if repo else "unknown",
+                "repository_id": str(instance.repository_id),
+                "project_name": project.name if project else "unknown",
+                "project_id": str(instance.project_id),
+                "status": instance.status,
+                "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,
+            }
+        )
+
+    return {"sessions": sessions}

apps/api/src/api/tool/tool_definitions.py

@@ -9,9 +9,9 @@ from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from src.auth.dependencies import get_current_user_id, get_db_session
-from src.models.tool_definition_manifest import ToolDefinitionManifest
-from src.models.tool_type import ToolType
-from src.services.manifest_compiler import (
+from src.models import ToolDefinitionManifest
+from src.models import ToolType
+from src.services.build.manifest_compiler import (
     compile_compose,
     compile_dockerfile,
     compile_entrypoint,
@@ -173,7 +173,7 @@ async def list_tool_definitions(
     """
     query = select(ToolDefinitionManifest)
     if not include_bases:
-        query = query.where(ToolDefinitionManifest.is_base == False)
+        query = query.where(ToolDefinitionManifest.is_base.is_(False))
 
     result = await session.execute(
         query.order_by(ToolDefinitionManifest.created_at.desc())

apps/api/src/api/tool/tool_types.py

@@ -1,19 +1,23 @@
 import uuid
-from datetime import datetime
 
 from fastapi import APIRouter, Depends, HTTPException, status
-from pydantic import BaseModel, ConfigDict, field_validator, model_validator
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from src.api.tool_types_validation import (
+from src.api.tool.tool_types_validation import (
     check_port_exposed,
     validate_compose_yaml,
     validate_required_variables,
 )
 from src.auth.dependencies import _get_user, get_current_user_id, get_db_session
-from src.models.tool_type import ToolType
+from src.models import ToolType
 from src.models.user import User
+from src.schemas.tool import (
+    ToolTypeCreate,
+    ToolTypeResponse,
+    ToolTypeUpdate,
+    ToolTypeValidateRequest,
+)
 
 router = APIRouter(prefix="/tool-types", tags=["tool-types"])
 
@@ -29,203 +33,6 @@ async def _require_admin(user: User) -> None:
     pass
 
 
-class ToolTypeCreate(BaseModel):
-    name: str
-    display_name: str
-    description: str | None = None
-    default_port: int = 0
-    definition_type: str = "compose"
-    compose_template: str | None = None
-    dockerfile_template: str | None = None
-    build_context: dict | None = None
-    readiness_probe: dict | None = None
-    startup_command: str | None = None
-    required_variables: list[str] = []
-    category: str = "other"
-    interface_type: str = "web"
-    requires_port: bool = True
-
-    @field_validator("definition_type")
-    @classmethod
-    def validate_definition_type(cls, v: str) -> str:
-        if v not in ("compose", "dockerfile"):
-            raise ValueError("definition_type must be 'compose' or 'dockerfile'")
-        return v
-
-    @field_validator("compose_template")
-    @classmethod
-    def validate_compose_template(cls, v: str | None, info) -> str | None:
-        data = info.data
-        if data.get("definition_type") != "compose":
-            return v
-        
-        if v is None:
-            raise ValueError("compose_template is required when definition_type is 'compose'")
-        
-        validate_compose_yaml(v)
-        return v
-
-    @field_validator("dockerfile_template")
-    @classmethod
-    def validate_dockerfile_template(cls, v: str | None, info) -> str | None:
-        data = info.data
-        if data.get("definition_type") != "dockerfile":
-            return v
-        
-        if v is None:
-            raise ValueError("dockerfile_template is required when definition_type is 'dockerfile'")
-        
-        if not v.strip().startswith("FROM"):
-            raise ValueError("Dockerfile must start with a FROM instruction")
-        
-        return v
-
-    @field_validator("interface_type")
-    @classmethod
-    def validate_interface_type(cls, v: str) -> str:
-        if v not in ("web", "terminal"):
-            raise ValueError("interface_type must be 'web' or 'terminal'")
-        return v
-
-    @field_validator("default_port")
-    @classmethod
-    def validate_default_port(cls, v: int, info) -> int:
-        data = info.data
-        requires_port = data.get("requires_port", True)
-        if not requires_port:
-            return v
-        if v <= 0 or v > 65535:
-            raise ValueError("Port must be between 1 and 65535")
-        return v
-
-    @field_validator("required_variables")
-    @classmethod
-    def validate_required_variables(cls, v: list[str], info) -> list[str]:
-        if not v:
-            return v
-        
-        data = info.data
-        if data.get("definition_type") != "compose":
-            return v
-        
-        template = data.get("compose_template")
-        if not template:
-            return v
-        
-        for var in v:
-            placeholder = f"{{{{{var}}}}}"
-            if placeholder not in template:
-                raise ValueError(f"Required variable '{var}' not found in compose template")
-        
-        return v
-
-    @model_validator(mode="after")
-    def validate_templates(self) -> "ToolTypeCreate":
-        if self.definition_type == "dockerfile" and self.dockerfile_template is None:
-            raise ValueError("dockerfile_template is required when definition_type is 'dockerfile'")
-        if self.definition_type == "compose" and self.compose_template is None:
-            raise ValueError("compose_template is required when definition_type is 'compose'")
-        
-        # Validate that default_port is exposed in compose template (only if requires_port)
-        if self.requires_port and self.definition_type == "compose" and self.compose_template:
-            try:
-                parsed = validate_compose_yaml(self.compose_template)
-            except ValueError:
-                return self
-            
-            if not check_port_exposed(parsed, self.default_port):
-                raise ValueError(f"Port {self.default_port} is not exposed in the compose template. Add it to the 'ports' section.")
-        
-        return self
-
-
-class ToolTypeUpdate(BaseModel):
-    display_name: str | None = None
-    description: str | None = None
-    default_port: int | None = None
-    definition_type: str | None = None
-    compose_template: str | None = None
-    dockerfile_template: str | None = None
-    build_context: dict | None = None
-    readiness_probe: dict | None = None
-    startup_command: str | None = None
-    required_variables: list[str] | None = None
-    category: str | None = None
-    interface_type: str | None = None
-    requires_port: bool | None = None
-
-    @field_validator("definition_type")
-    @classmethod
-    def validate_definition_type(cls, v: str | None) -> str | None:
-        if v is None:
-            return v
-        if v not in ("compose", "dockerfile"):
-            raise ValueError("definition_type must be 'compose' or 'dockerfile'")
-        return v
-
-    @field_validator("interface_type")
-    @classmethod
-    def validate_interface_type(cls, v: str | None) -> str | None:
-        if v is None:
-            return v
-        if v not in ("web", "terminal"):
-            raise ValueError("interface_type must be 'web' or 'terminal'")
-        return v
-
-    @field_validator("compose_template")
-    @classmethod
-    def validate_compose_template(cls, v: str | None, info) -> str | None:
-        if v is None:
-            return v
-
-        data = info.data
-        definition_type = data.get("definition_type")
-        if definition_type and definition_type != "compose":
-            return v
-
-        validate_compose_yaml(v)
-        return v
-
-    @field_validator("dockerfile_template")
-    @classmethod
-    def validate_dockerfile_template(cls, v: str | None, info) -> str | None:
-        if v is None:
-            return v
-        
-        data = info.data
-        definition_type = data.get("definition_type")
-        if definition_type and definition_type != "dockerfile":
-            return v
-        
-        if not v.strip().startswith("FROM"):
-            raise ValueError("Dockerfile must start with a FROM instruction")
-        
-        return v
-
-
-class ToolTypeResponse(BaseModel):
-    model_config = ConfigDict(from_attributes=True)
-
-    id: uuid.UUID
-    name: str
-    display_name: str
-    description: str | None
-    category: str
-    interface_type: str
-    requires_port: bool
-    default_port: int
-    definition_type: str
-    compose_template: str | None
-    dockerfile_template: str | None
-    build_context: dict | None
-    readiness_probe: dict | None
-    startup_command: str | None
-    required_variables: list[str]
-    created_by_id: uuid.UUID | None
-    created_at: datetime
-    updated_at: datetime
-
-
 @router.post(
     "",
     response_model=ToolTypeResponse,
@@ -250,18 +57,22 @@ async def create_tool_type(
     """
     user = await _get_user(session, user_id)
     await _require_admin(user)
-    
+
     # Check for duplicate name
     existing = await session.scalar(select(ToolType).where(ToolType.name == data.name))
     if existing:
-        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="tool type with this name already exists")
-    
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail="tool type with this name already exists",
+        )
+
     tool_type = ToolType(
         name=data.name,
         display_name=data.display_name,
         description=data.description,
         default_port=data.default_port,
         definition_type=data.definition_type,
+        manifest_id=data.manifest_id,
         compose_template=data.compose_template,
         dockerfile_template=data.dockerfile_template,
         build_context=data.build_context,
@@ -327,7 +138,9 @@ async def get_tool_type(
     await _get_user(session, user_id)
     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")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="tool type not found"
+        )
     return tool_type
 
 
@@ -356,15 +169,17 @@ async def update_tool_type(
     """
     user = await _get_user(session, user_id)
     await _require_admin(user)
-    
+
     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")
-    
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="tool type not found"
+        )
+
     # Built-in tool types can now be modified
-    
+
     update_data = data.model_dump(exclude_unset=True)
-    
+
     # Validate port if being updated
     requires_port = update_data.get("requires_port", tool_type.requires_port)
     if "default_port" in update_data and requires_port:
@@ -372,9 +187,9 @@ async def update_tool_type(
         if new_port <= 0 or new_port > 65535:
             raise HTTPException(
                 status_code=status.HTTP_400_BAD_REQUEST,
-                detail="Port must be between 1 and 65535"
+                detail="Port must be between 1 and 65535",
             )
-        
+
         # Only validate port exposure for compose definitions
         definition_type = update_data.get("definition_type", tool_type.definition_type)
         if definition_type == "compose":
@@ -385,12 +200,11 @@ async def update_tool_type(
                     if not check_port_exposed(parsed, new_port):
                         raise HTTPException(
                             status_code=status.HTTP_400_BAD_REQUEST,
-                            detail=f"Port {new_port} is not exposed in the compose template"
+                            detail=f"Port {new_port} is not exposed in the compose template",
                         )
                 except ValueError as e:
                     raise HTTPException(
-                        status_code=status.HTTP_400_BAD_REQUEST,
-                        detail=str(e)
+                        status_code=status.HTTP_400_BAD_REQUEST, detail=str(e)
                     )
 
     # Validate required variables for compose definitions
@@ -404,21 +218,22 @@ async def update_tool_type(
             template = tool_type.compose_template
             if template:
                 validate_required_variables(template, update_data["required_variables"])
-    
+
+    # When switching to manifest, clear legacy templates
+    if definition_type == "manifest":
+        if "manifest_id" in update_data:
+            tool_type.manifest_id = update_data["manifest_id"]
+        tool_type.compose_template = None
+        tool_type.dockerfile_template = None
+
     for field, value in update_data.items():
         setattr(tool_type, field, value)
-    
+
     await session.commit()
     await session.refresh(tool_type)
     return tool_type
 
 
-class ToolTypeValidateRequest(BaseModel):
-    definition_type: str
-    compose_template: str | None = None
-    dockerfile_template: str | None = None
-
-
 @router.post(
     "/validate",
     summary="Validate tool type template",
@@ -458,8 +273,11 @@ async def validate_tool_type_template(
         elif not data.dockerfile_template.strip().startswith("FROM"):
             errors.append("Dockerfile must start with a FROM instruction")
 
+    elif data.definition_type == "manifest":
+        pass  # Manifest validation is handled separately
+
     else:
-        errors.append("definition_type must be 'compose' or 'dockerfile'")
+        errors.append("definition_type must be 'compose', 'dockerfile', or 'manifest'")
 
     return {
         "valid": len(errors) == 0,
@@ -490,10 +308,12 @@ async def validate_tool_type(
     await _get_user(session, user_id)
     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")
-    
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="tool type not found"
+        )
+
     errors = []
-    
+
     if tool_type.definition_type == "compose":
         if not tool_type.compose_template:
             errors.append("Compose template is empty")
@@ -502,13 +322,17 @@ async def validate_tool_type(
                 validate_compose_yaml(tool_type.compose_template)
             except ValueError as e:
                 errors.append(str(e))
-    
+
     elif tool_type.definition_type == "dockerfile":
         if not tool_type.dockerfile_template:
             errors.append("Dockerfile template is empty")
         elif not tool_type.dockerfile_template.strip().startswith("FROM"):
             errors.append("Dockerfile must start with a FROM instruction")
-    
+
+    elif tool_type.definition_type == "manifest":
+        if not tool_type.manifest_id:
+            errors.append("Manifest reference is missing")
+
     return {
         "valid": len(errors) == 0,
         "errors": errors,
@@ -538,12 +362,14 @@ async def delete_tool_type(
     """
     user = await _get_user(session, user_id)
     await _require_admin(user)
-    
+
     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")
-    
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="tool type not found"
+        )
+
     # Built-in tool types can now be deleted
-    
+
     await session.delete(tool_type)
     await session.commit()

apps/api/src/api/user/__init__.py

@@ -0,0 +1,7 @@
+"""User API routers module."""
+
+from src.api.user.auth import router as auth_router
+from src.api.user.ssh_keys import router as ssh_keys_router
+from src.api.user.users import router as users_router
+
+__all__ = ["auth_router", "ssh_keys_router", "users_router"]

apps/api/src/api/user/ssh_keys.py

@@ -1,18 +1,24 @@
 import base64
 import uuid
-from datetime import datetime
 
 from cryptography.fernet import Fernet
 from cryptography.hazmat.primitives import serialization
 from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
 from fastapi import APIRouter, Depends, HTTPException, status
-from pydantic import BaseModel, ConfigDict
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from src.auth.dependencies import _get_user, get_current_user_id, get_db_session
 from src.config import Settings
-from src.models.ssh_key import SSHKey
+from src.models import SSHKey
+from src.schemas.project import (
+    SSHKeyCreate,
+    SSHKeyResponse,
+    SignPayloadRequest,
+    SignatureResponse,
+    VerifySignatureRequest,
+    VerifySignatureResponse,
+)
 
 router = APIRouter(prefix="/ssh-keys", tags=["ssh-keys"])
 
@@ -21,7 +27,7 @@ def _get_fernet() -> Fernet:
     """Generate a valid Fernet key from the session secret."""
     import base64
     import hashlib
-    
+
     settings = Settings()
     # Derive a 32-byte key from the session secret using SHA256
     key_bytes = hashlib.sha256(settings.session_secret.encode()).digest()
@@ -53,36 +59,6 @@ def generate_ssh_key_pair() -> tuple[str, str]:
     return private_bytes.decode("utf-8"), public_bytes.decode("utf-8")
 
 
-class SSHKeyCreate(BaseModel):
-    name: str
-
-
-class SSHKeyResponse(BaseModel):
-    model_config = ConfigDict(from_attributes=True)
-
-    id: uuid.UUID
-    name: str
-    public_key: str
-    created_at: datetime
-
-
-class SignPayloadRequest(BaseModel):
-    payload: str
-
-
-class SignatureResponse(BaseModel):
-    signature: str
-
-
-class VerifySignatureRequest(BaseModel):
-    payload: str
-    signature: str
-
-
-class VerifySignatureResponse(BaseModel):
-    valid: bool
-
-
 @router.post(
     "",
     response_model=SSHKeyResponse,
@@ -171,7 +147,9 @@ async def delete_ssh_key(
     user = await _get_user(session, user_id)
     ssh_key = await session.get(SSHKey, key_id)
     if ssh_key is None or ssh_key.user_id != user.id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="ssh key not found")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="ssh key not found"
+        )
 
     await session.delete(ssh_key)
     await session.commit()
@@ -203,7 +181,9 @@ async def sign_payload(
     user = await _get_user(session, user_id)
     ssh_key = await session.get(SSHKey, key_id)
     if ssh_key is None or ssh_key.user_id != user.id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="ssh key not found")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="ssh key not found"
+        )
 
     fernet = _get_fernet()
     private_key_pem = fernet.decrypt(ssh_key.private_key_encrypted.encode()).decode()
@@ -242,7 +222,9 @@ async def verify_signature(
     user = await _get_user(session, user_id)
     ssh_key = await session.get(SSHKey, key_id)
     if ssh_key is None or ssh_key.user_id != user.id:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="ssh key not found")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="ssh key not found"
+        )
 
     public_key = serialization.load_ssh_public_key(ssh_key.public_key.encode())
 

apps/api/src/api/user/users.py

@@ -2,11 +2,11 @@ import uuid
 from pathlib import Path
 
 from fastapi import APIRouter, Depends, HTTPException, UploadFile, status
-from pydantic import BaseModel, ConfigDict
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from src.auth.dependencies import _get_user, get_current_user_id, get_db_session
 from src.models.user import User
+from src.schemas.user import UserProfileResponse, UserProfileUpdate
 
 router = APIRouter(prefix="/users", tags=["users"])
 
@@ -16,20 +16,6 @@ ALLOWED_CONTENT_TYPES = {"image/png", "image/jpeg", "image/jpg"}
 MAX_AVATAR_SIZE = 2 * 1024 * 1024  # 2MB
 
 
-class UserProfileResponse(BaseModel):
-    model_config = ConfigDict(from_attributes=True)
-
-    id: uuid.UUID
-    email: str
-    name: str
-    avatar_url: str | None
-
-
-class UserProfileUpdate(BaseModel):
-    name: str | None = None
-    email: str | None = None
-
-
 @router.get(
     "/me",
     response_model=UserProfileResponse,
@@ -77,12 +63,16 @@ async def update_profile(
 
     if data.name is not None:
         if len(data.name.strip()) == 0:
-            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="name cannot be empty")
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST, detail="name cannot be empty"
+            )
         user.name = data.name.strip()
 
     if data.email is not None:
         if "@" not in data.email:
-            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="invalid email")
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST, detail="invalid email"
+            )
         user.email = data.email.strip()
 
     await session.commit()

apps/api/src/api/workspace/__init__.py

@@ -0,0 +1,17 @@
+"""Workspace API routers module."""
+
+from src.api.workspace.workspace_files import router as workspace_files_router
+from src.api.workspace.workspace_git import router as workspace_git_router
+from src.api.workspace.workspace_instances import router as workspace_instances_router
+from src.api.workspace.workspaces import (
+    all_workspaces_router,
+    router as workspaces_router,
+)
+
+__all__ = [
+    "all_workspaces_router",
+    "workspace_files_router",
+    "workspace_git_router",
+    "workspace_instances_router",
+    "workspaces_router",
+]

apps/api/src/api/workspace/workspace_files.py

@@ -0,0 +1,114 @@
+"""Workspace file API endpoints."""
+
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from src.auth.dependencies import get_current_user_id, get_db_session
+from src.models import Workspace
+from src.services.shared.file_service import FileService
+
+router = APIRouter(prefix="/workspaces/{workspace_id}/files")
+
+
+async def _get_workspace(
+    session: AsyncSession,
+    workspace_id: uuid.UUID,
+    user_id: uuid.UUID,
+) -> Workspace:
+    from sqlalchemy import select
+
+    result = await session.execute(
+        select(Workspace).where(
+            Workspace.id == workspace_id,
+            Workspace.user_id == user_id,
+        )
+    )
+    workspace = result.scalar_one_or_none()
+    if not workspace:
+        raise HTTPException(status_code=404, detail="Workspace not found")
+    return workspace
+
+
+@router.get("/")
+async def list_files(
+    workspace_id: uuid.UUID,
+    path: str = "",
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """List files in a workspace directory."""
+    workspace = await _get_workspace(session, workspace_id, user_id)
+    service = FileService()
+    try:
+        entries = service.list_directory(workspace, path)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    return {
+        "entries": [
+            {
+                "name": e.name,
+                "path": e.path,
+                "type": e.type,
+                "size": e.size,
+            }
+            for e in entries
+        ],
+    }
+
+
+@router.get("/content")
+async def get_file_content(
+    workspace_id: uuid.UUID,
+    path: str,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Get the content of a text file."""
+    workspace = await _get_workspace(session, workspace_id, user_id)
+    service = FileService()
+    try:
+        content = service.read_file(workspace, path)
+    except FileNotFoundError as exc:
+        raise HTTPException(status_code=404, detail=str(exc)) from exc
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    return {"content": content, "path": path}
+
+
+@router.post("/content")
+async def write_file(
+    workspace_id: uuid.UUID,
+    data: dict,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Write a file and optionally commit."""
+    workspace = await _get_workspace(session, workspace_id, user_id)
+    service = FileService()
+
+    file_path = data.get("path", "").strip()
+    content = data.get("content", "")
+    commit_message = data.get("message", "").strip()
+
+    if not file_path:
+        raise HTTPException(status_code=400, detail="File path is required")
+
+    try:
+        service.write_file(workspace, file_path, content)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    if commit_message:
+        from src.services.git.git_operations import GitOperations
+
+        git = GitOperations(workspace)
+        try:
+            await git.commit(commit_message)
+        except RuntimeError as exc:
+            raise HTTPException(status_code=500, detail=str(exc)) from exc
+
+    return {"status": "saved", "path": file_path}

apps/api/src/api/workspace/workspace_git.py

@@ -0,0 +1,203 @@
+"""Workspace git API endpoints."""
+
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from src.auth.dependencies import get_current_user_id, get_db_session
+from src.models import Workspace
+from src.services.git.git_operations import GitOperations
+
+router = APIRouter(prefix="/workspaces/{workspace_id}/git")
+
+
+async def _get_workspace(
+    session: AsyncSession,
+    workspace_id: uuid.UUID,
+    user_id: uuid.UUID,
+) -> Workspace:
+    from sqlalchemy import select
+
+    result = await session.execute(
+        select(Workspace).where(
+            Workspace.id == workspace_id,
+            Workspace.user_id == user_id,
+        )
+    )
+    workspace = result.scalar_one_or_none()
+    if not workspace:
+        raise HTTPException(status_code=404, detail="Workspace not found")
+    return workspace
+
+
+@router.get("/status")
+async def git_status(
+    workspace_id: uuid.UUID,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Get git status for the workspace."""
+    workspace = await _get_workspace(session, workspace_id, user_id)
+    git = GitOperations(workspace)
+    try:
+        status = await git.status()
+    except RuntimeError as exc:
+        raise HTTPException(status_code=500, detail=str(exc)) from exc
+
+    return {
+        "branch": status.branch,
+        "modified": status.modified,
+        "added": status.added,
+        "deleted": status.deleted,
+        "untracked": status.untracked,
+        "ahead": status.ahead,
+        "behind": status.behind,
+    }
+
+
+@router.get("/branches")
+async def git_branches(
+    workspace_id: uuid.UUID,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """List branches for the workspace."""
+    workspace = await _get_workspace(session, workspace_id, user_id)
+    git = GitOperations(workspace)
+    try:
+        branches, current = await git.branches()
+    except RuntimeError as exc:
+        raise HTTPException(status_code=500, detail=str(exc)) from exc
+
+    return {
+        "branches": branches,
+        "current_branch": current,
+    }
+
+
+@router.post("/commit")
+async def git_commit(
+    workspace_id: uuid.UUID,
+    data: dict,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Stage all changes and commit."""
+    workspace = await _get_workspace(session, workspace_id, user_id)
+    message = data.get("message", "").strip()
+    if not message:
+        raise HTTPException(status_code=400, detail="Commit message is required")
+
+    git = GitOperations(workspace)
+    try:
+        await git.commit(message)
+    except RuntimeError as exc:
+        raise HTTPException(status_code=500, detail=str(exc)) from exc
+
+    return {"status": "committed"}
+
+
+@router.post("/push")
+async def git_push(
+    workspace_id: uuid.UUID,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Push current branch."""
+    workspace = await _get_workspace(session, workspace_id, user_id)
+    git = GitOperations(workspace)
+    try:
+        await git.push()
+    except RuntimeError as exc:
+        raise HTTPException(status_code=500, detail=str(exc)) from exc
+
+    return {"status": "pushed"}
+
+
+@router.post("/pull")
+async def git_pull(
+    workspace_id: uuid.UUID,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Pull current branch."""
+    workspace = await _get_workspace(session, workspace_id, user_id)
+    git = GitOperations(workspace)
+    try:
+        await git.pull()
+    except RuntimeError as exc:
+        raise HTTPException(status_code=500, detail=str(exc)) from exc
+
+    return {"status": "pulled"}
+
+
+@router.post("/fetch")
+async def git_fetch(
+    workspace_id: uuid.UUID,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Fetch from origin."""
+    workspace = await _get_workspace(session, workspace_id, user_id)
+    git = GitOperations(workspace)
+    try:
+        await git.fetch()
+    except RuntimeError as exc:
+        raise HTTPException(status_code=500, detail=str(exc)) from exc
+
+    return {"status": "fetched"}
+
+
+@router.post("/checkout")
+async def git_checkout(
+    workspace_id: uuid.UUID,
+    data: dict,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Checkout a branch."""
+    workspace = await _get_workspace(session, workspace_id, user_id)
+    branch = data.get("branch", "").strip()
+    if not branch:
+        raise HTTPException(status_code=400, detail="Branch name is required")
+
+    git = GitOperations(workspace)
+    try:
+        await git.checkout(branch)
+    except RuntimeError as exc:
+        raise HTTPException(status_code=500, detail=str(exc)) from exc
+
+    workspace.branch = branch
+    await session.commit()
+
+    return {"status": "checked_out", "branch": branch}
+
+
+@router.get("/history")
+async def git_history(
+    workspace_id: uuid.UUID,
+    path: str | None = None,
+    limit: int = 50,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Get commit history."""
+    workspace = await _get_workspace(session, workspace_id, user_id)
+    git = GitOperations(workspace)
+    try:
+        commits = await git.history(path, limit)
+    except RuntimeError as exc:
+        raise HTTPException(status_code=500, detail=str(exc)) from exc
+
+    return {
+        "commits": [
+            {
+                "hash": c.hash,
+                "message": c.message,
+                "author": c.author,
+                "date": c.date,
+            }
+            for c in commits
+        ],
+    }

apps/api/src/api/workspace/workspace_instances.py

@@ -0,0 +1,60 @@
+"""Workspace instance API endpoints."""
+
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from src.auth.dependencies import get_current_user_id, get_db_session
+from src.models import ToolInstance
+from src.models import Workspace
+
+router = APIRouter(prefix="/workspaces/{workspace_id}/instances")
+
+
+async def _get_workspace(
+    session: AsyncSession,
+    workspace_id: uuid.UUID,
+    user_id: uuid.UUID,
+) -> Workspace:
+    result = await session.execute(
+        select(Workspace).where(
+            Workspace.id == workspace_id,
+            Workspace.user_id == user_id,
+        )
+    )
+    workspace = result.scalar_one_or_none()
+    if not workspace:
+        raise HTTPException(status_code=404, detail="Workspace not found")
+    return workspace
+
+
+@router.get("/")
+async def list_workspace_instances(
+    workspace_id: uuid.UUID,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> list[dict]:
+    """List tool instances using this workspace."""
+    await _get_workspace(session, workspace_id, user_id)
+    result = await session.execute(
+        select(ToolInstance)
+        .where(ToolInstance.workspace_id == workspace_id)
+        .order_by(ToolInstance.created_at.desc())
+    )
+    instances = result.scalars().all()
+
+    return [
+        {
+            "id": str(i.id),
+            "name": i.name,
+            "display_name": i.display_name,
+            "status": i.status,
+            "tool_type_id": str(i.tool_type_id),
+            "url": i.url,
+            "port": i.port,
+            "created_at": i.created_at.isoformat() if i.created_at else None,
+        }
+        for i in instances
+    ]

apps/api/src/api/workspace/workspaces.py

@@ -0,0 +1,450 @@
+"""Workspace CRUD API endpoints."""
+
+import logging
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+from sqlalchemy import func, 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 import GitRepository
+from src.models import ToolInstance
+from src.models import Workspace
+from src.services.shared.workspace_manager import WorkspaceHasInstancesError, WorkspaceManager
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/projects/{project_id}/repositories/{repo_id}/workspaces")
+all_workspaces_router = APIRouter(prefix="/workspaces")
+
+
+@all_workspaces_router.get("/")
+async def list_all_workspaces(
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> list[dict]:
+    """List all workspaces for the current user across all repos."""
+    instance_count = (
+        select(func.count(ToolInstance.id))
+        .where(ToolInstance.workspace_id == Workspace.id)
+        .correlate(Workspace)
+        .scalar_subquery()
+    )
+
+    result = await session.execute(
+        select(
+            Workspace,
+            GitRepository.name.label("repo_name"),
+            GitRepository.project_id,
+            GitRepository.ssh_key_id.label("repo_ssh_key_id"),
+            instance_count.label("instance_count"),
+        )
+        .join(GitRepository, Workspace.repo_id == GitRepository.id)
+        .where(Workspace.user_id == user_id)
+        .order_by(Workspace.created_at.desc())
+    )
+    rows = result.all()
+
+    return [
+        {
+            "id": str(ws.id),
+            "name": ws.name,
+            "repo_id": str(ws.repo_id),
+            "repo_name": repo_name or "",
+            "repo_ssh_key_id": str(ssh_key_id) if ssh_key_id else None,
+            "project_id": str(project_id) if project_id else "",
+            "project_name": "",
+            "user_id": str(ws.user_id),
+            "branch": ws.branch,
+            "path": ws.path,
+            "status": ws.status,
+            "last_sync_at": ws.last_sync_at.isoformat() if ws.last_sync_at else None,
+            "created_at": ws.created_at.isoformat() if ws.created_at else None,
+            "updated_at": ws.updated_at.isoformat() if ws.updated_at else None,
+            "instance_count": count or 0,
+        }
+        for ws, repo_name, project_id, ssh_key_id, count in rows
+    ]
+
+
+@all_workspaces_router.delete("/{workspace_id}")
+async def delete_workspace_top_level(
+    workspace_id: uuid.UUID,
+    force: bool = Query(False),
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Delete a workspace via top-level path."""
+    workspace = await session.get(Workspace, workspace_id)
+    if not workspace or workspace.user_id != user_id:
+        raise HTTPException(status_code=404, detail="Workspace not found")
+
+    manager = WorkspaceManager()
+    try:
+        await manager.delete(workspace, force=force, session=session)
+        await session.commit()
+    except WorkspaceHasInstancesError as exc:
+        await session.rollback()
+        raise HTTPException(
+            status_code=409,
+            detail={
+                "message": "Workspace has running tool instances",
+                "instances": exc.instances,
+            },
+        ) from exc
+    except Exception as exc:
+        await session.rollback()
+        logger.error("Failed to delete workspace: %s", exc)
+        raise HTTPException(
+            status_code=500, detail="Failed to delete workspace"
+        ) from exc
+
+    return {"status": "deleted"}
+
+
+@all_workspaces_router.post("/")
+async def create_workspace_top_level(
+    data: dict,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Create a workspace directly (no nested project/repo path)."""
+    repo_id_str = data.get("repo_id", "").strip()
+    if not repo_id_str:
+        raise HTTPException(status_code=400, detail="repo_id is required")
+
+    try:
+        repo_id = uuid.UUID(repo_id_str)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail="Invalid repo_id format") from exc
+
+    repo = await session.get(GitRepository, repo_id)
+    if not repo or repo.owner_id != user_id:
+        raise HTTPException(status_code=404, detail="Repository not found")
+
+    name = data.get("name", "").strip()
+    branch = data.get("branch", "main").strip()
+
+    if not name:
+        raise HTTPException(status_code=400, detail="Workspace name is required")
+
+    manager = WorkspaceManager()
+    try:
+        workspace = await manager.create(repo, user_id, name, branch, session=session)
+        session.add(workspace)
+        await session.commit()
+    except Exception as exc:
+        await session.rollback()
+        logger.error("Failed to create workspace: %s", exc)
+        raise HTTPException(
+            status_code=409,
+            detail="Workspace name already exists for this repository",
+        ) from exc
+
+    await session.refresh(workspace)
+    return {
+        "id": str(workspace.id),
+        "name": workspace.name,
+        "repo_id": str(workspace.repo_id),
+        "branch": workspace.branch,
+        "path": workspace.path,
+        "status": workspace.status,
+        "created_at": workspace.created_at.isoformat()
+        if workspace.created_at
+        else None,
+    }
+
+
+@router.get("/")
+async def list_workspaces(
+    project_id: uuid.UUID,
+    repo_id: uuid.UUID,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> list[dict]:
+    """List workspaces for a repository, with instance counts."""
+    # Verify repo belongs to project and user
+    repo = await _get_repo(session, repo_id, project_id, user_id)
+
+    # Build subquery for instance counts
+    instance_count = (
+        select(func.count(ToolInstance.id))
+        .where(ToolInstance.workspace_id == Workspace.id)
+        .correlate(Workspace)
+        .scalar_subquery()
+    )
+
+    result = await session.execute(
+        select(
+            Workspace,
+            instance_count.label("instance_count"),
+        )
+        .where(Workspace.repo_id == repo_id)
+        .order_by(Workspace.created_at.desc())
+    )
+    rows = result.all()
+
+    return [
+        {
+            "id": str(ws.id),
+            "name": ws.name,
+            "repo_id": str(ws.repo_id),
+            "repo_name": repo.name,
+            "repo_ssh_key_id": str(repo.ssh_key_id) if repo.ssh_key_id else None,
+            "project_id": str(repo.project_id) if repo.project_id else "",
+            "project_name": repo.project.name if repo.project else "",
+            "user_id": str(ws.user_id),
+            "branch": ws.branch,
+            "path": ws.path,
+            "status": ws.status,
+            "last_sync_at": ws.last_sync_at.isoformat() if ws.last_sync_at else None,
+            "created_at": ws.created_at.isoformat() if ws.created_at else None,
+            "updated_at": ws.updated_at.isoformat() if ws.updated_at else None,
+            "instance_count": count or 0,
+        }
+        for ws, count in rows
+    ]
+
+
+@router.post("/")
+async def create_workspace(
+    project_id: uuid.UUID,
+    repo_id: uuid.UUID,
+    data: dict,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Create a new workspace by cloning a repository branch."""
+    repo = await _get_repo(session, repo_id, project_id, user_id)
+
+    name = data.get("name", "").strip()
+    branch = data.get("branch", "main").strip()
+
+    if not name:
+        raise HTTPException(status_code=400, detail="Workspace name is required")
+    if not branch:
+        raise HTTPException(status_code=400, detail="Branch is required")
+
+    manager = WorkspaceManager()
+    try:
+        workspace = await manager.create(repo, user_id, name, branch, session=session)
+        session.add(workspace)
+        await session.commit()
+    except HTTPException:
+        raise
+    except ValueError as exc:
+        await session.rollback()
+        logger.error("Failed to create workspace: %s", exc)
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    except Exception as exc:
+        await session.rollback()
+        logger.error("Failed to create workspace: %s", exc)
+        raise HTTPException(
+            status_code=409,
+            detail="Workspace name already exists for this repository",
+        ) from exc
+
+    await session.refresh(workspace)
+    return {
+        "id": str(workspace.id),
+        "name": workspace.name,
+        "repo_id": str(workspace.repo_id),
+        "branch": workspace.branch,
+        "path": workspace.path,
+        "status": workspace.status,
+        "created_at": workspace.created_at.isoformat()
+        if workspace.created_at
+        else None,
+    }
+
+
+@router.get("/{workspace_id}")
+async def get_workspace_detail(
+    project_id: uuid.UUID,
+    repo_id: uuid.UUID,
+    workspace_id: uuid.UUID,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Get workspace details."""
+    repo = await _get_repo(session, repo_id, project_id, user_id)
+    workspace = await _get_workspace(session, workspace_id, repo_id)
+
+    # Count instances
+    result = await session.execute(
+        select(func.count(ToolInstance.id)).where(
+            ToolInstance.workspace_id == workspace_id
+        )
+    )
+    instance_count = result.scalar() or 0
+
+    return {
+        "id": str(workspace.id),
+        "name": workspace.name,
+        "repo_id": str(workspace.repo_id),
+        "repo_name": repo.name,
+        "user_id": str(workspace.user_id),
+        "branch": workspace.branch,
+        "path": workspace.path,
+        "status": workspace.status,
+        "last_sync_at": workspace.last_sync_at.isoformat()
+        if workspace.last_sync_at
+        else None,
+        "created_at": workspace.created_at.isoformat()
+        if workspace.created_at
+        else None,
+        "updated_at": workspace.updated_at.isoformat()
+        if workspace.updated_at
+        else None,
+        "instance_count": instance_count,
+    }
+
+
+@router.patch("/{workspace_id}")
+async def update_workspace(
+    project_id: uuid.UUID,
+    repo_id: uuid.UUID,
+    workspace_id: uuid.UUID,
+    data: dict,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Update workspace name or branch."""
+    await _get_repo(session, repo_id, project_id, user_id)
+    workspace = await _get_workspace(session, workspace_id, repo_id)
+
+    new_name = data.get("name", "").strip()
+    new_branch = data.get("branch", "").strip()
+
+    if new_name:
+        workspace.name = new_name
+    if new_branch:
+        workspace.branch = new_branch
+
+    try:
+        await session.commit()
+    except Exception as exc:
+        await session.rollback()
+        logger.error("Failed to update workspace: %s", exc)
+        raise HTTPException(
+            status_code=409,
+            detail="Workspace name already exists for this repository",
+        ) from exc
+
+    return {
+        "id": str(workspace.id),
+        "name": workspace.name,
+        "branch": workspace.branch,
+        "status": workspace.status,
+    }
+
+
+@router.delete("/{workspace_id}")
+async def delete_workspace(
+    project_id: uuid.UUID,
+    repo_id: uuid.UUID,
+    workspace_id: uuid.UUID,
+    force: bool = Query(False),
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Delete a workspace. Returns 409 if instances exist and force=False."""
+    await _get_repo(session, repo_id, project_id, user_id)
+    workspace = await _get_workspace(session, workspace_id, repo_id)
+
+    manager = WorkspaceManager()
+    try:
+        await manager.delete(workspace, force=force, session=session)
+        await session.commit()
+    except WorkspaceHasInstancesError as exc:
+        await session.rollback()
+        raise HTTPException(
+            status_code=409,
+            detail={
+                "message": "Workspace has running tool instances",
+                "instances": exc.instances,
+            },
+        ) from exc
+    except Exception as exc:
+        await session.rollback()
+        logger.error("Failed to delete workspace: %s", exc)
+        raise HTTPException(
+            status_code=500, detail="Failed to delete workspace"
+        ) from exc
+
+    return {"status": "deleted"}
+
+
+@router.post("/{workspace_id}/sync")
+async def sync_workspace(
+    project_id: uuid.UUID,
+    repo_id: uuid.UUID,
+    workspace_id: uuid.UUID,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Sync workspace with remote. Returns 409 if branch was deleted."""
+    await _get_repo(session, repo_id, project_id, user_id)
+    workspace = await _get_workspace(session, workspace_id, repo_id)
+
+    manager = WorkspaceManager()
+    result = await manager.sync(workspace, session=session)
+
+    if result.branch_deleted:
+        raise HTTPException(
+            status_code=409,
+            detail={
+                "message": f"Branch '{workspace.branch}' was deleted from remote",
+                "branch_deleted": True,
+            },
+        )
+
+    await session.commit()
+    return {
+        "branch_deleted": False,
+        "pulled": True,
+        "last_sync_at": workspace.last_sync_at.isoformat()
+        if workspace.last_sync_at
+        else None,
+    }
+
+
+async def _get_repo(
+    session: AsyncSession,
+    repo_id: uuid.UUID,
+    project_id: uuid.UUID,
+    user_id: uuid.UUID,
+) -> GitRepository:
+    """Fetch and validate repository access."""
+    result = await session.execute(
+        select(GitRepository)
+        .where(
+            GitRepository.id == repo_id,
+            GitRepository.project_id == project_id,
+        )
+        .options(selectinload(GitRepository.project))
+    )
+    repo = result.scalar_one_or_none()
+    if not repo:
+        raise HTTPException(status_code=404, detail="Repository not found")
+    return repo
+
+
+async def _get_workspace(
+    session: AsyncSession,
+    workspace_id: uuid.UUID,
+    repo_id: uuid.UUID,
+) -> Workspace:
+    """Fetch and validate workspace."""
+    result = await session.execute(
+        select(Workspace).where(
+            Workspace.id == workspace_id,
+            Workspace.repo_id == repo_id,
+        )
+    )
+    workspace = result.scalar_one_or_none()
+    if not workspace:
+        raise HTTPException(status_code=404, detail="Workspace not found")
+    return workspace

apps/api/src/logging_config.py

@@ -1,15 +1,52 @@
+"""Structured JSON logging configuration."""
+
+import json
 import logging
 import sys
 import time
 import traceback
-from typing import Callable
+from collections.abc import Callable
 
 from fastapi import Request, Response
 from starlette.middleware.base import BaseHTTPMiddleware
 
+from src.services.shared.correlation import get_correlation_id
+
 logger = logging.getLogger(__name__)
 
 
+class CorrelationIdFilter(logging.Filter):
+    """Inject correlation_id into every log record from context var."""
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        record.correlation_id = get_correlation_id()  # type: ignore[attr-defined]
+        return True
+
+
+class JSONFormatter(logging.Formatter):
+    """Emit log records as single-line JSON."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        log_obj: dict = {
+            "timestamp": self.formatTime(record),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+            "correlation_id": getattr(record, "correlation_id", None),
+        }
+        # Optional extra fields
+        for key in ("instance_id", "event_type"):
+            value = getattr(record, key, None)
+            if value is not None:
+                log_obj[key] = value
+        if record.exc_info:
+            log_obj["exception"] = self.formatException(record.exc_info)
+        return json.dumps(log_obj, default=str)
+
+    def formatTime(self, record: logging.LogRecord, datefmt: str | None = None) -> str:
+        return time.strftime("%Y-%m-%dT%H:%M:%S", time.gmtime(record.created))
+
+
 class RequestLoggingMiddleware(BaseHTTPMiddleware):
     """Log all HTTP requests with timing and status codes."""
 
@@ -17,7 +54,6 @@ class RequestLoggingMiddleware(BaseHTTPMiddleware):
         start_time = time.time()
         client_host = request.client.host if request.client else "unknown"
 
-        # Log the incoming request
         logger.info(
             "→ Request: %s %s (client: %s)",
             request.method,
@@ -29,7 +65,6 @@ class RequestLoggingMiddleware(BaseHTTPMiddleware):
             response = await call_next(request)
             duration = time.time() - start_time
 
-            # Log the response
             logger.info(
                 "← Response: %s %s → %d (%dms)",
                 request.method,
@@ -69,15 +104,13 @@ class ExceptionLoggingMiddleware(BaseHTTPMiddleware):
 
 
 def configure_logging(level: int = logging.INFO) -> None:
-    """Configure structured logging for the application."""
-    formatter = logging.Formatter(
-        fmt="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
-        datefmt="%Y-%m-%d %H:%M:%S",
-    )
+    """Configure structured JSON logging for the application."""
+    formatter = JSONFormatter()
 
     # Console handler
     console_handler = logging.StreamHandler(sys.stdout)
     console_handler.setFormatter(formatter)
+    console_handler.addFilter(CorrelationIdFilter())
 
     # Configure root logger
     root_logger = logging.getLogger()

apps/api/src/main.py

@@ -7,29 +7,42 @@ from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import JSONResponse
 from fastapi.staticfiles import StaticFiles
 
-from src.api.auth import router as auth_router
-from src.api.dashboard import router as dashboard_router
-from src.api.git_repositories import router as git_repositories_router
-from src.api.health import router as health_router
-from src.api.projects import router as projects_router
-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_profiles import router as config_profiles_router
-from src.api.tool_definitions import router as tool_definitions_router
-from src.api.tool_instances import router as tool_instances_router
-from src.api.tool_instances import sessions_router
-from src.api.tool_types import router as tool_types_router
-from src.api.user_config import router as user_config_router
-from src.api.users import router as users_router
+from src.api.config import config_profiles_router, user_config_router
+from src.api.project import git_repositories_router, projects_router
+from src.api.system import (
+    dashboard_router,
+    events_router,
+    health_router,
+    instance_proxy_router,
+    notifications_router,
+    terminal_router,
+)
+from src.api.tool import (
+    sessions_router,
+    tool_definitions_router,
+    tool_instances_router,
+    tool_types_router,
+)
+from src.api.user import auth_router, ssh_keys_router, users_router
+from src.api.workspace import (
+    all_workspaces_router,
+    workspace_files_router,
+    workspace_git_router,
+    workspace_instances_router,
+    workspaces_router,
+)
 from src.config import Settings
-from src.models.terminal_session import TerminalSessionModel  # noqa: F401 – Alembic model discovery
+from src.models import Notification  # noqa: F401 – Alembic model discovery
+from src.models import TerminalSessionModel  # noqa: F401 – Alembic model discovery
 from src.database import init_database
 from src.logging_config import (
     ExceptionLoggingMiddleware,
     RequestLoggingMiddleware,
     configure_logging,
 )
+from src.seeds.builtin_tool_types import seed_builtin_tool_types
+from src.services.instance import InstanceEventBus, HealthMonitor
+from src.services.shared import CorrelationIdMiddleware
 
 # Configure logging early
 log_level = os.getenv("LOG_LEVEL", "INFO").upper()
@@ -54,6 +67,7 @@ app.add_middleware(
     allow_headers=["*"],
 )
 
+app.add_middleware(CorrelationIdMiddleware)
 app.add_middleware(RequestLoggingMiddleware)
 app.add_middleware(ExceptionLoggingMiddleware)
 
@@ -103,6 +117,11 @@ async def validation_exception_handler(request: Request, exc: RequestValidationE
     )
 
 
+# Global services
+_event_bus = InstanceEventBus()
+_health_monitor = HealthMonitor(_event_bus)
+
+
 @app.on_event("startup")
 async def on_startup():
     logger.info("Starting up Headquarter API...")
@@ -115,9 +134,25 @@ async def on_startup():
 
         sys.exit(1)
 
+    # Start background health monitor
+    _health_monitor.start()
+    logger.info("Health monitor started")
+
+    # Seed built-in tool types
+    await seed_builtin_tool_types()
+    logger.info("Built-in tool types seeded")
+
     logger.info("Startup complete.")
 
 
+@app.on_event("shutdown")
+async def on_shutdown():
+    logger.info("Shutting down Headquarter API...")
+    _health_monitor.stop()
+    logger.info("Health monitor stopped")
+    logger.info("Shutdown complete.")
+
+
 app.include_router(health_router)
 app.include_router(auth_router)
 app.include_router(dashboard_router)
@@ -133,4 +168,11 @@ app.include_router(tool_instances_router)
 app.include_router(sessions_router)
 app.include_router(instance_proxy_router)
 app.include_router(terminal_router)
+app.include_router(events_router)
+app.include_router(notifications_router)
+app.include_router(all_workspaces_router)
+app.include_router(workspaces_router)
+app.include_router(workspace_files_router)
+app.include_router(workspace_git_router)
+app.include_router(workspace_instances_router)
 app.mount("/uploads", StaticFiles(directory="uploads"), name="uploads")

apps/api/src/models/__init__.py

@@ -1,20 +1,27 @@
 from src.models.base import Base
-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
-from src.models.terminal_session import TerminalSessionModel
-from src.models.tool_definition_manifest import ToolDefinitionManifest
-from src.models.tool_instance import ToolInstance
-from src.models.tool_type import ToolType
-from src.models.user import User
-from src.models.user_config import UserConfig
+from src.models.config.config_profile import ConfigProfile, ConfigProfileInclude
+from src.models.project.git_repository import GitRepository
+from src.models.project.project import Project
+from src.models.project.workspace import Workspace
+from src.models.system.health_check import HealthCheck
+from src.models.system.instance_event import InstanceEvent
+from src.models.system.notification import Notification
+from src.models.system.terminal_session import TerminalSessionModel
+from src.models.tool.tool_definition_manifest import ToolDefinitionManifest
+from src.models.tool.tool_instance import ToolInstance
+from src.models.tool.tool_type import ToolType
+from src.models.user.ssh_key import SSHKey
+from src.models.user.user import User
+from src.models.user.user_config import UserConfig
 
 __all__ = [
     "Base",
     "ConfigProfile",
     "ConfigProfileInclude",
     "GitRepository",
+    "HealthCheck",
+    "InstanceEvent",
+    "Notification",
     "Project",
     "SSHKey",
     "TerminalSessionModel",
@@ -23,4 +30,5 @@ __all__ = [
     "ToolType",
     "User",
     "UserConfig",
+    "Workspace",
 ]

apps/api/src/models/config/__init__.py

@@ -0,0 +1,5 @@
+"""Config models module."""
+
+from src.models.config.config_profile import ConfigProfile, ConfigProfileInclude
+
+__all__ = ["ConfigProfile", "ConfigProfileInclude"]

apps/api/src/models/config/config_profile.py

@@ -1,7 +1,15 @@
 import uuid
 from typing import TYPE_CHECKING
 
-from sqlalchemy import ForeignKey, JSON, Integer, String, Text, Boolean
+from sqlalchemy import (
+    Boolean,
+    ForeignKey,
+    JSON,
+    Integer,
+    String,
+    Text,
+    UniqueConstraint,
+)
 from sqlalchemy import Uuid as UUID
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
@@ -9,12 +17,15 @@ 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 import ToolType
     from src.models.user import User
 
 
 class ConfigProfile(UUIDPrimaryKeyMixin, TimestampMixin, Base):
     __tablename__ = "config_profiles"
+    __table_args__ = (
+        UniqueConstraint("user_id", "name", name="uq_config_profiles_user_name"),
+    )
 
     user_id: Mapped[uuid.UUID] = mapped_column(
         UUID(), ForeignKey("users.id", ondelete="CASCADE"), nullable=False

apps/api/src/models/project/__init__.py

@@ -0,0 +1,7 @@
+"""Project models module."""
+
+from src.models.project.git_repository import GitRepository
+from src.models.project.project import Project
+from src.models.project.workspace import Workspace
+
+__all__ = ["GitRepository", "Project", "Workspace"]

apps/api/src/models/project/git_repository.py

@@ -10,7 +10,7 @@ from src.models.base import Base, TimestampMixin, UUIDPrimaryKeyMixin
 
 if TYPE_CHECKING:
     from src.models.project import Project
-    from src.models.ssh_key import SSHKey
+    from src.models import SSHKey
     from src.models.user import User
 
 

apps/api/src/models/project/project.py

@@ -8,8 +8,8 @@ from sqlalchemy.orm import Mapped, mapped_column, relationship
 from src.models.base import Base, TimestampMixin, UUIDPrimaryKeyMixin
 
 if TYPE_CHECKING:
-    from src.models.git_repository import GitRepository
-    from src.models.ssh_key import SSHKey
+    from src.models import GitRepository
+    from src.models import SSHKey
     from src.models.user import User
 
 

apps/api/src/models/project/workspace.py

@@ -0,0 +1,50 @@
+"""Workspace model for persistent writable repo clones."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+from sqlalchemy import DateTime, ForeignKey, String, UniqueConstraint
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from src.models.base import Base, TimestampMixin
+
+if TYPE_CHECKING:
+    from src.models import GitRepository
+    from src.models.user import User
+
+
+class Workspace(Base, TimestampMixin):
+    """A persistent, writable local clone of a Git repository.
+
+    Users create workspaces explicitly, then start tool instances on them.
+    Multiple tool instances can share the same workspace.
+    """
+
+    __tablename__ = "workspaces"
+
+    id: Mapped[uuid.UUID] = mapped_column(primary_key=True, default=uuid.uuid4)
+    name: Mapped[str] = mapped_column(String(255), nullable=False)
+    repo_id: Mapped[uuid.UUID] = mapped_column(
+        ForeignKey("git_repositories.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+    user_id: Mapped[uuid.UUID] = mapped_column(
+        ForeignKey("users.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+    branch: Mapped[str] = mapped_column(String(255), nullable=False, default="main")
+    path: Mapped[str] = mapped_column(String(2048), nullable=False)
+    status: Mapped[str] = mapped_column(String(16), nullable=False, default="ready")
+    last_sync_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+
+    __table_args__ = (
+        UniqueConstraint("repo_id", "name", name="uq_workspace_repo_name"),
+    )
+
+    repository: Mapped[GitRepository] = relationship("GitRepository")
+    owner: Mapped[User] = relationship("User")

apps/api/src/models/system/__init__.py

@@ -0,0 +1,8 @@
+"""System models module."""
+
+from src.models.system.health_check import HealthCheck
+from src.models.system.instance_event import InstanceEvent
+from src.models.system.notification import Notification
+from src.models.system.terminal_session import TerminalSessionModel
+
+__all__ = ["HealthCheck", "InstanceEvent", "Notification", "TerminalSessionModel"]

apps/api/src/models/system/health_check.py

@@ -0,0 +1,30 @@
+"""SQLAlchemy model for health check snapshots."""
+
+import uuid
+from datetime import datetime
+
+from sqlalchemy import Boolean, DateTime, ForeignKey, Integer, String, Text, Uuid, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from src.models.base import Base, UUIDPrimaryKeyMixin
+
+
+class HealthCheck(UUIDPrimaryKeyMixin, Base):
+    __tablename__ = "health_checks"
+
+    instance_id: Mapped[uuid.UUID] = mapped_column(
+        Uuid(as_uuid=True),
+        ForeignKey("tool_instances.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+    container_status: Mapped[str | None] = mapped_column(String(50), nullable=True)
+    container_healthy: Mapped[bool | None] = mapped_column(Boolean, nullable=True)
+    tunnel_healthy: Mapped[bool | None] = mapped_column(Boolean, nullable=True)
+    exit_code: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    probe_status: Mapped[str | None] = mapped_column(String(50), nullable=True)
+    probe_output: Mapped[str | None] = mapped_column(Text, nullable=True)
+    checked_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        nullable=False,
+    )

apps/api/src/models/system/instance_event.py

@@ -0,0 +1,39 @@
+"""SQLAlchemy model for instance lifecycle event audit rows."""
+
+import uuid
+from datetime import datetime
+from typing import Any
+
+from sqlalchemy import DateTime, ForeignKey, JSON, String, Text, Uuid, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from src.models.base import Base, UUIDPrimaryKeyMixin
+
+
+class InstanceEvent(UUIDPrimaryKeyMixin, Base):
+    __tablename__ = "instance_events"
+
+    instance_id: Mapped[uuid.UUID] = mapped_column(
+        Uuid(as_uuid=True),
+        ForeignKey("tool_instances.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+    event_type: Mapped[str] = mapped_column(String(50), nullable=False)
+    status: Mapped[str | None] = mapped_column(String(50), nullable=True)
+    message: Mapped[str | None] = mapped_column(Text, nullable=True)
+    created_by: Mapped[uuid.UUID | None] = mapped_column(
+        Uuid(as_uuid=True),
+        ForeignKey("users.id", ondelete="SET NULL"),
+        nullable=True,
+    )
+    event_metadata: Mapped[dict[str, Any]] = mapped_column(
+        "metadata",
+        JSON,
+        nullable=False,
+        default=dict,
+    )
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        nullable=False,
+    )

apps/api/src/models/system/notification.py

@@ -0,0 +1,43 @@
+"""Notification SQLAlchemy model."""
+
+from datetime import datetime
+from typing import Any
+import uuid
+
+from sqlalchemy import DateTime, ForeignKey, JSON, String, Text
+from sqlalchemy import Uuid as UUID
+from sqlalchemy.orm import Mapped, mapped_column
+from sqlalchemy.sql import func
+
+from src.models.base import Base, UUIDPrimaryKeyMixin
+
+
+class Notification(UUIDPrimaryKeyMixin, Base):
+    __tablename__ = "notifications"
+
+    user_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("users.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+    category: Mapped[str] = mapped_column(String(32), nullable=False)
+    severity: Mapped[str] = mapped_column(String(16), nullable=False)
+    title: Mapped[str] = mapped_column(String(255), nullable=False)
+    message: Mapped[str | None] = mapped_column(Text, nullable=True)
+    source_type: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    source_id: Mapped[uuid.UUID | None] = mapped_column(
+        UUID(as_uuid=True), nullable=True
+    )
+    notification_metadata: Mapped[dict[str, Any]] = mapped_column(
+        "metadata", JSON, nullable=False, default=dict
+    )
+    read_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True, index=True
+    )
+    dismissed_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), nullable=False, index=True
+    )

apps/api/src/models/tool/__init__.py

@@ -0,0 +1,7 @@
+"""Tool models module."""
+
+from src.models.tool.tool_definition_manifest import ToolDefinitionManifest
+from src.models.tool.tool_instance import ToolInstance
+from src.models.tool.tool_type import ToolType
+
+__all__ = ["ToolDefinitionManifest", "ToolInstance", "ToolType"]

apps/api/src/models/tool/tool_instance.py

@@ -9,11 +9,12 @@ 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 import ConfigProfile
+    from src.models import GitRepository
     from src.models.project import Project
-    from src.models.tool_type import ToolType
+    from src.models import ToolType
     from src.models.user import User
+    from src.models import Workspace
 
 
 class ToolInstance(UUIDPrimaryKeyMixin, TimestampMixin, Base):
@@ -59,8 +60,13 @@ class ToolInstance(UUIDPrimaryKeyMixin, TimestampMixin, Base):
     selected_config_profile_id: Mapped[uuid.UUID | None] = mapped_column(
         UUID(), ForeignKey("config_profiles.id", ondelete="SET NULL"), nullable=True
     )
+    ssh_key_ids: Mapped[list[str] | None] = mapped_column(JSON, nullable=True)
+    workspace_id: Mapped[uuid.UUID | None] = mapped_column(
+        UUID(), ForeignKey("workspaces.id", ondelete="SET NULL"), nullable=True
+    )
 
     tool_type: Mapped["ToolType"] = relationship()
+    workspace: Mapped["Workspace | None"] = relationship()
     repository: Mapped["GitRepository"] = relationship()
     project: Mapped["Project"] = relationship()
     owner: Mapped["User"] = relationship()

apps/api/src/models/tool/tool_type.py

@@ -6,9 +6,9 @@ from sqlalchemy import Uuid as UUID
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
 from src.models.base import Base, TimestampMixin, UUIDPrimaryKeyMixin
+from src.models.tool.tool_definition_manifest import ToolDefinitionManifest
 
 if TYPE_CHECKING:
-    from src.models.tool_definition_manifest import ToolDefinitionManifest
     from src.models.user import User
 
 

apps/api/src/models/user/__init__.py

@@ -0,0 +1,7 @@
+"""User models module."""
+
+from src.models.user.ssh_key import SSHKey
+from src.models.user.user import User
+from src.models.user.user_config import UserConfig
+
+__all__ = ["SSHKey", "User", "UserConfig"]

apps/api/src/models/user/user.py

@@ -7,8 +7,8 @@ from src.models.base import Base, TimestampMixin, UUIDPrimaryKeyMixin
 
 if TYPE_CHECKING:
     from src.models.project import Project
-    from src.models.ssh_key import SSHKey
-    from src.models.user_config import UserConfig
+    from src.models import SSHKey
+    from src.models import UserConfig
 
 
 class User(UUIDPrimaryKeyMixin, TimestampMixin, Base):

apps/api/src/models/user/user_config.py

@@ -0,0 +1,51 @@
+import uuid
+from typing import TYPE_CHECKING
+
+from sqlalchemy import ForeignKey, JSON
+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.user import User
+
+
+class UserConfig(UUIDPrimaryKeyMixin, TimestampMixin, Base):
+    __tablename__ = "user_configs"
+
+    user_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(), ForeignKey("users.id"), nullable=False, unique=True
+    )
+    config: Mapped[dict[str, object]] = mapped_column(
+        JSON, default=dict, nullable=False
+    )
+
+    user: Mapped["User"] = relationship(back_populates="user_config")
+
+    @property
+    def default_profile_id(self) -> uuid.UUID | None:
+        """Return the legacy global default profile ID from config JSON."""
+        profile_id = self.config.get("default_profile_id")
+        if isinstance(profile_id, str):
+            return uuid.UUID(profile_id)
+        return None
+
+    @default_profile_id.setter
+    def default_profile_id(self, value: uuid.UUID | None) -> None:
+        if value is not None:
+            self.config["default_profile_id"] = str(value)
+        elif "default_profile_id" in self.config:
+            del self.config["default_profile_id"]
+
+    @property
+    def default_profiles(self) -> dict[str, str]:
+        """Return per-tool-type default profile IDs from config JSON."""
+        value = self.config.get("default_profiles", {})
+        if isinstance(value, dict):
+            return {str(k): str(v) for k, v in value.items()}
+        return {}
+
+    @default_profiles.setter
+    def default_profiles(self, value: dict[str, str]) -> None:
+        self.config["default_profiles"] = value

apps/api/src/models/user_config.py

@@ -1,20 +0,0 @@
-import uuid
-from typing import TYPE_CHECKING
-
-from sqlalchemy import ForeignKey
-from sqlalchemy import JSON, 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.user import User
-
-
-class UserConfig(UUIDPrimaryKeyMixin, TimestampMixin, Base):
-    __tablename__ = "user_configs"
-
-    user_id: Mapped[uuid.UUID] = mapped_column(UUID(), ForeignKey("users.id"), nullable=False, unique=True)
-    config: Mapped[dict[str, object]] = mapped_column(JSON, default=dict, nullable=False)
-
-    user: Mapped["User"] = relationship(back_populates="user_config")

apps/api/src/schemas/config/__init__.py

@@ -0,0 +1,27 @@
+"""Config schemas module."""
+
+from src.schemas.config.config_profile import (
+    ConfigProfileCreate,
+    ConfigProfileIncludeUpdate,
+    ConfigProfileResponse,
+    ConfigProfileUpdate,
+    DefaultProfilesUpdate,
+    GitMountItem,
+    GitMountMapping,
+    MountItem,
+    ValidateGitUrlRequest,
+    ValidateGitUrlResponse,
+)
+
+__all__ = [
+    "ConfigProfileCreate",
+    "ConfigProfileIncludeUpdate",
+    "ConfigProfileResponse",
+    "ConfigProfileUpdate",
+    "DefaultProfilesUpdate",
+    "GitMountItem",
+    "GitMountMapping",
+    "MountItem",
+    "ValidateGitUrlRequest",
+    "ValidateGitUrlResponse",
+]

apps/api/src/schemas/config/config_profile.py

@@ -0,0 +1,280 @@
+"""Config profile request/response schemas."""
+
+import uuid
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+from src.api.shared_validators import validate_env_vars as _validate_env_vars
+
+
+def _validate_uuid(v: str | None) -> str | None:
+    if v is None:
+        return v
+    try:
+        uuid.UUID(v)
+    except ValueError as exc:
+        raise ValueError(f"Invalid UUID: {v}") from exc
+    return v
+
+
+class GitMountMapping(BaseModel):
+    source_path: str = Field(
+        description="Path within repository (supports glob patterns)"
+    )
+    target_path: str = Field(description="Absolute path inside container")
+
+    @field_validator("source_path")
+    @classmethod
+    def validate_source_path(cls, v: str) -> str:
+        if v.startswith("/"):
+            raise ValueError("source_path must be relative (no leading /)")
+        if ".." in v:
+            raise ValueError("source_path cannot contain path traversal (..)")
+        return v
+
+    @field_validator("target_path")
+    @classmethod
+    def validate_target_path(cls, v: str) -> str:
+        if ".." in v:
+            raise ValueError("target_path cannot contain path traversal (..)")
+        return v
+
+
+class GitMountItem(BaseModel):
+    remote_url: str = Field(description="Git remote URL (HTTPS or SSH)")
+    source_path: str | None = Field(
+        default=None, description="Path within repository (legacy single mapping)"
+    )
+    target_path: str | None = Field(
+        default=None,
+        description="Absolute path inside container (legacy single mapping)",
+    )
+    branch: str | None = Field(default=None, description="Optional branch or tag name")
+    mappings: list[GitMountMapping] | None = Field(
+        default=None, description="Multiple source/target mappings from the same repo"
+    )
+
+    @field_validator("remote_url")
+    @classmethod
+    def validate_remote_url(cls, v: str) -> str:
+        if not v.startswith(("http://", "https://", "git@", "ssh://")):
+            raise ValueError(
+                "remote_url must be a valid git URL (https://, git@, or ssh://)"
+            )
+        return v
+
+    @field_validator("source_path")
+    @classmethod
+    def validate_source_path(cls, v: str | None) -> str | None:
+        if v is None:
+            return v
+        if v.startswith("/"):
+            raise ValueError("source_path must be relative (no leading /)")
+        if ".." in v:
+            raise ValueError("source_path cannot contain path traversal (..)")
+        return v
+
+    @field_validator("target_path")
+    @classmethod
+    def validate_target_path(cls, v: str | None) -> str | None:
+        if v is None:
+            return v
+        if ".." in v:
+            raise ValueError("target_path cannot contain path traversal (..)")
+        return v
+
+    @model_validator(mode="after")
+    def check_mappings_or_legacy(self):
+        has_legacy = self.source_path is not None and self.target_path is not None
+        has_mappings = self.mappings is not None and len(self.mappings) > 0
+        if not has_legacy and not has_mappings:
+            raise ValueError(
+                "Git mount must have either 'mappings' (non-empty array) or both 'source_path' and 'target_path'"
+            )
+        return self
+
+
+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:
+            if ".." in path or not path:
+                raise ValueError(f"Invalid file path: {path}")
+            if path.startswith("/"):
+                raise ValueError(
+                    f"Mount file paths must be relative (got: {path}). "
+                    f"The mount target defines the absolute container 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}"
+    )
+    git_mounts: list[GitMountItem] = Field(
+        default_factory=list, description="Git repository mounts"
+    )
+    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:
+            if ".." in path or not path:
+                raise ValueError(f"Invalid file path: {path}")
+            if path.startswith("/"):
+                raise ValueError(
+                    f"File paths must be relative (got: {path}). "
+                    f"Use Mounts for absolute container paths."
+                )
+        return v
+
+    @field_validator("env_vars")
+    @classmethod
+    def validate_env_vars(cls, v: dict) -> dict:
+        result = _validate_env_vars(v)
+        if result is None:
+            raise ValueError("env_vars must be a JSON object")
+        return result
+
+    @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}"
+    )
+    git_mounts: list[GitMountItem] | None = Field(
+        default=None, description="Git repository mounts"
+    )
+    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:
+            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 as exc:
+                raise ValueError(f"Invalid UUID in includes: {item}") from exc
+        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
+    git_mounts: list
+    is_default: bool
+    includes: list[dict]
+    created_at: str
+    updated_at: str
+
+
+class DefaultProfilesUpdate(BaseModel):
+    default_profiles: dict[str, str] = Field(
+        description="Mapping of tool_type_id -> profile_id for default profiles"
+    )
+
+
+class ValidateGitUrlRequest(BaseModel):
+    url: str = Field(description="Git remote URL to validate")
+    ssh_key_id: str | None = Field(
+        default=None, description="Optional SSH key ID for private repos"
+    )
+
+
+class ValidateGitUrlResponse(BaseModel):
+    valid: bool
+    suggested_url: str | None = None
+    branches: list[str] | None = None
+    default_branch: str | None = None
+    error: str | None = None
+    error_code: str | None = None

apps/api/src/schemas/project/__init__.py

@@ -0,0 +1,41 @@
+"""Project schemas module."""
+
+from src.schemas.project.git_repository import (
+    GitRepositoryCreate,
+    GitRepositoryResponse,
+    UpdateSSHKeyRequest,
+    URLParseRequest,
+    URLParseResponse,
+)
+from src.schemas.project.project import (
+    ProjectCreate,
+    ProjectResponse,
+    ProjectUpdate,
+    SetDefaultSSHKeyRequest,
+)
+from src.schemas.project.ssh_key import (
+    SSHKeyCreate,
+    SSHKeyResponse,
+    SignPayloadRequest,
+    SignatureResponse,
+    VerifySignatureRequest,
+    VerifySignatureResponse,
+)
+
+__all__ = [
+    "GitRepositoryCreate",
+    "GitRepositoryResponse",
+    "ProjectCreate",
+    "ProjectResponse",
+    "ProjectUpdate",
+    "SSHKeyCreate",
+    "SSHKeyResponse",
+    "SetDefaultSSHKeyRequest",
+    "SignPayloadRequest",
+    "SignatureResponse",
+    "URLParseRequest",
+    "URLParseResponse",
+    "UpdateSSHKeyRequest",
+    "VerifySignatureRequest",
+    "VerifySignatureResponse",
+]

apps/api/src/schemas/project/git_repository.py

@@ -0,0 +1,47 @@
+"""Git repository request/response schemas."""
+
+import uuid
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict
+
+
+class GitRepositoryCreate(BaseModel):
+    name: str
+    remote_url: str | None = None
+    force_original_url: bool = False
+    ssh_key_id: str | None = None
+
+
+class URLParseRequest(BaseModel):
+    url: str
+
+
+class URLParseResponse(BaseModel):
+    original_url: str
+    base_url: str | None
+    is_valid_clone_url: bool
+    needs_parsing: bool
+    host: str | None
+    message: str
+    error_code: str | None
+
+
+class GitRepositoryResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: uuid.UUID
+    name: str
+    path: str
+    project_id: uuid.UUID | None
+    owner_id: uuid.UUID
+    is_mirror: bool
+    remote_url: str | None
+    last_push: datetime | None
+    ssh_key_id: uuid.UUID | None
+    created_at: datetime
+    updated_at: datetime
+
+
+class UpdateSSHKeyRequest(BaseModel):
+    ssh_key_id: str | None = None

apps/api/src/schemas/project/project.py

@@ -0,0 +1,29 @@
+"""Project request/response schemas."""
+
+import uuid
+
+from pydantic import BaseModel, ConfigDict
+
+
+class ProjectCreate(BaseModel):
+    name: str
+    description: str | None = None
+
+
+class ProjectUpdate(BaseModel):
+    name: str | None = None
+    description: str | None = None
+
+
+class ProjectResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: uuid.UUID
+    name: str
+    description: str | None
+    owner_id: uuid.UUID
+    default_ssh_key_id: uuid.UUID | None
+
+
+class SetDefaultSSHKeyRequest(BaseModel):
+    ssh_key_id: uuid.UUID

apps/api/src/schemas/project/ssh_key.py

@@ -0,0 +1,36 @@
+"""SSH key request/response schemas."""
+
+import uuid
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict
+
+
+class SSHKeyCreate(BaseModel):
+    name: str
+
+
+class SSHKeyResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: uuid.UUID
+    name: str
+    public_key: str
+    created_at: datetime
+
+
+class SignPayloadRequest(BaseModel):
+    payload: str
+
+
+class SignatureResponse(BaseModel):
+    signature: str
+
+
+class VerifySignatureRequest(BaseModel):
+    payload: str
+    signature: str
+
+
+class VerifySignatureResponse(BaseModel):
+    valid: bool

apps/api/src/schemas/system/__init__.py

@@ -0,0 +1,17 @@
+"""System schemas module."""
+
+from src.schemas.system.health import (
+    DatabaseHealth,
+    DatabaseHealthResponse,
+    DiskHealth,
+    HealthChecks,
+    HealthResponse,
+)
+
+__all__ = [
+    "DatabaseHealth",
+    "DatabaseHealthResponse",
+    "DiskHealth",
+    "HealthChecks",
+    "HealthResponse",
+]

apps/api/src/schemas/system/health.py

@@ -0,0 +1,50 @@
+"""Health check response schemas."""
+
+from pydantic import BaseModel, Field
+
+
+class DatabaseHealth(BaseModel):
+    """Database health check result."""
+
+    status: str = Field(description="Database health status", examples=["healthy"])
+    response_time_ms: float = Field(
+        description="Query response time in milliseconds", examples=[5.2]
+    )
+
+
+class DiskHealth(BaseModel):
+    """Disk space health check result."""
+
+    status: str = Field(description="Disk health status", examples=["healthy"])
+    free_gb: float = Field(description="Free disk space in GB", examples=[45.2])
+    total_gb: float = Field(description="Total disk space in GB", examples=[100.0])
+
+
+class HealthChecks(BaseModel):
+    """Individual health checks."""
+
+    database: DatabaseHealth | None = None
+    disk: DiskHealth | None = None
+
+
+class HealthResponse(BaseModel):
+    """Overall health check response."""
+
+    status: str = Field(description="Overall health status", examples=["healthy"])
+    timestamp: str = Field(
+        description="ISO 8601 timestamp", examples=["2026-05-19T12:00:00Z"]
+    )
+    version: str = Field(description="API version", examples=["0.1.0"])
+    checks: HealthChecks = Field(description="Individual health checks")
+    uptime_seconds: float = Field(
+        description="Server uptime in seconds", examples=[3600.0]
+    )
+
+
+class DatabaseHealthResponse(BaseModel):
+    """Database-specific health check response."""
+
+    status: str = Field(description="Database health status", examples=["healthy"])
+    response_time_ms: float = Field(
+        description="Query response time in milliseconds", examples=[5.2]
+    )

apps/api/src/schemas/tool/__init__.py

@@ -0,0 +1,18 @@
+"""Tool schemas module."""
+
+from src.schemas.tool.tool_instance import CreateInstanceRequest, StartInstanceRequest
+from src.schemas.tool.tool_type import (
+    ToolTypeCreate,
+    ToolTypeResponse,
+    ToolTypeUpdate,
+    ToolTypeValidateRequest,
+)
+
+__all__ = [
+    "CreateInstanceRequest",
+    "StartInstanceRequest",
+    "ToolTypeCreate",
+    "ToolTypeResponse",
+    "ToolTypeUpdate",
+    "ToolTypeValidateRequest",
+]

apps/api/src/schemas/tool/tool_instance.py

@@ -0,0 +1,45 @@
+"""Tool instance request/response schemas."""
+
+from pydantic import BaseModel, Field
+
+
+class CreateInstanceRequest(BaseModel):
+    """Request body for creating a tool instance."""
+
+    model_config = {"extra": "ignore"}
+
+    tool_type_id: str = Field(description="UUID of the tool type to instantiate")
+    display_name: str | None = Field(
+        default=None, description="Optional display name for the instance"
+    )
+    workspace_id: str | None = Field(
+        default=None, description="UUID of workspace to mount (replaces clone_mode)"
+    )
+    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"
+    )
+    ssh_key_ids: list[str] = Field(
+        default_factory=list, description="SSH key IDs to mount into container ~/.ssh"
+    )
+
+
+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"
+    )
+    ssh_key_ids: list[str] = Field(
+        default_factory=list, description="SSH key IDs to mount into container ~/.ssh"
+    )

apps/api/src/schemas/tool/tool_type.py

@@ -0,0 +1,230 @@
+"""Tool type request/response schemas."""
+
+import uuid
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, field_validator, model_validator
+
+from src.api.tool.tool_types_validation import (
+    check_port_exposed,
+    validate_compose_yaml,
+    validate_required_variables,
+)
+
+
+class ToolTypeCreate(BaseModel):
+    name: str
+    display_name: str
+    description: str | None = None
+    default_port: int = 0
+    definition_type: str = "compose"
+    manifest_id: uuid.UUID | None = None
+    compose_template: str | None = None
+    dockerfile_template: str | None = None
+    build_context: dict | None = None
+    readiness_probe: dict | None = None
+    startup_command: str | None = None
+    required_variables: list[str] = []
+    category: str = "other"
+    interface_type: str = "web"
+    requires_port: bool = True
+
+    @field_validator("definition_type")
+    @classmethod
+    def validate_definition_type(cls, v: str) -> str:
+        if v not in ("compose", "dockerfile", "manifest"):
+            raise ValueError(
+                "definition_type must be 'compose', 'dockerfile', or 'manifest'"
+            )
+        return v
+
+    @field_validator("compose_template")
+    @classmethod
+    def validate_compose_template(cls, v: str | None, info) -> str | None:
+        data = info.data
+        if data.get("definition_type") != "compose":
+            return v
+
+        if v is None or not v.strip():
+            raise ValueError(
+                "compose_template is required when definition_type is 'compose'"
+            )
+
+        validate_compose_yaml(v)
+        return v
+
+    @field_validator("dockerfile_template")
+    @classmethod
+    def validate_dockerfile_template(cls, v: str | None, info) -> str | None:
+        data = info.data
+        if data.get("definition_type") != "dockerfile":
+            return v
+
+        if v is None or not v.strip():
+            raise ValueError(
+                "dockerfile_template is required when definition_type is 'dockerfile'"
+            )
+
+        if not v.strip().startswith("FROM"):
+            raise ValueError("Dockerfile must start with a FROM instruction")
+
+        return v
+
+    @field_validator("interface_type")
+    @classmethod
+    def validate_interface_type(cls, v: str) -> str:
+        if v not in ("web", "terminal"):
+            raise ValueError("interface_type must be 'web' or 'terminal'")
+        return v
+
+    @field_validator("default_port")
+    @classmethod
+    def validate_default_port(cls, v: int, info) -> int:
+        data = info.data
+        requires_port = data.get("requires_port", True)
+        if not requires_port:
+            return v
+        if v <= 0 or v > 65535:
+            raise ValueError("Port must be between 1 and 65535")
+        return v
+
+    @field_validator("required_variables")
+    @classmethod
+    def validate_required_variables(cls, v: list[str], info) -> list[str]:
+        if not v:
+            return v
+
+        data = info.data
+        if data.get("definition_type") != "compose":
+            return v
+
+        template = data.get("compose_template")
+        if not template:
+            return v
+
+        validate_required_variables(template, v)
+        return v
+
+    @model_validator(mode="after")
+    def validate_templates(self) -> "ToolTypeCreate":
+        if self.definition_type == "manifest":
+            if self.manifest_id is None:
+                raise ValueError(
+                    "manifest_id is required when definition_type is 'manifest'"
+                )
+            return self
+
+        if self.definition_type == "dockerfile" and (
+            self.dockerfile_template is None or not self.dockerfile_template.strip()
+        ):
+            raise ValueError(
+                "dockerfile_template is required when definition_type is 'dockerfile'"
+            )
+        if self.definition_type == "compose" and (
+            self.compose_template is None or not self.compose_template.strip()
+        ):
+            raise ValueError(
+                "compose_template is required when definition_type is 'compose'"
+            )
+
+        if (
+            self.requires_port
+            and self.definition_type == "compose"
+            and self.compose_template
+        ):
+            try:
+                parsed = validate_compose_yaml(self.compose_template)
+            except ValueError:
+                return self
+
+            if not check_port_exposed(parsed, self.default_port):
+                raise ValueError(
+                    f"Port {self.default_port} is not exposed in the compose template. Add it to the 'ports' section."
+                )
+
+        return self
+
+
+class ToolTypeUpdate(BaseModel):
+    display_name: str | None = None
+    description: str | None = None
+    default_port: int | None = None
+    definition_type: str | None = None
+    manifest_id: uuid.UUID | None = None
+    compose_template: str | None = None
+    dockerfile_template: str | None = None
+    build_context: dict | None = None
+    readiness_probe: dict | None = None
+    startup_command: str | None = None
+    required_variables: list[str] | None = None
+    category: str | None = None
+    interface_type: str | None = None
+    requires_port: bool | None = None
+
+    @field_validator("definition_type")
+    @classmethod
+    def validate_definition_type(cls, v: str | None) -> str | None:
+        if v is None:
+            return v
+        if v not in ("compose", "dockerfile", "manifest"):
+            raise ValueError(
+                "definition_type must be 'compose', 'dockerfile', or 'manifest'"
+            )
+        return v
+
+    @field_validator("interface_type")
+    @classmethod
+    def validate_interface_type(cls, v: str | None) -> str | None:
+        if v is None:
+            return v
+        if v not in ("web", "terminal"):
+            raise ValueError("interface_type must be 'web' or 'terminal'")
+        return v
+
+    @field_validator("compose_template")
+    @classmethod
+    def validate_compose_template(cls, v: str | None, info) -> str | None:
+        if v is None:
+            return v
+        validate_compose_yaml(v)
+        return v
+
+    @field_validator("dockerfile_template")
+    @classmethod
+    def validate_dockerfile_template(cls, v: str | None, info) -> str | None:
+        if v is None:
+            return v
+        if not v.strip().startswith("FROM"):
+            raise ValueError("Dockerfile must start with a FROM instruction")
+        return v
+
+
+class ToolTypeResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: uuid.UUID
+    name: str
+    display_name: str
+    description: str | None
+    category: str
+    interface_type: str
+    requires_port: bool
+    default_port: int
+    definition_type: str
+    manifest_id: uuid.UUID | None
+    compose_template: str | None
+    dockerfile_template: str | None
+    build_context: dict | None
+    readiness_probe: dict | None
+    startup_command: str | None
+    required_variables: list[str]
+    created_by_id: uuid.UUID | None
+    created_at: datetime
+    updated_at: datetime
+
+
+class ToolTypeValidateRequest(BaseModel):
+    definition_type: str
+    compose_template: str | None = None
+    dockerfile_template: str | None = None

apps/api/src/schemas/user/__init__.py

@@ -0,0 +1,11 @@
+"""User schemas module."""
+
+from src.schemas.user.user import UserProfileResponse, UserProfileUpdate
+from src.schemas.user.user_config import UserConfigResponse, UserConfigUpdate
+
+__all__ = [
+    "UserConfigResponse",
+    "UserConfigUpdate",
+    "UserProfileResponse",
+    "UserProfileUpdate",
+]

apps/api/src/schemas/user/user.py

@@ -0,0 +1,19 @@
+"""User response schemas."""
+
+import uuid
+
+from pydantic import BaseModel, ConfigDict
+
+
+class UserProfileResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: uuid.UUID
+    email: str
+    name: str
+    avatar_url: str | None
+
+
+class UserProfileUpdate(BaseModel):
+    name: str | None = None
+    email: str | None = None

apps/api/src/schemas/user/user_config.py

@@ -0,0 +1,25 @@
+"""User config response schemas."""
+
+from pydantic import BaseModel, ConfigDict
+
+
+class UserConfigResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    default_editor: str | None = None
+    theme: str = "system"
+    git_user_name: str | None = None
+    git_user_email: str | None = None
+    last_session_id: str | None = None
+    notification_mute_categories: list[str] | None = None
+    notification_toast_level: str | None = None
+
+
+class UserConfigUpdate(BaseModel):
+    default_editor: str | None = None
+    theme: str | None = None
+    git_user_name: str | None = None
+    git_user_email: str | None = None
+    last_session_id: str | None = None
+    notification_mute_categories: list[str] | None = None
+    notification_toast_level: str | None = None

apps/api/src/seeds/__init__.py

@@ -0,0 +1 @@
+"""Database seeding utilities."""

apps/api/src/seeds/builtin_tool_types.py

@@ -0,0 +1,168 @@
+"""Seed built-in tool types into the database."""
+
+import logging
+
+from sqlalchemy import select, text
+
+from src.database import SessionLocal
+from src.models import ToolType
+
+logger = logging.getLogger(__name__)
+
+
+async def _table_exists(session, table_name: str) -> bool:
+    """Check if a table exists in the database."""
+    try:
+        result = await session.execute(
+            text(
+                """
+                SELECT EXISTS (
+                    SELECT FROM information_schema.tables
+                    WHERE table_schema = 'public'
+                    AND table_name = :table_name
+                )
+            """
+            ),
+            {"table_name": table_name},
+        )
+        return result.scalar() or False
+    except Exception:
+        return False
+
+
+async def seed_builtin_tool_types():
+    """Create or update built-in tool types in the database.
+
+    Built-in tool types have no creator (created_by_id=None) and provide
+    out-of-the-box tools for users without requiring manual tool creation.
+    """
+    async with SessionLocal() as session:
+        # Check if tool_types table exists before attempting to seed
+        if not await _table_exists(session, "tool_types"):
+            logger.warning(
+                "tool_types table does not exist. Skipping seeding. "
+                "Migrations may not have run yet."
+            )
+            return
+
+        builtin_types = [
+            {
+                "name": "code-server",
+                "display_name": "VS Code Server",
+                "description": "VS Code running in the browser via code-server",
+                "category": "editor",
+                "interface_type": "web",
+                "compose_template": """version: "3.8"
+services:
+  code-server:
+    image: lscr.io/linuxserver/code-server:latest
+    container_name: {{TOOL_NAME}}
+    environment:
+      - PUID=1000
+      - PGID=1000
+      - TZ=Europe/London
+    volumes:
+      - {{REPO_PATH}}:/config/workspace
+    ports:
+      - "8443:8443"
+    restart: unless-stopped""",
+                "default_port": 8443,
+                "required_variables": ["REPO_PATH", "TOOL_NAME"],
+            },
+            {
+                "name": "jupyter-notebook",
+                "display_name": "Jupyter Notebook",
+                "description": "Jupyter Lab for interactive development",
+                "category": "notebook",
+                "interface_type": "web",
+                "default_port": 8888,
+                "compose_template": """version: "3.8"
+services:
+  jupyter:
+    image: jupyter/scipy-notebook:latest
+    container_name: {{TOOL_NAME}}
+    environment:
+      - JUPYTER_ENABLE_LAB=yes
+    volumes:
+      - {{REPO_PATH}}:/home/jovyan/work
+    ports:
+      - "8888:8888"
+    restart: unless-stopped""",
+                "required_variables": ["REPO_PATH", "TOOL_NAME"],
+            },
+            {
+                "name": "opencode",
+                "display_name": "OpenCode",
+                "description": "AI coding assistant - run opencode in terminal",
+                "category": "ai-assistant",
+                "interface_type": "terminal",
+                "default_port": 3000,
+                "compose_template": """version: "3.8"
+services:
+  opencode:
+    image: node:20-slim
+    container_name: {{TOOL_NAME}}
+    working_dir: /workspace
+    environment:
+      - HOME=/tmp
+    volumes:
+      - {{REPO_PATH}}:/workspace
+      - opencode_home:/tmp
+    ports:
+      - "3000:3000"
+    command: >
+      sh -c "set -x &&
+             apt-get update && apt-get install -y git ca-certificates &&
+             echo 'Installing opencode...' &&
+             npm install -g opencode-ai 2>&1 || echo 'ERROR: npm install failed' &&
+             which opencode || echo 'ERROR: opencode not in PATH' &&
+             npm bin -g &&
+             ls -la $(npm bin -g) || echo 'ERROR: global bin dir not found' &&
+             echo 'export PATH=\"$(npm bin -g):\\$PATH\"' >> /root/.bashrc &&
+             echo 'cd /workspace' >> /root/.bashrc &&
+             echo 'OpenCode installation complete' &&
+             cd /workspace &&
+             exec tail -f /dev/null"
+    stdin_open: true
+    tty: true
+    restart: unless-stopped
+
+volumes:
+  opencode_home:""",
+                "required_variables": ["REPO_PATH", "TOOL_NAME"],
+            },
+        ]
+
+        for tool_data in builtin_types:
+            existing = await session.scalar(
+                select(ToolType).where(ToolType.name == tool_data["name"])
+            )
+            if not existing:
+                tool_type = ToolType(
+                    name=tool_data["name"],
+                    display_name=tool_data["display_name"],
+                    description=tool_data["description"],
+                    category=tool_data["category"],
+                    interface_type=tool_data["interface_type"],
+                    definition_type="compose",
+                    compose_template=tool_data["compose_template"],
+                    required_variables=tool_data["required_variables"],
+                    default_port=tool_data.get("default_port", 0),
+                    created_by_id=None,
+                )
+                session.add(tool_type)
+                logger.info("Created built-in tool type: %s", tool_data["name"])
+            else:
+                # Update existing built-in tool types to reflect code changes
+                existing.display_name = tool_data["display_name"]
+                existing.description = tool_data["description"]
+                existing.category = tool_data["category"]
+                existing.interface_type = tool_data["interface_type"]
+                existing.definition_type = "compose"
+                existing.compose_template = tool_data["compose_template"]
+                existing.required_variables = tool_data["required_variables"]
+                existing.default_port = tool_data.get("default_port", 0)
+                logger.info("Updated built-in tool type: %s", tool_data["name"])
+
+        await session.commit()
+        logger.info("Built-in tool types seeded successfully.")

apps/api/src/services/build/docker_build.py

@@ -6,7 +6,9 @@ import subprocess
 logger = logging.getLogger(__name__)
 
 
-def build_image(instance_dir: str, dockerfile: str, tag: str, build_context: dict | None = None) -> tuple[int, str, str]:
+def build_image(
+    instance_dir: str, dockerfile: str, tag: str, build_context: dict | None = None
+) -> tuple[int, str, str]:
     """Build a Docker image from a Dockerfile.
 
     Args:
@@ -20,10 +22,16 @@ def build_image(instance_dir: str, dockerfile: str, tag: str, build_context: dic
     """
     from pathlib import Path
 
+    # Defensive: normalise any CRLF that may have crept in from manifest DB
+    # strings — Docker's legacy builder treats \r as a character after the
+    # backslash, breaking RUN continuations and producing
+    # "unknown instruction" errors.
+    dockerfile = dockerfile.replace("\r\n", "\n").replace("\r", "\n")
+
     # Write Dockerfile
     dockerfile_path = Path(instance_dir) / "Dockerfile"
-    dockerfile_path.write_text(dockerfile)
-    logger.debug("Wrote Dockerfile to %s", dockerfile_path)
+    dockerfile_path.write_text(dockerfile, newline="\n")
+    logger.debug("Wrote Dockerfile to %s (%d bytes)", dockerfile_path, len(dockerfile))
 
     # Write build context files
     if build_context:
@@ -33,19 +41,27 @@ def build_image(instance_dir: str, dockerfile: str, tag: str, build_context: dic
             try:
                 full_path.resolve().relative_to(Path(instance_dir).resolve())
             except ValueError:
-                logger.error("Build context file path escapes instance directory: %s", file_path)
-                raise ValueError(f"Build context file path '{file_path}' escapes instance directory")
-            
+                logger.error(
+                    "Build context file path escapes instance directory: %s", file_path
+                )
+                raise ValueError(
+                    f"Build context file path '{file_path}' escapes instance directory"
+                )
+
             full_path.parent.mkdir(parents=True, exist_ok=True)
-            full_path.write_text(content)
+            normalized = content.replace("\r\n", "\n").replace("\r", "\n")
+            full_path.write_text(normalized, newline="\n")
             logger.debug("Wrote build context file: %s", full_path)
 
     # Build image
     logger.debug("Building Docker image with tag: %s", tag)
     cmd = [
-        "docker", "build",
-        "-t", tag,
-        "-f", str(dockerfile_path),
+        "docker",
+        "build",
+        "-t",
+        tag,
+        "-f",
+        str(dockerfile_path),
         instance_dir,
     ]
 

apps/api/src/services/build/manifest_compiler.py

@@ -8,6 +8,8 @@ from typing import Any
 
 import yaml
 
+from src.services.docker import sort_volumes_by_specificity
+
 
 def resolve_base(manifest: dict) -> dict:
     """Merge a base definition into a tool manifest.
@@ -24,7 +26,7 @@ def resolve_base(manifest: dict) -> dict:
     result = deepcopy(manifest)
 
     base_definition_id = result.pop("base_definition_id", None)
-    base_version = result.pop("base_version", "latest")
+    result.pop("base_version", None)
 
     if base_definition_id:
         # This will be provided by the caller (they have the DB session)
@@ -116,11 +118,16 @@ def compile_dockerfile(manifest: dict) -> str:
 
     # System packages (apt)
     apt_packages = manifest.get("packages", {}).get("apt", [])
+    if manifest.get("user"):
+        # Ensure sudo is available for permission-fixing startup scripts
+        apt_packages = list(apt_packages)
+        if "sudo" not in apt_packages:
+            apt_packages.append("sudo")
     if apt_packages:
-        lines.append("RUN apt-get update && apt-get install -y \\\\")
+        lines.append("RUN apt-get update && apt-get install -y \\")
         for pkg in apt_packages[:-1]:
-            lines.append(f"    {pkg} \\\\")
-        lines.append(f"    {apt_packages[-1]} \\\\")
+            lines.append(f"    {pkg} \\")
+        lines.append(f"    {apt_packages[-1]} \\")
         lines.append("    && rm -rf /var/lib/apt/lists/*")
         lines.append("")
 
@@ -129,9 +136,9 @@ def compile_dockerfile(manifest: dict) -> str:
     if node:
         version = node.get("version", "20")
         lines.append(
-            f"RUN curl -fsSL https://deb.nodesource.com/setup_{version}.x | bash - && \\\\"
+            f"RUN curl -fsSL https://deb.nodesource.com/setup_{version}.x | bash - && \\"
         )
-        lines.append("    apt-get install -y nodejs && \\\\")
+        lines.append("    apt-get install -y nodejs && \\")
         lines.append("    rm -rf /var/lib/apt/lists/*")
         lines.append("")
 
@@ -157,9 +164,25 @@ def compile_dockerfile(manifest: dict) -> str:
         gid = user["gid"]
         create_home = "-m " if user.get("create_home", True) else ""
         shell = user.get("shell", "/bin/bash")
-        lines.append(f"RUN groupadd -g {gid} {name} && \\\\")
+        lines.append(f"RUN groupadd -g {gid} {name} && \\")
         lines.append(f"    useradd -u {uid} -g {gid} {create_home}-s {shell} {name}")
         lines.append("")
+        # Set HOME and USER for runtime compatibility
+        home = f"/home/{name}"
+        lines.append(f"ENV HOME={home}")
+        lines.append(f"ENV USER={name}")
+        lines.append("")
+        # Ensure home directory exists and is writable by the user
+        lines.append(
+            f"RUN mkdir -p {home} && chown {name}:{name} {home} && chmod 755 {home}"
+        )
+        lines.append("")
+
+        # Configure passwordless sudo so startup scripts can fix permissions
+        lines.append(
+            f'RUN echo "{name} ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/{name} && chmod 0440 /etc/sudoers.d/{name}'
+        )
+        lines.append("")
 
     # Build scripts
     build_scripts = manifest.get("scripts", {}).get("build", [])
@@ -174,6 +197,11 @@ def compile_dockerfile(manifest: dict) -> str:
     if build_scripts:
         lines.append("")
 
+    # After build scripts, ensure everything in home is owned by the user
+    if user and build_scripts:
+        lines.append(f"RUN chown -R {name}:{name} {home}")
+        lines.append("")
+
     # Create mount target directories
     mounts = manifest.get("mounts", [])
     if mounts:
@@ -298,10 +326,24 @@ def compile_compose(manifest: dict, variables: dict[str, Any]) -> str:
         volumes.append(vol_str)
 
     if volumes:
-        service["volumes"] = volumes
+        service["volumes"] = sort_volumes_by_specificity(volumes)
 
     compose = {"services": {"app": service}}
-    return yaml.dump(compose, default_flow_style=False)
+    result = yaml.dump(compose, default_flow_style=False)
+
+    # Debug: log mount resolution so we can diagnose missing mounts
+    import logging
+    logger = logging.getLogger(__name__)
+    logger.debug(
+        "compile_compose: REPO_PATH=%s SSH_PATH=%s EXTRA_VOLUMES=%s mounts=%s volumes=%s",
+        variables.get("REPO_PATH", "<empty>"),
+        variables.get("SSH_PATH", "<empty>"),
+        variables.get("EXTRA_VOLUMES", []),
+        manifest.get("mounts", []),
+        volumes,
+    )
+
+    return result
 
 
 def resolve_mount_source(mount: dict, variables: dict[str, Any]) -> str:
@@ -333,6 +375,21 @@ def resolve_mount_source(mount: dict, variables: dict[str, Any]) -> str:
     return ""
 
 
+def get_manifest_home_dir(manifest: dict) -> str:
+    """Get the home directory for a container based on manifest user config.
+
+    Args:
+        manifest: Fully resolved manifest JSON.
+
+    Returns:
+        Home directory path (e.g., /home/user or /root).
+    """
+    user = manifest.get("user")
+    if user and user.get("name"):
+        return f"/home/{user['name']}"
+    return "/root"
+
+
 def compute_image_tag(tool_name: str, manifest: dict) -> str:
     """Compute a deterministic image tag from manifest content.
 

apps/api/src/services/config/__init__.py

@@ -0,0 +1,25 @@
+"""Config profile services module."""
+
+from src.services.config.config_profile_resolver import (
+    ConfigProfileCycleError,
+    ConfigProfileNotFoundError,
+    ResolvedMount,
+    ResolvedProfile,
+    apply_resolved_profile,
+    check_include_cycle,
+    expand_container_path,
+    resolve_profile,
+    resolved_profile_to_dict,
+)
+
+__all__ = [
+    "ConfigProfileCycleError",
+    "ConfigProfileNotFoundError",
+    "ResolvedMount",
+    "ResolvedProfile",
+    "apply_resolved_profile",
+    "check_include_cycle",
+    "expand_container_path",
+    "resolve_profile",
+    "resolved_profile_to_dict",
+]

apps/api/src/services/config/config_profile_resolver.py

@@ -5,6 +5,7 @@ and cycle protection.
 """
 
 import logging
+import os
 import uuid
 from dataclasses import dataclass, field
 from typing import Any
@@ -12,7 +13,7 @@ from typing import Any
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from src.models.config_profile import ConfigProfile, ConfigProfileInclude
+from src.models import ConfigProfile, ConfigProfileInclude
 
 logger = logging.getLogger(__name__)
 
@@ -57,7 +58,9 @@ class ResolvedProfile:
     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:
+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:
@@ -176,21 +179,59 @@ def _merge_git_mounts(
 ) -> list[dict[str, Any]]:
     """Merge git mounts from included profiles.
 
-    Later mounts override earlier ones with the same remote_url + target_path combo.
+    Entries with the same remote_url + branch have their mappings concatenated.
+    Different repos are kept as separate entries.
+    All entries are normalized to the mappings format.
     """
     result = list(base)
-    # Build lookup by (remote_url, target_path)
-    seen = {(m["remote_url"], m["target_path"]): i for i, m in enumerate(result)}
+    # Normalize existing entries to mappings format
+    for i, m in enumerate(result):
+        result[i] = _normalize_git_mount_entry(dict(m))
+
+    # Build lookup by (remote_url, branch)
+    seen = {}
+    for i, m in enumerate(result):
+        key = (m["remote_url"], m.get("branch"))
+        seen[key] = i
+
     for mount in overlay:
-        key = (mount["remote_url"], mount["target_path"])
+        mount = _normalize_git_mount_entry(dict(mount))
+        key = (mount["remote_url"], mount.get("branch"))
         if key in seen:
-            result[seen[key]] = dict(mount)
+            # Same repo+branch: concatenate mappings, dedup by (source_path, target_path)
+            existing = result[seen[key]]
+            existing_sources = {
+                (m["source_path"], m["target_path"])
+                for m in existing.get("mappings", [])
+            }
+            for mapping in mount.get("mappings", []):
+                map_key = (mapping["source_path"], mapping["target_path"])
+                if map_key not in existing_sources:
+                    existing["mappings"].append(dict(mapping))
+                    existing_sources.add(map_key)
         else:
             seen[key] = len(result)
-            result.append(dict(mount))
+            result.append(mount)
     return result
 
 
+def _normalize_git_mount_entry(entry: dict[str, Any]) -> dict[str, Any]:
+    """Normalize a git mount entry to the unified mappings format.
+
+    Converts legacy source_path + target_path into a single-entry mappings array.
+    """
+    entry = dict(entry)
+    if "mappings" not in entry or not entry.get("mappings"):
+        source = entry.get("source_path", ".")
+        target = entry.get("target_path")
+        if target is not None:
+            entry["mappings"] = [{"source_path": source, "target_path": target}]
+    # Remove legacy fields once normalized
+    entry.pop("source_path", None)
+    entry.pop("target_path", None)
+    return entry
+
+
 async def _resolve_profile_recursive(
     session: AsyncSession,
     profile_id: uuid.UUID,
@@ -214,7 +255,9 @@ async def _resolve_profile_recursive(
     """
     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}")
+        raise ConfigProfileCycleError(
+            f"Cycle detected in profile includes: {cycle_path}"
+        )
 
     profile = await session.get(ConfigProfile, profile_id)
     if profile is None:
@@ -241,13 +284,18 @@ async def _resolve_profile_recursive(
         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.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.env_vars,
+            included.env_vars,
+            result.env_overrides,
+            included.profile_name,
         )
         result.runtime_hints = _merge_runtime_hints(
             result.runtime_hints,
@@ -391,6 +439,7 @@ async def check_include_cycle(
 def apply_resolved_profile(
     instance_dir: str,
     resolved: ResolvedProfile,
+    home_dir: str = "/root",
 ) -> tuple[dict[str, str], dict[str, str], list[dict], dict[str, Any]]:
     """Apply a resolved profile to an instance directory.
 
@@ -420,14 +469,19 @@ def apply_resolved_profile(
         try:
             full_path.resolve().relative_to(instance_path.resolve())
         except ValueError:
-            logger.warning("Profile file path escapes instance directory: %s", file_path)
+            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("/", "_")
+        expanded_target = expand_container_path(mount.target, home_dir)
+        mount_dir = (
+            instance_path / "mounts" / expanded_target.lstrip("/").replace("/", "_")
+        )
         mount_dir.mkdir(parents=True, exist_ok=True)
 
         for file_path, content in mount.files.items():
@@ -440,15 +494,44 @@ def apply_resolved_profile(
             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",
-        })
+            # Mount each file individually so sibling files from other mounts
+            # (e.g. git repo directories) are preserved.
+            file_target = os.path.join(expanded_target, file_path)
+            volume_mounts.append(
+                {
+                    "source": str(full_path),
+                    "target": file_target,
+                    "type": "bind",
+                }
+            )
 
     return env_vars, files, volume_mounts, resolved.runtime_hints
 
 
+def expand_container_path(path: str, home_dir: str) -> str:
+    """Expand ~ and $HOME in a container path to the actual home directory.
+
+    Only expands at the start of the path (e.g., ~/foo, $HOME/foo, $HOME).
+    Leaves mid-string occurrences unchanged.
+
+    Args:
+        path: Container path that may contain ~ or $HOME.
+        home_dir: The container's home directory (e.g., /home/user or /root).
+
+    Returns:
+        Path with ~ and $HOME expanded.
+    """
+    if path.startswith("~/"):
+        return os.path.join(home_dir, path[2:])
+    if path == "~":
+        return home_dir
+    if path.startswith("$HOME/"):
+        return home_dir + "/" + path[6:]
+    if path == "$HOME":
+        return home_dir
+    return path
+
+
 def resolved_profile_to_dict(resolved: ResolvedProfile) -> dict[str, Any]:
     """Convert a ResolvedProfile to a plain dict for serialization.
 

apps/api/src/services/docker.py

@@ -1,556 +0,0 @@
-"""Docker service for managing tool instances."""
-
-import os
-import re
-import subprocess
-import time
-from pathlib import Path
-from typing import Any
-
-
-def render_compose_template(template: str, variables: dict[str, Any]) -> str:
-    """Render a Docker Compose template with variable substitution.
-
-    Args:
-        template: The compose template string
-        variables: Dictionary of variable names to values
-
-    Returns:
-        Rendered compose file content
-    """
-    result = template
-    for key, value in variables.items():
-        placeholder = f"{{{{{key}}}}}"
-        result = result.replace(placeholder, str(value))
-    return result
-
-
-def ensure_instance_directory(instance_id: str, base_path: str | None = None) -> str:
-    """Create and return the instance directory path.
-
-    Args:
-        instance_id: Unique instance identifier
-        base_path: Base directory for all instances (defaults to Settings.instance_base_path)
-
-    Returns:
-        Absolute path to instance directory
-    """
-    if base_path is None:
-        from src.config import Settings
-
-        base_path = Settings().instance_base_path
-    instance_dir = Path(base_path) / instance_id
-    instance_dir.mkdir(parents=True, exist_ok=True)
-    return str(instance_dir.absolute())
-
-
-def write_compose_file(instance_dir: str, content: str) -> str:
-    """Write the rendered compose file to the instance directory.
-
-    Args:
-        instance_dir: Path to instance directory
-        content: Rendered compose content
-
-    Returns:
-        Path to the compose file
-    """
-    compose_path = Path(instance_dir) / "docker-compose.yml"
-    compose_path.write_text(content)
-    return str(compose_path)
-
-
-def write_env_file(instance_dir: str, env_vars: dict[str, str]) -> str:
-    """Write environment variables to a .env file.
-
-    Args:
-        instance_dir: Path to instance directory
-        env_vars: Dictionary of env var names to values
-
-    Returns:
-        Path to the env file
-    """
-    env_path = Path(instance_dir) / ".env"
-    lines = [f'{key}="{value}"' for key, value in env_vars.items()]
-    env_path.write_text("\n".join(lines) + "\n")
-    return str(env_path)
-
-
-def write_config_files(instance_dir: str, files: dict[str, str]) -> None:
-    """Write config files to the instance directory.
-
-    Args:
-        instance_dir: Path to instance directory
-        files: Dictionary of file paths (relative to instance dir) to content
-    """
-    instance_path = Path(instance_dir)
-    for file_path, content in files.items():
-        # Ensure the path is within the instance directory (security)
-        full_path = instance_path / file_path
-        try:
-            full_path.resolve().relative_to(instance_path.resolve())
-        except ValueError:
-            raise ValueError(f"File path '{file_path}' escapes instance directory")
-
-        full_path.parent.mkdir(parents=True, exist_ok=True)
-        full_path.write_text(content)
-
-
-def execute_compose_command(
-    compose_path: str, action: str, timeout: int = 60, env_file: str | None = None
-) -> tuple[int, str, str]:
-    """Execute a docker compose command.
-
-    Args:
-        compose_path: Path to docker-compose.yml
-        action: The compose action (up, down, start, stop, restart)
-        timeout: Command timeout in seconds
-        env_file: Optional path to .env file for environment variables
-
-    Returns:
-        Tuple of (returncode, stdout, stderr)
-    """
-    instance_dir = Path(compose_path).parent
-
-    cmd = ["docker", "compose", "-f", compose_path]
-
-    if env_file:
-        cmd.extend(["--env-file", env_file])
-
-    if action == "up":
-        cmd.extend(["up", "-d"])
-    elif action == "down":
-        cmd.extend(["down", "-v"])
-    elif action in ("start", "stop", "restart"):
-        cmd.append(action)
-    else:
-        raise ValueError(f"Unknown compose action: {action}")
-
-    result = subprocess.run(
-        cmd,
-        cwd=str(instance_dir),
-        capture_output=True,
-        text=True,
-        timeout=timeout,
-    )
-
-    return result.returncode, result.stdout, result.stderr
-
-
-def get_container_id(instance_name: str) -> str | None:
-    """Get the container ID for a compose service.
-
-    Searches all containers including stopped/exited ones.
-
-    Args:
-        instance_name: The service name in compose
-
-    Returns:
-        Container ID or None if not found
-    """
-    # Docker container names are lowercase internally; normalize to ensure match
-    result = subprocess.run(
-        ["docker", "ps", "-a", "-q", "--filter", f"name={instance_name.lower()}"],
-        capture_output=True,
-        text=True,
-    )
-
-    if result.returncode == 0 and result.stdout.strip():
-        return result.stdout.strip().split("\n")[0]
-    return None
-
-
-def get_container_name(instance_name: str) -> str | None:
-    """Get the full container name for a compose service.
-
-    Searches all containers including stopped/exited ones.
-
-    Args:
-        instance_name: The service name in compose
-
-    Returns:
-        Container name or None if not found
-    """
-    # Docker container names are lowercase internally; normalize to ensure match
-    result = subprocess.run(
-        [
-            "docker",
-            "ps",
-            "-a",
-            "--format",
-            "{{.Names}}",
-            "--filter",
-            f"name={instance_name.lower()}",
-        ],
-        capture_output=True,
-        text=True,
-    )
-
-    if result.returncode == 0 and result.stdout.strip():
-        return result.stdout.strip().split("\n")[0]
-    return None
-
-
-def connect_container_to_network(
-    container_name: str, network_name: str = "backend"
-) -> bool:
-    """Connect a Docker container to an existing network.
-
-    Args:
-        container_name: Name or ID of the container
-        network_name: Name of the Docker network (default: backend)
-
-    Returns:
-        True if successful, False otherwise
-    """
-    result = subprocess.run(
-        ["docker", "network", "connect", network_name, container_name],
-        capture_output=True,
-        text=True,
-    )
-    return result.returncode == 0
-
-
-def get_container_status(container_id: str) -> dict[str, Any]:
-    """Get the status of a Docker container.
-
-    Args:
-        container_id: Docker container ID
-
-    Returns:
-        Dict with 'status' (running, exited, restarting, not_found),
-        'exit_code' (int or None), and 'health' (health status or None)
-    """
-    result = subprocess.run(
-        [
-            "docker",
-            "inspect",
-            "-f",
-            "{{.State.Status}}|{{.State.ExitCode}}|{{if .State.Health}}{{.State.Health.Status}}{{else}}none{{end}}",
-            container_id,
-        ],
-        capture_output=True,
-        text=True,
-    )
-
-    if result.returncode != 0:
-        return {"status": "not_found", "exit_code": None, "health": None}
-
-    parts = result.stdout.strip().split("|")
-    status = parts[0] if parts else "unknown"
-    exit_code = int(parts[1]) if len(parts) > 1 and parts[1].isdigit() else None
-    health = parts[2] if len(parts) > 2 and parts[2] != "none" else None
-
-    return {"status": status, "exit_code": exit_code, "health": health}
-
-
-def wait_for_container_running(
-    container_id: str, timeout: int = 30, interval: float = 2.0
-) -> dict[str, Any]:
-    """Wait for a container to reach the running state.
-
-    Polls docker inspect until the container status is "running" or timeout.
-
-    Args:
-        container_id: Docker container ID
-        timeout: Maximum seconds to wait
-        interval: Seconds between polls
-
-    Returns:
-        Dict with 'success' (bool), 'status' (str), 'exit_code' (int or None),
-        and 'waited_seconds' (float)
-    """
-
-    start_time = time.time()
-
-    while time.time() - start_time < timeout:
-        info = get_container_status(container_id)
-
-        if info["status"] == "running":
-            return {
-                "success": True,
-                "status": "running",
-                "exit_code": None,
-                "waited_seconds": time.time() - start_time,
-            }
-
-        if info["status"] == "exited":
-            return {
-                "success": False,
-                "status": "exited",
-                "exit_code": info["exit_code"],
-                "waited_seconds": time.time() - start_time,
-            }
-
-        if info["status"] == "not_found":
-            return {
-                "success": False,
-                "status": "not_found",
-                "exit_code": None,
-                "waited_seconds": time.time() - start_time,
-            }
-
-        time.sleep(interval)
-
-    # Timeout reached
-    info = get_container_status(container_id)
-    return {
-        "success": False,
-        "status": info["status"],
-        "exit_code": info["exit_code"],
-        "waited_seconds": time.time() - start_time,
-    }
-
-
-def get_container_logs(container_id: str, tail: int = 100) -> str:
-    """Get the logs of a Docker container.
-
-    Args:
-        container_id: Docker container ID
-        tail: Number of lines to return
-
-    Returns:
-        Container logs
-    """
-    result = subprocess.run(
-        ["docker", "logs", "--tail", str(tail), container_id],
-        capture_output=True,
-        text=True,
-    )
-
-    if result.returncode == 0:
-        return result.stdout
-    return f"Failed to get logs: {result.stderr}"
-
-
-def find_free_port(start: int = 10000, end: int = 20000) -> int:
-    """Find a free TCP port in the given range.
-
-    Args:
-        start: Start of port range
-        end: End of port range
-
-    Returns:
-        Free port number
-    """
-    import socket
-
-    for port in range(start, end):
-        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
-            if s.connect_ex(("localhost", port)) != 0:
-                return port
-
-    raise RuntimeError(f"No free port found in range {start}-{end}")
-
-
-def start_cloudflared_tunnel(
-    container_name: str, port: int, timeout: int = 30
-) -> dict[str, str]:
-    """Start a temporary Cloudflare tunnel for a container.
-
-    Uses 'cloudflared tunnel --url' to create a temporary tunnel
-    with a random trycloudflare.com URL.
-
-    Args:
-        container_name: Name of the Docker container to tunnel to
-        port: Port number the container listens on
-        timeout: Maximum seconds to wait for tunnel URL
-
-    Returns:
-        Dict with 'url' (the public tunnel URL) and 'pid' (process ID)
-    """
-    import subprocess
-    import logging
-
-    logger = logging.getLogger(__name__)
-
-    # First verify the container is accessible
-    logger.info("Checking connectivity to %s:%d...", container_name, port)
-    for attempt in range(10):
-        check = subprocess.run(
-            [
-                "curl",
-                "-s",
-                "-o",
-                "/dev/null",
-                "-w",
-                "%{http_code}",
-                f"http://{container_name}:{port}",
-            ],
-            capture_output=True,
-            text=True,
-            timeout=5,
-        )
-        logger.info(
-            "Connectivity check %d: http_code=%s", attempt + 1, check.stdout.strip()
-        )
-        if check.returncode == 0:
-            break
-        time.sleep(1)
-    else:
-        logger.warning(
-            "Container %s:%d not responding to curl checks", container_name, port
-        )
-
-    # Run cloudflared in background, capture output
-    logger.info("Starting cloudflared tunnel to http://%s:%d", container_name, port)
-    proc = subprocess.Popen(
-        ["cloudflared", "tunnel", "--url", f"http://{container_name}:{port}"],
-        stdout=subprocess.PIPE,
-        stderr=subprocess.STDOUT,
-        text=True,
-    )
-
-    # Wait for the URL to appear in output
-    url_pattern = re.compile(r"https://[a-z0-9-]+\.trycloudflare\.com")
-    start_time = time.time()
-    url = None
-
-    if proc.stdout is None:
-        proc.terminate()
-        proc.wait(timeout=5)
-        raise RuntimeError("Failed to capture cloudflared output")
-
-    while time.time() - start_time < timeout:
-        # Read available output
-        import select
-
-        readable, _, _ = select.select([proc.stdout], [], [], 1.0)
-        if readable:
-            line = proc.stdout.readline()
-            if line:
-                match = url_pattern.search(line)
-                if match:
-                    url = match.group(0)
-                    break
-
-    if not url:
-        proc.terminate()
-        proc.wait(timeout=5)
-        raise RuntimeError(
-            f"Failed to get tunnel URL within {timeout}s. "
-            f"cloudflared output may contain errors."
-        )
-
-    return {"url": url, "pid": str(proc.pid)}
-
-
-def stop_cloudflared_tunnel(pid: str) -> None:
-    """Stop a cloudflared tunnel process.
-
-    Args:
-        pid: Process ID of the cloudflared tunnel
-    """
-    import signal
-
-    try:
-        os.kill(int(pid), signal.SIGTERM)
-    except ProcessLookupError:
-        pass  # Already stopped
-
-
-def recreate_tunnel(
-    container_name: str, port: int, old_pid: str | None = None
-) -> dict[str, str]:
-    """Recreate a temporary Cloudflare tunnel.
-
-    Stops the old tunnel (if pid provided) and starts a new one.
-
-    Args:
-        container_name: Name of the Docker container to tunnel to
-        port: Port number the container listens on
-        old_pid: Optional PID of the old tunnel process to stop
-
-    Returns:
-        Dict with 'url' and 'pid' for the new tunnel
-    """
-    if old_pid:
-        stop_cloudflared_tunnel(old_pid)
-
-    return start_cloudflared_tunnel(container_name, port)
-
-
-def check_tunnel_health(url: str, timeout: int = 10) -> dict[str, Any]:
-    """Check if a tunnel URL is healthy with smart error classification.
-
-    Args:
-        url: The tunnel URL to check
-        timeout: Request timeout in seconds
-
-    Returns:
-        Dict with 'tunnel_status' (healthy, unreachable, error_response, not_applicable),
-        'status_code' (int or None), 'healthy' (bool), and 'error' (str or None)
-    """
-    import subprocess
-
-    try:
-        result = subprocess.run(
-            [
-                "curl",
-                "-s",
-                "-o",
-                "/dev/null",
-                "-w",
-                "%{http_code}",
-                "--max-time",
-                str(timeout),
-                url,
-            ],
-            capture_output=True,
-            text=True,
-            timeout=timeout + 5,
-        )
-        status_code = int(result.stdout.strip())
-
-        if 200 <= status_code < 400:
-            return {
-                "tunnel_status": "healthy",
-                "status_code": status_code,
-                "healthy": True,
-                "error": None,
-            }
-        elif status_code in (502, 503, 504):
-            # Application error, not tunnel error
-            return {
-                "tunnel_status": "error_response",
-                "status_code": status_code,
-                "healthy": False,
-                "error": f"Application returned HTTP {status_code}",
-            }
-        else:
-            return {
-                "tunnel_status": "error_response",
-                "status_code": status_code,
-                "healthy": False,
-                "error": f"HTTP {status_code}",
-            }
-    except subprocess.TimeoutExpired:
-        return {
-            "tunnel_status": "unreachable",
-            "status_code": None,
-            "healthy": False,
-            "error": "Tunnel request timed out",
-        }
-    except (ValueError, Exception) as e:
-        error_str = str(e).lower()
-        # Classify connection errors
-        if any(
-            err in error_str
-            for err in [
-                "connection refused",
-                "econnrefused",
-                "could not resolve",
-                "nodename",
-            ]
-        ):
-            return {
-                "tunnel_status": "unreachable",
-                "status_code": None,
-                "healthy": False,
-                "error": f"Tunnel unreachable: {e}",
-            }
-        return {
-            "tunnel_status": "unreachable",
-            "status_code": None,
-            "healthy": False,
-            "error": str(e),
-        }

apps/api/src/services/docker/__init__.py

@@ -0,0 +1,55 @@
+"""Docker services package for container and compose operations."""
+
+from src.services.docker.compose import (
+    execute_compose_command,
+    render_compose_template,
+    sort_volumes_by_specificity,
+    write_compose_file,
+)
+from src.services.docker.config_staging import (
+    ensure_instance_directory,
+    write_config_files,
+    write_env_file,
+)
+from src.services.docker.container import (
+    connect_container_to_network,
+    find_free_port,
+    get_backend_network_name,
+    get_container_id,
+    get_container_ip_on_network,
+    get_container_logs,
+    get_container_name,
+    get_container_status,
+    is_container_on_network,
+    wait_for_container_running,
+)
+from src.services.docker.tunnel import (
+    check_tunnel_health,
+    recreate_tunnel,
+    start_tunnel,
+    stop_tunnel,
+)
+
+__all__ = [
+    "check_tunnel_health",
+    "connect_container_to_network",
+    "ensure_instance_directory",
+    "execute_compose_command",
+    "find_free_port",
+    "get_backend_network_name",
+    "get_container_id",
+    "get_container_ip_on_network",
+    "get_container_logs",
+    "get_container_name",
+    "get_container_status",
+    "is_container_on_network",
+    "recreate_tunnel",
+    "render_compose_template",
+    "sort_volumes_by_specificity",
+    "start_tunnel",
+    "stop_tunnel",
+    "wait_for_container_running",
+    "write_compose_file",
+    "write_config_files",
+    "write_env_file",
+]

apps/api/src/services/docker/compose.py

@@ -0,0 +1,120 @@
+"""Docker Compose file generation and manipulation."""
+
+import logging
+import subprocess
+from collections import Counter
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def sort_volumes_by_specificity(volumes: list[str]) -> list[str]:
+    """Sort volume strings so parent paths come before child paths.
+
+    Docker Compose mounts volumes in array order. A later mount at a parent
+    path hides earlier mounts at child paths. By sorting shallow paths first
+    and deep paths last, deeper (more specific) mounts overlay correctly.
+
+    Volume format: source:target or source:target:type
+
+    Args:
+        volumes: List of Docker volume mount strings.
+
+    Returns:
+        Sorted list with parent paths before child paths.
+    """
+
+    def _target_depth(vol: str) -> int:
+        parts = vol.split(":")
+        if len(parts) < 2:
+            return 0
+        target = parts[1].rstrip("/")
+        if not target or target == "/":
+            return 0
+        return target.count("/")
+
+    # Detect duplicate targets and warn
+    targets = []
+    for vol in volumes:
+        parts = vol.split(":")
+        targets.append(parts[1] if len(parts) > 1 else "")
+    dupes = [t for t, c in Counter(targets).items() if c > 1]
+    if dupes:
+        logger.warning("Duplicate mount targets detected: %s", dupes)
+
+    # Stable sort: parent paths first, child paths last
+    return sorted(volumes, key=_target_depth)
+
+
+def render_compose_template(template: str, variables: dict[str, Any]) -> str:
+    """Render a Docker Compose template with variable substitution.
+
+    Args:
+        template: The compose template string
+        variables: Dictionary of variable names to values
+
+    Returns:
+        Rendered compose file content
+    """
+    result = template
+    for key, value in variables.items():
+        placeholder = f"{{{{{key}}}}}"
+        result = result.replace(placeholder, str(value))
+    return result
+
+
+def write_compose_file(instance_dir: str, content: str) -> str:
+    """Write the rendered compose file to the instance directory.
+
+    Args:
+        instance_dir: Path to instance directory
+        content: Rendered compose content
+
+    Returns:
+        Path to the compose file
+    """
+    compose_path = Path(instance_dir) / "docker-compose.yml"
+    compose_path.write_text(content)
+    return str(compose_path)
+
+
+def execute_compose_command(
+    compose_path: str, action: str, timeout: int = 60, env_file: str | None = None
+) -> tuple[int, str, str]:
+    """Execute a docker compose command.
+
+    Args:
+        compose_path: Path to docker-compose.yml
+        action: The compose action (up, down, start, stop, restart)
+        timeout: Command timeout in seconds
+        env_file: Optional path to .env file for environment variables
+
+    Returns:
+        Tuple of (returncode, stdout, stderr)
+    """
+    instance_dir = Path(compose_path).parent
+
+    cmd = ["docker", "compose", "-f", compose_path]
+
+    if env_file:
+        cmd.extend(["--env-file", env_file])
+
+    if action == "up":
+        cmd.extend(["up", "-d", "--force-recreate"])
+    elif action == "down":
+        cmd.extend(["down", "-v"])
+    elif action in ("start", "stop", "restart"):
+        cmd.append(action)
+    else:
+        raise ValueError(f"Unknown compose action: {action}")
+
+    result = subprocess.run(
+        cmd,
+        cwd=str(instance_dir),
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+    )
+
+    return result.returncode, result.stdout, result.stderr

apps/api/src/services/docker/config_staging.py

@@ -0,0 +1,61 @@
+"""Staging configuration files into instance directories."""
+
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+def ensure_instance_directory(instance_id: str, base_path: str | None = None) -> str:
+    """Create and return the instance directory path.
+
+    Args:
+        instance_id: Unique instance identifier
+        base_path: Base directory for all instances (defaults to Settings.instance_base_path)
+
+    Returns:
+        Absolute path to instance directory
+    """
+    if base_path is None:
+        from src.config import Settings
+
+        base_path = Settings().instance_base_path
+    instance_dir = Path(base_path) / instance_id
+    instance_dir.mkdir(parents=True, exist_ok=True)
+    return str(instance_dir.absolute())
+
+
+def write_env_file(instance_dir: str, env_vars: dict[str, str]) -> str:
+    """Write environment variables to a .env file.
+
+    Args:
+        instance_dir: Path to instance directory
+        env_vars: Dictionary of env var names to values
+
+    Returns:
+        Path to the env file
+    """
+    env_path = Path(instance_dir) / ".env"
+    lines = [f'{key}="{value}"' for key, value in env_vars.items()]
+    env_path.write_text("\n".join(lines) + "\n")
+    return str(env_path)
+
+
+def write_config_files(instance_dir: str, files: dict[str, str]) -> None:
+    """Write config files to the instance directory.
+
+    Args:
+        instance_dir: Path to instance directory
+        files: Dictionary of file paths (relative to instance dir) to content
+    """
+    instance_path = Path(instance_dir)
+    for file_path, content in files.items():
+        # Ensure the path is within the instance directory (security)
+        full_path = instance_path / file_path
+        try:
+            full_path.resolve().relative_to(instance_path.resolve())
+        except ValueError:
+            raise ValueError(f"File path '{file_path}' escapes instance directory")
+
+        full_path.parent.mkdir(parents=True, exist_ok=True)
+        full_path.write_text(content)

apps/api/src/services/docker/container.py

@@ -0,0 +1,316 @@
+"""Docker container runtime queries and network management."""
+
+import logging
+import subprocess
+import time
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def get_container_id(instance_name: str) -> str | None:
+    """Get the container ID for a compose service.
+
+    Uses exact name matching to avoid substring collisions with tunnel
+    containers (e.g. tunnel-code-server-... matching code-server-...).
+    Falls back to case-insensitive matching since Docker DNS is case-
+    insensitive but docker inspect is case-sensitive.
+
+    Args:
+        instance_name: The expected container name.
+
+    Returns:
+        Container ID or None if not found.
+    """
+    expected = instance_name.lower()
+
+    # Fast path: exact match via docker inspect
+    result = subprocess.run(
+        ["docker", "inspect", "-f", "{{.Id}}", expected],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode == 0 and result.stdout.strip():
+        return result.stdout.strip()
+
+    # Fallback: list all containers and do case-insensitive exact match
+    ps_result = subprocess.run(
+        ["docker", "ps", "-a", "--format", "{{.Names}}\t{{.ID}}"],
+        capture_output=True,
+        text=True,
+    )
+    if ps_result.returncode == 0:
+        for line in ps_result.stdout.strip().splitlines():
+            parts = line.split("\t")
+            if len(parts) == 2:
+                name, cid = parts
+                if name.lower() == expected:
+                    return cid
+    return None
+
+
+def get_container_name(instance_name: str) -> str | None:
+    """Get the full container name for a compose service.
+
+    Uses exact name matching via docker inspect to avoid substring collisions.
+
+    Args:
+        instance_name: The exact container name (case-insensitive for Docker).
+
+    Returns:
+        Container name or None if not found.
+    """
+    result = subprocess.run(
+        ["docker", "inspect", "-f", "{{.Name}}", instance_name.lower()],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode == 0 and result.stdout.strip():
+        return result.stdout.strip().lstrip("/")
+    return None
+
+
+def get_backend_network_name() -> str:
+    """Auto-detect the actual Docker network name for the backend network.
+
+    Docker Compose prefixes network names with the project directory name
+    (e.g. 'headquarter_backend' instead of 'backend'). We inspect the API
+    container itself to find the real network name it's connected to.
+
+    Returns:
+        The actual Docker network name, or 'backend' as fallback.
+    """
+    # Try to find the API container by its known name
+    api_container = "hq-api"
+    result = subprocess.run(
+        [
+            "docker",
+            "inspect",
+            "-f",
+            "{{range $k, $v := .NetworkSettings.Networks}}{{$k}} {{end}}",
+            api_container,
+        ],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode == 0 and result.stdout.strip():
+        networks = result.stdout.strip().split()
+        for net in networks:
+            if "backend" in net.lower():
+                return net
+        # API container is on some network — return the first one
+        return networks[0]
+    return "backend"
+
+
+def connect_container_to_network(
+    container_name: str, network_name: str | None = None
+) -> bool:
+    """Connect a Docker container to an existing network.
+
+    Args:
+        container_name: Name or ID of the container
+        network_name: Name of the Docker network. If None, auto-detects
+            from the API container's own network membership.
+
+    Returns:
+        True if successful, False otherwise
+    """
+    if network_name is None:
+        network_name = get_backend_network_name()
+    result = subprocess.run(
+        ["docker", "network", "connect", network_name, container_name],
+        capture_output=True,
+        text=True,
+    )
+    return result.returncode == 0
+
+
+def get_container_ip_on_network(
+    container_id: str, network_name: str | None = None
+) -> str | None:
+    """Get a container's IP address on a specific Docker network.
+
+    Args:
+        container_id: Docker container ID or name.
+        network_name: Network name. If None, auto-detects from the API container.
+
+    Returns:
+        IP address string, or None if the container is not on that network.
+    """
+    if network_name is None:
+        network_name = get_backend_network_name()
+    result = subprocess.run(
+        [
+            "docker",
+            "inspect",
+            "-f",
+            f"{{{{.NetworkSettings.Networks.{network_name}.IPAddress}}}}",
+            container_id,
+        ],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode == 0:
+        ip = result.stdout.strip()
+        if ip and ip != "<no value>":
+            return ip
+    return None
+
+
+def is_container_on_network(container_id: str, network_name: str | None = None) -> bool:
+    """Check whether a container is already attached to a Docker network.
+
+    Args:
+        container_id: Docker container ID or name.
+        network_name: Network name. If None, auto-detects from the API container.
+
+    Returns:
+        True if the container is on the network.
+    """
+    if network_name is None:
+        network_name = get_backend_network_name()
+    result = subprocess.run(
+        [
+            "docker",
+            "inspect",
+            "-f",
+            f"{{{{.NetworkSettings.Networks.{network_name}}}}}",
+            container_id,
+        ],
+        capture_output=True,
+        text=True,
+    )
+    return result.returncode == 0 and "<no value>" not in result.stdout
+
+
+def get_container_status(container_id: str) -> dict[str, Any]:
+    """Get the status of a Docker container.
+
+    Args:
+        container_id: Docker container ID
+
+    Returns:
+        Dict with 'status' (running, exited, restarting, not_found),
+        'exit_code' (int or None), and 'health' (health status or None)
+    """
+    result = subprocess.run(
+        [
+            "docker",
+            "inspect",
+            "-f",
+            "{{.State.Status}}|{{.State.ExitCode}}|{{if .State.Health}}{{.State.Health.Status}}{{else}}none{{end}}",
+            container_id,
+        ],
+        capture_output=True,
+        text=True,
+    )
+
+    if result.returncode != 0:
+        return {"status": "not_found", "exit_code": None, "health": None}
+
+    parts = result.stdout.strip().split("|")
+    status = parts[0] if parts else "unknown"
+    exit_code = int(parts[1]) if len(parts) > 1 and parts[1].isdigit() else None
+    health = parts[2] if len(parts) > 2 and parts[2] != "none" else None
+
+    return {"status": status, "exit_code": exit_code, "health": health}
+
+
+def wait_for_container_running(
+    container_id: str, timeout: int = 30, interval: float = 2.0
+) -> dict[str, Any]:
+    """Wait for a container to reach the running state.
+
+    Polls docker inspect until the container status is "running" or timeout.
+
+    Args:
+        container_id: Docker container ID
+        timeout: Maximum seconds to wait
+        interval: Seconds between polls
+
+    Returns:
+        Dict with 'success' (bool), 'status' (str), 'exit_code' (int or None),
+        and 'waited_seconds' (float)
+    """
+
+    start_time = time.time()
+
+    while time.time() - start_time < timeout:
+        info = get_container_status(container_id)
+
+        if info["status"] == "running":
+            return {
+                "success": True,
+                "status": "running",
+                "exit_code": None,
+                "waited_seconds": time.time() - start_time,
+            }
+
+        if info["status"] == "exited":
+            return {
+                "success": False,
+                "status": "exited",
+                "exit_code": info["exit_code"],
+                "waited_seconds": time.time() - start_time,
+            }
+
+        if info["status"] == "not_found":
+            return {
+                "success": False,
+                "status": "not_found",
+                "exit_code": None,
+                "waited_seconds": time.time() - start_time,
+            }
+
+        time.sleep(interval)
+
+    # Timeout reached
+    info = get_container_status(container_id)
+    return {
+        "success": False,
+        "status": info["status"],
+        "exit_code": info["exit_code"],
+        "waited_seconds": time.time() - start_time,
+    }
+
+
+def get_container_logs(container_id: str, tail: int = 100) -> str:
+    """Get the logs of a Docker container.
+
+    Args:
+        container_id: Docker container ID
+        tail: Number of lines to return
+
+    Returns:
+        Container logs
+    """
+    result = subprocess.run(
+        ["docker", "logs", "--tail", str(tail), container_id],
+        capture_output=True,
+        text=True,
+    )
+
+    if result.returncode == 0:
+        return result.stdout
+    return f"Failed to get logs: {result.stderr}"
+
+
+def find_free_port(start: int = 10000, end: int = 20000) -> int:
+    """Find a free TCP port in the given range.
+
+    Args:
+        start: Start of port range
+        end: End of port range
+
+    Returns:
+        Free port number
+    """
+    import socket
+
+    for port in range(start, end):
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            if s.connect_ex(("localhost", port)) != 0:
+                return port
+
+    raise RuntimeError(f"No free port found in range {start}-{end}")

apps/api/src/services/docker/tunnel.py

@@ -0,0 +1,281 @@
+"""Cloudflare tunnel management using cloudflared Docker containers.
+
+Each tunnel runs as a Docker container on the same 'backend' network as the API.
+cloudflared connects to the tool container by its Docker Compose service name
+(e.g. http://code-server-headquarter-34837cd3:8443).
+"""
+
+import logging
+import re
+import subprocess
+from typing import Any
+
+from src.services.docker.container import get_backend_network_name
+
+logger = logging.getLogger(__name__)
+
+TUNNEL_IMAGE = "cloudflare/cloudflared:latest"
+
+
+def _tunnel_container_name(instance_name: str) -> str:
+    return f"tunnel-{instance_name.lower()}"
+
+
+def _ensure_image() -> None:
+    """Pull cloudflared image if not already present."""
+    result = subprocess.run(
+        ["docker", "images", "-q", TUNNEL_IMAGE],
+        capture_output=True,
+        text=True,
+    )
+    if not result.stdout.strip():
+        logger.info("Pulling %s ...", TUNNEL_IMAGE)
+        pull = subprocess.run(
+            ["docker", "pull", TUNNEL_IMAGE],
+            capture_output=True,
+            text=True,
+        )
+        if pull.returncode != 0:
+            logger.warning("Failed to pull %s: %s", TUNNEL_IMAGE, pull.stderr)
+
+
+def _cleanup_stale_tunnel(tunnel_name: str) -> None:
+    """Remove any existing tunnel container with this name."""
+    subprocess.run(
+        ["docker", "stop", "-t", "3", tunnel_name],
+        capture_output=True,
+        text=True,
+    )
+    subprocess.run(
+        ["docker", "rm", "-f", tunnel_name],
+        capture_output=True,
+        text=True,
+    )
+
+
+def _get_tunnel_logs(tunnel_name: str) -> tuple[str, str]:
+    """Get stdout and stderr logs from a container."""
+    result = subprocess.run(
+        ["docker", "logs", tunnel_name],
+        capture_output=True,
+        text=True,
+    )
+    return result.stdout, result.stderr
+
+
+def _get_tunnel_exit_code(tunnel_name: str) -> int | None:
+    """Get exit code of a container if it has exited."""
+    result = subprocess.run(
+        ["docker", "inspect", "-f", "{{.State.ExitCode}}", tunnel_name],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode == 0:
+        try:
+            return int(result.stdout.strip())
+        except ValueError:
+            pass
+    return None
+
+
+def start_tunnel(
+    instance_name: str,
+    container_port: int,
+    timeout: int = 30,
+    target_url: str | None = None,
+) -> dict[str, str]:
+    """Start a temporary Cloudflare tunnel for an instance.
+
+    Args:
+        instance_name: The tool instance name (used for tunnel naming).
+        container_port: The port the tool container listens on internally.
+        timeout: Seconds to wait for the tunnel URL.
+        target_url: Optional explicit URL to proxy to. If omitted, derives
+            http://{instance_name.lower()}:{container_port}.
+
+    Returns:
+        Dict with 'url' and 'container_name'.
+    """
+    _ensure_image()
+
+    tunnel_name = _tunnel_container_name(instance_name)
+    _cleanup_stale_tunnel(tunnel_name)
+
+    # Target the tool container by name on the backend network
+    if target_url is None:
+        target_url = f"http://{instance_name.lower()}:{container_port}"
+
+    cmd = [
+        "docker",
+        "run",
+        "-d",
+        "--network",
+        get_backend_network_name(),
+        "--name",
+        tunnel_name,
+        TUNNEL_IMAGE,
+        "tunnel",
+        "--no-autoupdate",
+        "--url",
+        target_url,
+    ]
+
+    logger.debug("Running: %s", " ".join(cmd))
+    proc = subprocess.run(cmd, capture_output=True, text=True)
+    if proc.returncode != 0:
+        raise RuntimeError(
+            f"Failed to start tunnel container {tunnel_name}: {proc.stderr}"
+        )
+
+    container_id = proc.stdout.strip()
+    logger.debug("Tunnel container started: %s", container_id)
+
+    # Wait for URL to appear in logs
+    # Exclude api.trycloudflare.com which is the Cloudflare API endpoint,
+    # not a tunnel URL. Real tunnel URLs have random subdomains (10+ chars).
+    url_pattern = re.compile(r"https://(?!api\.)[a-z0-9-]{10,}\.trycloudflare\.com")
+    start_time = __import__("time").time()
+    url: str | None = None
+    combined_logs = ""
+
+    while __import__("time").time() - start_time < timeout:
+        stdout, stderr = _get_tunnel_logs(tunnel_name)
+        combined_logs = stdout + "\n" + stderr
+
+        match = url_pattern.search(combined_logs)
+        if match:
+            url = match.group(0)
+            break
+
+        # Check if container exited early
+        exit_code = _get_tunnel_exit_code(tunnel_name)
+        if exit_code is not None and exit_code != 0:
+            _cleanup_stale_tunnel(tunnel_name)
+            raise RuntimeError(
+                f"Tunnel container {tunnel_name} exited with code {exit_code}. "
+                f"Logs:\n{combined_logs[-3000:]}"
+            )
+
+        __import__("time").sleep(0.5)
+
+    if not url:
+        stdout, stderr = _get_tunnel_logs(tunnel_name)
+        combined_logs = stdout + "\n" + stderr
+        exit_code = _get_tunnel_exit_code(tunnel_name)
+
+        _cleanup_stale_tunnel(tunnel_name)
+        raise RuntimeError(
+            f"Tunnel {tunnel_name} did not produce a URL within {timeout}s. "
+            f"Exit code: {exit_code}. Logs:\n{combined_logs[-3000:]}"
+        )
+
+    # Wait a moment for Cloudflare DNS edge to propagate the new tunnel subdomain
+    __import__("time").sleep(2)
+
+    logger.info(
+        "Tunnel %s started for %s → %s (%s)",
+        tunnel_name,
+        instance_name,
+        target_url,
+        url,
+    )
+    return {"url": url, "container_name": tunnel_name}
+
+
+def stop_tunnel(instance_name: str) -> None:
+    """Stop and remove the tunnel container for an instance."""
+    tunnel_name = _tunnel_container_name(instance_name)
+    _cleanup_stale_tunnel(tunnel_name)
+    logger.debug("Stopped and removed tunnel container %s", tunnel_name)
+
+
+def recreate_tunnel(
+    instance_name: str, container_port: int, target_url: str | None = None
+) -> dict[str, str]:
+    """Recreate a tunnel for an instance.
+
+    Args:
+        instance_name: The tool instance name.
+        container_port: The port the tool container listens on internally.
+        target_url: Optional explicit origin URL. If omitted, derives
+            http://{instance_name.lower()}:{container_port}.
+    """
+    stop_tunnel(instance_name)
+    return start_tunnel(instance_name, container_port, target_url=target_url)
+
+
+def check_tunnel_health(url: str, timeout: int = 10) -> dict[str, Any]:
+    """Check if a tunnel URL is healthy.
+
+    Returns:
+        Dict with 'tunnel_status', 'status_code', 'healthy', 'error'.
+    """
+    try:
+        result = subprocess.run(
+            [
+                "curl",
+                "-s",
+                "-o",
+                "/dev/null",
+                "-w",
+                "%{http_code}",
+                "--max-time",
+                str(timeout),
+                url,
+            ],
+            capture_output=True,
+            text=True,
+            timeout=timeout + 5,
+        )
+        status_code = int(result.stdout.strip())
+
+        if 200 <= status_code < 400:
+            return {
+                "tunnel_status": "healthy",
+                "status_code": status_code,
+                "healthy": True,
+                "error": None,
+            }
+        if status_code in (502, 503, 504):
+            return {
+                "tunnel_status": "error_response",
+                "status_code": status_code,
+                "healthy": False,
+                "error": f"Application returned HTTP {status_code}",
+            }
+        return {
+            "tunnel_status": "error_response",
+            "status_code": status_code,
+            "healthy": False,
+            "error": f"HTTP {status_code}",
+        }
+    except subprocess.TimeoutExpired:
+        return {
+            "tunnel_status": "unreachable",
+            "status_code": None,
+            "healthy": False,
+            "error": "Tunnel request timed out",
+        }
+    except (ValueError, Exception) as exc:
+        error_str = str(exc).lower()
+        if any(
+            err in error_str
+            for err in [
+                "connection refused",
+                "econnrefused",
+                "could not resolve",
+                "nodename",
+            ]
+        ):
+            return {
+                "tunnel_status": "unreachable",
+                "status_code": None,
+                "healthy": False,
+                "error": f"Tunnel unreachable: {exc}",
+            }
+        return {
+            "tunnel_status": "unreachable",
+            "status_code": None,
+            "healthy": False,
+            "error": str(exc),
+        }

apps/api/src/services/git/__init__.py

@@ -0,0 +1,19 @@
+"""Git services module."""
+
+from src.services.git.clone import (
+    check_dirty_state,
+    clone_repository,
+    remove_clone_directory,
+)
+from src.services.git.git_operations import Commit, GitOperations, GitStatus
+from src.services.git.git_service import GitService
+
+__all__ = [
+    "check_dirty_state",
+    "clone_repository",
+    "remove_clone_directory",
+    "Commit",
+    "GitOperations",
+    "GitStatus",
+    "GitService",
+]