fix: handle bare repos in branch creation and checkout

- Fall back to symbolic-ref when checkout --orphan fails on bare repos\n- Fall back to symbolic-ref when checkout fails on bare repos\n- Make get_current_branch handle bare repos with unborn branches\n- Add integration tests for bare repo branch operations\n\nQuality gates: pytest integration tests (12 passed)

AGENTS.md

@@ -87,6 +87,31 @@ Do not claim completion without verification evidence.
 
 ## Git workflow
 
+### Branching strategy
+
+For every spec change or new functionality:
+
+1. Create a new branch from `dev` with a proper prefix:
+   - `feat/` for new features (e.g., `feat/tool-workshop`)
+   - `fix/` for bug fixes (e.g., `fix/terminal-tty`)
+   - `refactor/` for refactors (e.g., `refactor/api-cleanup`)
+   - `docs/` for documentation (e.g., `docs/api-guide`)
+   - `chore/` for maintenance (e.g., `chore/update-deps`)
+2. Branch name should reference the OpenSpec change name when applicable.
+3. Do not commit directly to `main` or `dev`.
+
+### Completion and merge
+
+When implementation is complete and verified:
+
+1. Ensure all tests pass and quality gates are met.
+2. Stage all changes with `git add -A`.
+3. Create a commit with a proper conventional commit message (see below).
+4. Switch to `dev`: `git checkout dev`.
+5. Merge the feature branch: `git merge --no-ff <branch-name>`.
+6. Push to remote: `git push origin dev`.
+7. Delete the local feature branch if desired: `git branch -d <branch-name>`.
+
 ### Auto-commit on spec completion
 
 When an OpenSpec change is fully implemented and all tasks are complete:

CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- **Project Management** - Create and manage projects with dashboard view
+- **Git Repository Management** - Bare repository initialization and mirror cloning with smart URL parsing
+- **Repository Workspace** - File browser with syntax highlighting, branch switching, and file editing
+- **Git History Visualization** - Commit history with graph visualization and diff viewing
+- **Git Control** - Branch management, commit, fetch/pull/push, merge operations
+- **File Editor** - Syntax highlighting for 50+ languages with edit/commit workflow
+- **Smart Git URL Parsing** - Automatic detection and correction of browser URLs to git clone URLs
+- **OAuth2 Authentication** - Session-based authentication via Authentik with simplified flow
+- **User Profile** - Profile management with avatar upload
+- **User Settings** - Theme selection, git identity, and preference management
+- **SSH Key Management** - Ed25519 key generation with secure storage
+- **Tool Types** - Built-in development tools (code-server, jupyter-notebook) with custom type support
+- **Comprehensive Documentation** - Architecture, API, deployment, and development guides
+
+### Changed
+
+- Simplified authentication from JWT to session-based cookies
+- Restructured test infrastructure with unit/integration/system separation
+- Improved Docker deployment with Traefik integration
+
+### Fixed
+
+- Database migration chain errors
+- Cross-origin cookie handling for OAuth flow
+- Nginx permission issues in container
+
+## [0.1.0] - 2026-05-19
+
+### Added
+
+- Initial release with core project and repository management
+- OAuth2 authentication with Authentik
+- Basic file browsing and git history viewing
+- Development tool type definitions

README.md

@@ -1,53 +1,195 @@
+# Headquarter
 
-## Testing Strategy
+A self-hosted platform for managing projects, git repositories, and development tools with OAuth2 authentication.
 
-The project uses a three-tier testing approach:
+## Overview
 
-### Test Categories
+Headquarter provides a centralized workspace for development teams to:
+- Manage projects and their associated git repositories
+- Browse repository files and view git history
+- Spawn development tools (VS Code Server, Jupyter Notebook, etc.)
+- Manage SSH keys and user preferences
 
-1. **Unit Tests** (`apps/api/tests/unit/`)
-   - Fast tests with no external dependencies
-   - Use SQLite in-memory database
-   - Run with: `make test-unit` or `pytest -m unit`
+## Features
 
-2. **Integration Tests** (`apps/api/tests/integration/`)
-   - Test API endpoints with database
-   - Use PostgreSQL with transaction rollback
-   - Run with: `make test-integration` or `pytest -m integration`
+### Project Management
+- Create and manage projects
+- View all projects in a dashboard
+- Click any project to open its workspace
 
-3. **System/E2E Tests** (`e2e/`)
-   - End-to-end tests using Playwright
-   - Test full user journeys
-   - Run with: `make test-e2e`
+### Git Repository Management
+- Initialize bare repositories
+- Clone repositories (including mirror clones)
+- Smart URL parsing (converts browser URLs to git URLs)
+- View repository history and commit details
 
-### Running Tests
+### Repository Workspace
+- Browse files and directories
+- View file contents with syntax highlighting
+- Switch between branches
+- Quick file editing with automatic commits
 
+### Git History Visualization
+- View commit history with branch graph
+- See commit details, statistics, and diffs
+- Filter by branch
+
+### Authentication
+- OAuth2 via Authentik
+- Session-based authentication
+- User profile management
+
+### Tool Management
+- Built-in tool types (code-server, jupyter-notebook)
+- Create custom tool types with Docker Compose templates
+- Template validation
+
+### User Settings
+- Theme selection (system/light/dark)
+- Git identity configuration
+- Default editor preference
+
+### SSH Key Management
+- Generate Ed25519 key pairs
+- Copy public keys to clipboard
+- Delete keys
+
+## Quick Start
+
+### Prerequisites
+- Docker and Docker Compose
+- Git
+
+### Local Development
+
+1. **Clone the repository:**
    ```bash
-# Run all tests (excludes system tests by default)
-make test
-
-# Run specific categories
-make test-unit          # Fast unit tests only
-make test-integration   # Integration tests with DB
-make test-system        # Full stack tests
-make test-e2e          # Browser-based E2E tests
-
-# Inside Docker container
-docker compose exec api pytest -v -m unit
-docker compose exec api pytest -v -m integration
+   git clone <repository-url>
+   cd headquarter
    ```
 
-### Test Markers
+2. **Set up environment:**
+   ```bash
+   cp .env.example .env
+   # Edit .env with your settings
+   ```
 
-Tests are marked with pytest markers:
-- `@pytest.mark.unit` - Fast, isolated tests
-- `@pytest.mark.integration` - Tests with database/external services
-- `@pytest.mark.system` - Full stack tests
+3. **Start services:**
+   ```bash
+   docker compose up -d
+   ```
 
-### Shared Fixtures
+4. **Access the application:**
+   - Frontend: http://localhost:5173
+   - API: http://localhost:8000
+   - API Docs: http://localhost:8000/docs
 
-Common fixtures are in `apps/api/tests/conftest.py`:
-- `sqlite_engine` - SQLite engine for unit tests
-- `postgres_engine` - PostgreSQL engine for integration tests
-- `db_session` - Database session with transaction rollback
-- `test_client` - FastAPI TestClient instance
+### Production Deployment
+
+See [Deployment Guide](docs/deployment/) for production setup with Traefik and Authentik.
+
+## Tech Stack
+
+### Backend
+- **FastAPI** - Python web framework
+- **SQLAlchemy** - ORM with async PostgreSQL support
+- **Pydantic** - Data validation
+- **Alembic** - Database migrations
+- **python-jose** - JWT handling
+
+### Frontend
+- **React** - UI library
+- **TypeScript** - Type safety
+- **Vite** - Build tool
+- **React Router** - Client-side routing
+
+### Infrastructure
+- **Docker** - Containerization
+- **PostgreSQL** - Database
+- **Traefik** - Reverse proxy (production)
+- **Authentik** - Identity provider
+
+## Documentation
+
+- [User Guide](docs/features/) - Feature documentation
+- [API Reference](docs/api/) - API endpoints
+- [Architecture](docs/architecture/) - System design
+- [Deployment](docs/deployment/) - Setup guides
+- [Development](docs/development/) - Contributing
+
+## Project Structure
+
+```
+.
+├── apps/
+│   ├── api/              # FastAPI backend
+│   │   ├── src/
+│   │   │   ├── api/      # API routes
+│   │   │   ├── auth/     # Authentication
+│   │   │   ├── models/   # Database models
+│   │   │   └── utils/    # Utilities
+│   │   ├── tests/        # Test suite
+│   │   └── Dockerfile
+│   └── web/              # React frontend
+│       ├── src/
+│       │   ├── api/      # API clients
+│       │   ├── components/# UI components
+│       │   └── pages/    # Page components
+│       └── Dockerfile
+├── docs/                 # Documentation
+├── docker-compose.yml    # Development setup
+├── docker-compose.traefik.yml  # Production setup
+└── Makefile             # Common commands
+```
+
+## Development
+
+### Backend Development
+```bash
+cd apps/api
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+uvicorn src.main:app --reload
+```
+
+### Frontend Development
+```bash
+cd apps/web
+npm install
+npm run dev
+```
+
+### Running Tests
+```bash
+# Backend tests
+make test
+
+# Frontend tests
+make test-web
+
+# All quality gates
+make lint
+make typecheck
+```
+
+## Configuration
+
+Key environment variables:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `API_DOMAIN` | API domain | `localhost` |
+| `WEB_DOMAIN` | Web domain | `localhost` |
+| `AUTHENTIK_DOMAIN` | Authentik domain | - |
+| `AUTHENTIK_CLIENT_ID` | OAuth client ID | - |
+| `AUTHENTIK_CLIENT_SECRET` | OAuth client secret | - |
+| `DATABASE_URL` | PostgreSQL URL | - |
+| `JWT_SECRET` | JWT signing secret | - |
+| `REPO_BASE_PATH` | Repository storage path | `/data/repos` |
+
+See [Environment Variables](docs/deployment/environment.md) for complete list.
+
+## License
+
+[License information]

apps/api/Dockerfile

@@ -16,34 +16,50 @@ RUN pip install --no-cache-dir --user -e ".[dev]"
 # Production stage
 FROM python:3.11-slim
 
-# Create non-root user
-RUN groupadd -r appgroup && useradd -r -g appgroup appuser
+# Create non-root user and add to docker group
+RUN groupadd -r appgroup && useradd -r -g appgroup appuser \
+    && groupadd -r docker || true \
+    && usermod -aG docker appuser
 
 WORKDIR /app
 
-# Install runtime dependencies
+# Install runtime dependencies including Docker CLI
 RUN apt-get update && apt-get install -y --no-install-recommends \
     libpq5 \
     git \
     netcat-openbsd \
+    ca-certificates \
+    curl \
+    gnupg \
+    && install -m 0755 -d /etc/apt/keyrings \
+    && curl -fsSL https://download.docker.com/linux/debian/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg \
+    && chmod a+r /etc/apt/keyrings/docker.gpg \
+    && echo "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian \
+    "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" > /etc/apt/sources.list.d/docker.list \
+    && apt-get update \
+    && apt-get install -y --no-install-recommends docker-ce-cli docker-compose-plugin \
+    && curl -L --output /usr/local/bin/cloudflared https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 \
+    && chmod +x /usr/local/bin/cloudflared \
     && rm -rf /var/lib/apt/lists/*
 
 # Copy dependencies from builder
-COPY --from=builder /root/.local /home/appuser/.local
-ENV PATH=/home/appuser/.local/bin:$PATH
+COPY --from=builder /root/.local /root/.local
+ENV PATH=/root/.local/bin:$PATH
 
 # Copy application code
 COPY --chown=appuser:appgroup . .
 
-# Create directories for repo storage
-RUN mkdir -p /data/repos && chown -R appuser:appgroup /data/repos
+# Create directories for repo and instance storage
+RUN mkdir -p /data/repos /data/instances && chown -R appuser:appgroup /data
 
 # Copy wait-for-db script
 COPY wait-for-db.sh /usr/local/bin/wait-for-db.sh
 RUN chmod +x /usr/local/bin/wait-for-db.sh
 
-# Switch to non-root user
-USER appuser
+# NOTE: Running as root to access Docker socket for managing tool instances
+# This is required because Docker socket permissions require root or docker group membership
+# which doesn't work well across container boundaries.
+# Consider using Docker-in-Docker or rootless Docker for production hardening.
 
 # Expose port
 EXPOSE 8000

apps/api/README.md

@@ -0,0 +1,252 @@
+# Headquarter API
+
+The backend API for Headquarter - a self-hosted platform for managing projects, git repositories, and development tools.
+
+## Overview
+
+Built with **FastAPI** and **SQLAlchemy** (async), using **PostgreSQL** for data storage and **Docker** for tool instance management.
+
+### Tech Stack
+
+- **Framework**: FastAPI (Python 3.12+)
+- **Database**: PostgreSQL 15+ with asyncpg
+- **ORM**: SQLAlchemy 2.0 (async)
+- **Auth**: OAuth2 via Authentik with session cookies
+- **Migrations**: Alembic
+- **Tools**: Docker Compose for instance management
+
+## Quick Start
+
+### Prerequisites
+
+- Python 3.12+
+- PostgreSQL 15+ running locally
+- Docker (for tool instances)
+
+### Setup
+
+```bash
+cd apps/api
+
+# Create virtual environment
+python -m venv .venv
+source .venv/bin/activate
+
+# Install dependencies
+pip install -e ".[dev]"
+
+# Set up database
+# Ensure PostgreSQL is running with a 'headquarter' database
+
+# Run migrations
+alembic upgrade head
+
+# Start development server
+uvicorn src.main:app --reload --port 8000
+```
+
+The API will be available at `http://localhost:8000`.
+
+### Interactive Documentation
+
+Once running, visit:
+- **Swagger UI**: http://localhost:8000/docs
+- **ReDoc**: http://localhost:8000/redoc
+- **OpenAPI JSON**: http://localhost:8000/openapi.json
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `DATABASE_URL` | Yes | - | PostgreSQL connection string |
+| `API_BASE_URL` | Yes | - | Public API URL (e.g., `https://api.example.com`) |
+| `AUTHENTIK_DOMAIN` | Yes | - | Authentik server domain |
+| `AUTHENTIK_CLIENT_ID` | Yes | - | OAuth2 client ID |
+| `AUTHENTIK_CLIENT_SECRET` | Yes | - | OAuth2 client secret |
+| `AUTHENTIK_APPLICATION_SLUG` | Yes | - | Authentik application slug |
+| `WEB_BASE_URL` | Yes | - | Public frontend URL |
+| `SESSION_SECRET` | Yes | - | Secret for session cookie signing |
+| `COOKIE_DOMAIN` | No | - | Cookie domain (e.g., `.example.com`) |
+| `UPLOAD_DIR` | No | `./uploads` | Directory for file uploads |
+| `REPO_BASE_PATH` | No | `./repositories` | Base path for git repositories |
+| `INSTANCES_BASE_PATH` | No | `./instances` | Base path for tool instances |
+| `LOG_LEVEL` | No | `INFO` | Logging level |
+
+## Development
+
+### Running Tests
+
+```bash
+# Run all tests
+pytest
+
+# Run specific test category
+pytest -m unit          # Unit tests (no DB)
+pytest -m integration   # Integration tests (requires DB)
+
+# Run with coverage
+pytest --cov=src --cov-report=html
+```
+
+### Code Quality
+
+```bash
+# Format code
+ruff format src tests
+
+# Lint
+ruff check src tests
+
+# Type check
+mypy src
+```
+
+### Database Migrations
+
+```bash
+# Create new migration
+alembic revision --autogenerate -m "description"
+
+# Apply migrations
+alembic upgrade head
+
+# Rollback one migration
+alembic downgrade -1
+
+# Show current revision
+alembic current
+```
+
+## Architecture
+
+### Directory Structure
+
+```
+src/
+├── api/              # API endpoint routers
+│   ├── auth.py       # OAuth2 authentication
+│   ├── dashboard.py  # Dashboard summary
+│   ├── git_repositories.py  # Git repo management
+│   ├── health.py     # Health checks
+│   ├── projects.py   # Project CRUD
+│   ├── ssh_keys.py   # SSH key management
+│   ├── terminal.py   # WebSocket terminal
+│   ├── tool_instances.py  # Tool instance management
+│   ├── tool_types.py # Tool type definitions
+│   ├── user_config.py # User preferences
+│   └── users.py      # User profile
+├── auth/             # Authentication logic
+│   ├── cookies.py    # Cookie utilities
+│   ├── dependencies.py # Auth dependencies
+│   ├── oidc.py       # OpenID Connect
+│   └── session.py    # Session management
+├── config.py         # Application settings
+├── database.py       # Database setup
+├── main.py           # FastAPI application
+├── models/           # SQLAlchemy models
+├── schemas/          # Pydantic schemas
+├── services/         # Business logic
+│   ├── docker.py     # Docker Compose management
+│   ├── terminal_manager.py  # Terminal sessions
+│   └── terminal_session.py  # Terminal I/O
+└── utils/            # Utilities
+    ├── git_control.py      # Git operations
+    ├── git_files.py        # File operations
+    ├── git_history.py      # History extraction
+    └── git_url_parser.py   # URL parsing
+```
+
+### Authentication Flow
+
+1. User clicks "Login" → redirects to Authentik OAuth
+2. Authentik redirects back with authorization code
+3. API exchanges code for tokens and fetches user info
+4. API creates session cookie (HMAC-signed, httpOnly)
+5. Frontend stores nothing - cookie sent automatically
+6. Subsequent requests include cookie for authentication
+
+### Data Flow
+
+```
+Client → FastAPI Router → Auth Dependency → Service Layer → Database
+                ↓
+         Pydantic Models (validation)
+                ↓
+         SQLAlchemy Models (ORM)
+                ↓
+         PostgreSQL (storage)
+```
+
+## API Endpoints
+
+### Authentication
+- `GET /auth/login` - Initiate OAuth login
+- `GET /auth/callback` - OAuth callback
+- `GET /auth/me` - Get current user
+- `POST /auth/logout` - Logout
+
+### Projects
+- `GET /projects` - List projects
+- `POST /projects` - Create project
+- `GET /projects/{id}` - Get project
+- `PUT /projects/{id}` - Update project
+- `DELETE /projects/{id}` - Delete project
+
+### Git Repositories
+- `GET /projects/{id}/repositories` - List repositories
+- `POST /projects/{id}/repositories` - Create repository
+- `GET /projects/{id}/repositories/{id}` - Get repository
+- `DELETE /projects/{id}/repositories/{id}` - Delete repository
+- `GET /projects/{id}/repositories/{id}/files` - List files
+- `GET /projects/{id}/repositories/{id}/files/content` - Get file content
+- `POST /projects/{id}/repositories/{id}/files/content` - Update file
+- `GET /projects/{id}/repositories/{id}/branches` - List branches
+- `GET /projects/{id}/repositories/{id}/history` - Commit history
+- `GET /projects/{id}/repositories/{id}/commits/{hash}` - Commit detail
+
+### Tool Types
+- `GET /tool-types` - List tool types
+- `POST /tool-types` - Create tool type
+- `GET /tool-types/{id}` - Get tool type
+- `PUT /tool-types/{id}` - Update tool type
+- `DELETE /tool-types/{id}` - Delete tool type
+
+### Tool Instances
+- `GET /tool-instances` - List instances
+- `POST /tool-instances` - Create instance
+- `GET /tool-instances/{id}` - Get instance
+- `POST /tool-instances/{id}/start` - Start instance
+- `POST /tool-instances/{id}/stop` - Stop instance
+- `POST /tool-instances/{id}/restart` - Restart instance
+- `DELETE /tool-instances/{id}` - Delete instance
+- `GET /tool-instances/{id}/logs` - Get logs
+
+### Terminal
+- `WS /ws/tool-instances/{id}/terminal` - WebSocket terminal
+
+### Users
+- `GET /users/me` - Get profile
+- `PUT /users/me` - Update profile
+- `POST /users/me/avatar` - Upload avatar
+- `GET /users/me/config` - Get config
+- `PATCH /users/me/config` - Update config
+
+### SSH Keys
+- `GET /ssh-keys` - List keys
+- `POST /ssh-keys` - Create key
+- `DELETE /ssh-keys/{id}` - Delete key
+
+### Health
+- `GET /health` - System health
+- `GET /health/db` - Database health
+
+## Deployment
+
+See the [deployment documentation](../../docs/deployment/) for Docker and Traefik setup.
+
+## Contributing
+
+1. Follow PEP 8 style guide
+2. Add tests for new endpoints
+3. Update documentation
+4. Run quality gates before committing

apps/api/alembic/versions/0006_tool_instances.py

@@ -0,0 +1,55 @@
+"""add tool_instances table
+
+Revision ID: 0006_tool_instances
+Revises: 0005_ssh_keys_timestamps
+Create Date: 2026-05-19 10:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision: str = "0006_tool_instances"
+down_revision: Union[str, None] = "0005_ssh_keys_timestamps"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "tool_instances",
+        sa.Column("id", postgresql.UUID(as_uuid=True), server_default=sa.text("gen_random_uuid()"), nullable=False),
+        sa.Column("name", sa.String(255), nullable=False),
+        sa.Column("display_name", sa.String(255), nullable=False),
+        sa.Column("tool_type_id", postgresql.UUID(as_uuid=True), nullable=False),
+        sa.Column("repository_id", postgresql.UUID(as_uuid=True), nullable=False),
+        sa.Column("project_id", postgresql.UUID(as_uuid=True), nullable=False),
+        sa.Column("owner_id", postgresql.UUID(as_uuid=True), nullable=False),
+        sa.Column("status", sa.String(50), nullable=False, server_default="pending"),
+        sa.Column("container_id", sa.String(255), nullable=True),
+        sa.Column("compose_path", sa.String(1024), nullable=True),
+        sa.Column("url", sa.String(1024), nullable=True),
+        sa.Column("port", sa.Integer(), nullable=True),
+        sa.Column("last_started_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("last_stopped_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.ForeignKeyConstraint(["tool_type_id"], ["tool_types.id"]),
+        sa.ForeignKeyConstraint(["repository_id"], ["git_repositories.id"]),
+        sa.ForeignKeyConstraint(["project_id"], ["projects.id"]),
+        sa.ForeignKeyConstraint(["owner_id"], ["users.id"]),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index("idx_tool_instances_owner", "tool_instances", ["owner_id"])
+    op.create_index("idx_tool_instances_repo", "tool_instances", ["repository_id"])
+    op.create_index("idx_tool_instances_status", "tool_instances", ["status"])
+
+
+def downgrade() -> None:
+    op.drop_index("idx_tool_instances_status", table_name="tool_instances")
+    op.drop_index("idx_tool_instances_repo", table_name="tool_instances")
+    op.drop_index("idx_tool_instances_owner", table_name="tool_instances")
+    op.drop_table("tool_instances")

apps/api/alembic/versions/0007_instance_container_name.py

@@ -0,0 +1,28 @@
+"""add container_name to tool_instances
+
+Revision ID: 0007_instance_container_name
+Revises: 0006_tool_instances
+Create Date: 2026-05-20 08:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision: str = "0007_instance_container_name"
+down_revision: Union[str, None] = "0006_tool_instances"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "tool_instances",
+        sa.Column("container_name", sa.String(255), nullable=True)
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("tool_instances", "container_name")

apps/api/alembic/versions/0008_tool_type_category.py

@@ -0,0 +1,33 @@
+"""add category and interfaces to tool_types
+
+Revision ID: 0008_tool_type_category
+Revises: 0007_instance_container_name
+Create Date: 2026-05-20 09:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision: str = "0008_tool_type_category"
+down_revision: Union[str, None] = "0007_instance_container_name"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "tool_types",
+        sa.Column("category", sa.String(50), nullable=False, server_default="other")
+    )
+    op.add_column(
+        "tool_types",
+        sa.Column("interfaces", sa.JSON(), nullable=False, server_default='["web"]')
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("tool_types", "interfaces")
+    op.drop_column("tool_types", "category")

apps/api/alembic/versions/0009_tool_configs.py

@@ -0,0 +1,46 @@
+"""add tool_configs table
+
+Revision ID: 0009_tool_configs
+Revises: 0008_tool_type_category
+Create Date: 2026-05-20 09:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision: str = "0009_tool_configs"
+down_revision: Union[str, None] = "0008_tool_type_category"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "tool_configs",
+        sa.Column("id", postgresql.UUID(as_uuid=True), server_default=sa.text("gen_random_uuid()"), nullable=False),
+        sa.Column("user_id", postgresql.UUID(as_uuid=True), nullable=False),
+        sa.Column("tool_type_id", postgresql.UUID(as_uuid=True), nullable=False),
+        sa.Column("project_id", postgresql.UUID(as_uuid=True), nullable=True),
+        sa.Column("key", sa.String(255), nullable=False),
+        sa.Column("value", sa.Text(), nullable=False),
+        sa.Column("config_type", sa.String(20), nullable=False, server_default="env"),
+        sa.Column("file_path", sa.String(1024), 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"]),
+        sa.ForeignKeyConstraint(["tool_type_id"], ["tool_types.id"]),
+        sa.ForeignKeyConstraint(["project_id"], ["projects.id"]),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index("idx_tool_configs_user_tool", "tool_configs", ["user_id", "tool_type_id"])
+    op.create_index("idx_tool_configs_project", "tool_configs", ["project_id"])
+
+
+def downgrade() -> None:
+    op.drop_index("idx_tool_configs_project", table_name="tool_configs")
+    op.drop_index("idx_tool_configs_user_tool", table_name="tool_configs")
+    op.drop_table("tool_configs")

apps/api/alembic/versions/0010_tool_type_default_port.py

@@ -0,0 +1,28 @@
+"""add default_port to tool_types
+
+Revision ID: 0010_tool_type_default_port
+Revises: 0009_tool_configs
+Create Date: 2026-05-20 10:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision: str = "0010_tool_type_default_port"
+down_revision: Union[str, None] = "0009_tool_configs"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "tool_types",
+        sa.Column("default_port", sa.Integer(), nullable=True)
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("tool_types", "default_port")

apps/api/alembic/versions/0011_tool_instance_tunnel_fields.py

@@ -0,0 +1,33 @@
+"""add tunnel fields to tool_instances
+
+Revision ID: 0011_tool_instance_tunnel_fields
+Revises: 0010_tool_type_default_port
+Create Date: 2026-05-20 12:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision: str = "0011_tool_instance_tunnel_fields"
+down_revision: Union[str, None] = "0010_tool_type_default_port"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "tool_instances",
+        sa.Column("public_url", sa.String(1024), nullable=True)
+    )
+    op.add_column(
+        "tool_instances",
+        sa.Column("tunnel_id", sa.String(255), nullable=True)
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("tool_instances", "tunnel_id")
+    op.drop_column("tool_instances", "public_url")

apps/api/alembic/versions/0012_default_port_req.py

@@ -0,0 +1,48 @@
+"""make default_port non-nullable and set values
+
+Revision ID: 0012_default_port_req
+Revises: 0011_tool_instance_tunnel_fields
+Create Date: 2026-05-20 15:00:00.000000
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision: str = "0012_default_port_req"
+down_revision: Union[str, None] = "0011_tool_instance_tunnel_fields"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # Set default_port for existing built-in tool types
+    op.execute("""
+        UPDATE tool_types 
+        SET default_port = CASE 
+            WHEN name = 'code-server' THEN 8443
+            WHEN name = 'jupyter-notebook' THEN 8888
+            WHEN name = 'opencode' THEN 3000
+            ELSE 8080
+        END
+        WHERE default_port IS NULL
+    """)
+    
+    # Make default_port non-nullable
+    op.alter_column(
+        "tool_types",
+        "default_port",
+        existing_type=sa.Integer(),
+        nullable=False,
+    )
+
+
+def downgrade() -> None:
+    op.alter_column(
+        "tool_types",
+        "default_port",
+        existing_type=sa.Integer(),
+        nullable=True,
+    )

apps/api/alembic/versions/398082499c30_add_tool_config_fields.py

@@ -0,0 +1,40 @@
+"""add_tool_config_fields
+
+Revision ID: 398082499c30
+Revises: af8512103d67
+Create Date: 2026-05-22 18:38:20.166184
+"""
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision = '398082499c30'
+down_revision = 'af8512103d67'
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # Add new columns to tool_configs
+    op.add_column('tool_configs', sa.Column('port_override', sa.Integer(), nullable=True))
+    op.add_column('tool_configs', sa.Column('start_command', sa.Text(), nullable=True))
+    op.add_column('tool_configs', sa.Column('working_directory', sa.Text(), nullable=True))
+    op.add_column('tool_configs', sa.Column('environment_variables', postgresql.JSONB(astext_type=sa.Text()), nullable=True, server_default='{}'))
+    op.add_column('tool_configs', sa.Column('volumes', postgresql.JSONB(astext_type=sa.Text()), nullable=True, server_default='[]'))
+    
+    # Add CHECK constraint for port range
+    op.create_check_constraint('chk_port_range', 'tool_configs', sa.text('port_override IS NULL OR (port_override >= 1 AND port_override <= 65535)'))
+
+
+def downgrade() -> None:
+    # Drop CHECK constraint
+    op.drop_constraint('chk_port_range', 'tool_configs', type_='check')
+    
+    # Drop columns
+    op.drop_column('tool_configs', 'port_override')
+    op.drop_column('tool_configs', 'start_command')
+    op.drop_column('tool_configs', 'working_directory')
+    op.drop_column('tool_configs', 'environment_variables')
+    op.drop_column('tool_configs', 'volumes')

apps/api/alembic/versions/8ed7dd80973d_create_config_folders_table.py

@@ -0,0 +1,44 @@
+"""create_config_folders_table
+
+Revision ID: 8ed7dd80973d
+Revises: 398082499c30
+Create Date: 2026-05-22 18:38:22.133696
+"""
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision = '8ed7dd80973d'
+down_revision = '398082499c30'
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        'config_folders',
+        sa.Column('id', postgresql.UUID(as_uuid=True), primary_key=True, server_default=sa.text('gen_random_uuid()')),
+        sa.Column('user_id', postgresql.UUID(as_uuid=True), sa.ForeignKey('users.id', ondelete='CASCADE'), nullable=False),
+        sa.Column('name', sa.String(255), nullable=False),
+        sa.Column('description', sa.Text(), nullable=True),
+        sa.Column('mount_path', sa.String(1024), nullable=False),
+        sa.Column('files', postgresql.JSONB(astext_type=sa.Text()), nullable=False, server_default='{}'),
+        sa.Column('project_overrides', postgresql.JSONB(astext_type=sa.Text()), nullable=True, server_default='{}'),
+        sa.Column('is_active', sa.Boolean(), nullable=False, server_default='true'),
+        sa.Column('created_at', sa.DateTime(timezone=True), nullable=False, server_default=sa.text('NOW()')),
+        sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False, server_default=sa.text('NOW()')),
+        sa.UniqueConstraint('user_id', 'name', name='uq_config_folders_user_name')
+    )
+    
+    # Add index on user_id for filtering
+    op.create_index('idx_config_folders_user', 'config_folders', ['user_id'])
+
+
+def downgrade() -> None:
+    # Drop index
+    op.drop_index('idx_config_folders_user', table_name='config_folders')
+    
+    # Drop table
+    op.drop_table('config_folders')

apps/api/alembic/versions/af8512103d67_add_tool_type_fields.py

@@ -0,0 +1,38 @@
+"""add_tool_type_fields
+
+Revision ID: af8512103d67
+Revises: 0012_default_port_req
+Create Date: 2026-05-22 18:37:56.607240
+"""
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision = 'af8512103d67'
+down_revision = '0012_default_port_req'
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # Add new columns to tool_types
+    op.add_column('tool_types', sa.Column('definition_type', sa.String(20), nullable=False, server_default='compose'))
+    op.add_column('tool_types', sa.Column('dockerfile_template', sa.Text(), nullable=True))
+    op.add_column('tool_types', sa.Column('build_context', postgresql.JSONB(astext_type=sa.Text()), nullable=True, server_default='{}'))
+    op.add_column('tool_types', sa.Column('readiness_probe', postgresql.JSONB(astext_type=sa.Text()), nullable=True))
+    
+    # Add CHECK constraint for definition_type
+    op.create_check_constraint('chk_definition_type', 'tool_types', sa.text("definition_type IN ('compose', 'dockerfile')"))
+
+
+def downgrade() -> None:
+    # Drop CHECK constraint
+    op.drop_constraint('chk_definition_type', 'tool_types', type_='check')
+    
+    # Drop columns
+    op.drop_column('tool_types', 'definition_type')
+    op.drop_column('tool_types', 'dockerfile_template')
+    op.drop_column('tool_types', 'build_context')
+    op.drop_column('tool_types', 'readiness_probe')

apps/api/src/api/auth.py

@@ -25,8 +25,21 @@ async def get_db_session() -> AsyncGenerator[AsyncSession, None]:
         yield session
 
 
-@router.get("/login")
+@router.get(
+    "/login",
+    summary="Initiate OAuth login",
+    description="Redirects to the configured OAuth provider (Authentik) to start the authentication flow.",
+    response_class=RedirectResponse,
+)
 async def login(next: str = "/") -> RedirectResponse:
+    """Initiate OAuth2 login flow.
+
+    Args:
+        next: URL to redirect to after successful authentication.
+
+    Returns:
+        RedirectResponse to the OAuth provider's authorization endpoint.
+    """
     settings = Settings()
     redirect_uri = f"{settings.api_base_url}/auth/callback"
     state = token_urlsafe(24)
@@ -46,7 +59,6 @@ async def login(next: str = "/") -> RedirectResponse:
 async def callback(
     code: str,
     state: str,
-    response: Response,
     auth_state: str | None = Cookie(default=None),
     auth_next: str | None = Cookie(default="/"),
     session: AsyncSession = Depends(get_db_session),
@@ -116,7 +128,13 @@ async def callback(
     cookie_secure = bool(cookie_options["secure"])
     cookie_domain = str(cookie_options["domain"]) if cookie_options.get("domain") else None
     
-    response.set_cookie(
+    logger.info("Auth callback complete for user id=%s, redirecting to %s", user.id, auth_next)
+    
+    # Redirect to frontend with the original next path
+    redirect_url = f"{settings.web_base_url}{auth_next}"
+    redirect_response = RedirectResponse(url=redirect_url)
+    
+    redirect_response.set_cookie(
         "session", 
         session_cookie, 
         httponly=True, 
@@ -124,14 +142,10 @@ async def callback(
         secure=cookie_secure,
         domain=cookie_domain,
     )
-    response.delete_cookie("auth_state", samesite="lax", domain=cookie_domain)
-    response.delete_cookie("auth_next", samesite="lax", domain=cookie_domain)
+    redirect_response.delete_cookie("auth_state", samesite="lax", domain=cookie_domain)
+    redirect_response.delete_cookie("auth_next", samesite="lax", domain=cookie_domain)
     
-    logger.info("Auth callback complete for user id=%s, redirecting to %s", user.id, auth_next)
-    
-    # Redirect to frontend with the original next path
-    redirect_url = f"{settings.web_base_url}{auth_next}"
-    return RedirectResponse(url=redirect_url)
+    return redirect_response
 
 
 @router.post("/logout")
@@ -151,20 +165,30 @@ async def me(
     session_cookie: str | None = Cookie(default=None, alias="session"),
     session: AsyncSession = Depends(get_db_session),
 ) -> dict[str, Any]:
+    logger.info("Auth /me called, cookie present: %s", bool(session_cookie))
+    
     if not session_cookie:
+        logger.warning("Auth /me: missing session cookie")
         raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="missing session")
 
     settings = Settings()
+    logger.info("Auth /me: cookie_domain=%s, cookie_secure=%s, cookie_samesite=%s", 
+                settings.cookie_domain, settings.cookie_secure, settings.cookie_samesite)
+    
     try:
         payload = decode_session_cookie(settings=settings, cookie_value=session_cookie)
         user_id = payload["user_id"]
+        logger.info("Auth /me: decoded session for user_id=%s", user_id)
     except ValueError as exc:
+        logger.warning("Auth /me: invalid session: %s", exc)
         raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail=str(exc))
 
     user = await session.get(User, user_id)
     if user is None:
+        logger.warning("Auth /me: user not found for id=%s", user_id)
         raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="user not found")
 
+    logger.info("Auth /me: success for user=%s", user.email)
     return {
         "user": {
             "id": str(user.id),

apps/api/src/api/config_folders.py

@@ -0,0 +1,372 @@
+"""Config folder API endpoints."""
+
+import logging
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from pydantic import BaseModel, Field, field_validator
+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.config_folder import ConfigFolder
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/config-folders", tags=["config-folders"])
+
+MAX_FOLDER_SIZE_MB = 10
+MAX_FOLDER_SIZE_BYTES = MAX_FOLDER_SIZE_MB * 1024 * 1024
+
+
+class ConfigFolderCreate(BaseModel):
+    name: str = Field(description="Folder name (unique per user)")
+    description: str | None = Field(default=None, description="Optional description")
+    mount_path: str = Field(description="Default mount path in container")
+    files: dict = Field(default_factory=dict, description="Files as {path: content}")
+
+    @field_validator("mount_path")
+    @classmethod
+    def validate_mount_path(cls, v: str) -> str:
+        if not v.startswith("/"):
+            raise ValueError("Mount path must be absolute (start with /)")
+        return v
+
+    @field_validator("files")
+    @classmethod
+    def validate_files(cls, v: dict) -> dict:
+        total_size = 0
+        for path, content in v.items():
+            # Check for path traversal
+            if ".." in path or path.startswith("/"):
+                raise ValueError(f"Invalid file path: {path}")
+            total_size += len(content.encode("utf-8"))
+        
+        if total_size > MAX_FOLDER_SIZE_BYTES:
+            raise ValueError(f"Total folder size exceeds {MAX_FOLDER_SIZE_MB}MB limit")
+        
+        return v
+
+
+class ConfigFolderUpdate(BaseModel):
+    name: str | None = Field(default=None, description="Folder name")
+    description: str | None = Field(default=None, description="Optional description")
+    mount_path: str | None = Field(default=None, description="Default mount path")
+    files: dict | None = Field(default=None, description="Files as {path: content}")
+    is_active: bool | None = Field(default=None, description="Active/inactive toggle")
+
+    @field_validator("mount_path")
+    @classmethod
+    def validate_mount_path(cls, v: str | None) -> str | None:
+        if v is None:
+            return v
+        if not v.startswith("/"):
+            raise ValueError("Mount path must be absolute (start with /)")
+        return v
+
+    @field_validator("files")
+    @classmethod
+    def validate_files(cls, v: dict | None) -> dict | None:
+        if v is None:
+            return v
+        
+        total_size = 0
+        for path, content in v.items():
+            # Check for path traversal
+            if ".." in path or path.startswith("/"):
+                raise ValueError(f"Invalid file path: {path}")
+            total_size += len(content.encode("utf-8"))
+        
+        if total_size > MAX_FOLDER_SIZE_BYTES:
+            raise ValueError(f"Total folder size exceeds {MAX_FOLDER_SIZE_MB}MB limit")
+        
+        return v
+
+
+class ProjectOverrideCreate(BaseModel):
+    mount_path: str | None = Field(default=None, description="Override mount path")
+    files: dict = Field(default_factory=dict, description="Override files")
+
+    @field_validator("mount_path")
+    @classmethod
+    def validate_mount_path(cls, v: str | None) -> str | None:
+        if v is None:
+            return v
+        if not v.startswith("/"):
+            raise ValueError("Mount path must be absolute (start with /)")
+        return v
+
+
+class ConfigFolderResponse(BaseModel):
+    id: str
+    user_id: str
+    name: str
+    description: str | None
+    mount_path: str
+    files: dict
+    project_overrides: dict | None
+    is_active: bool
+    created_at: str
+    updated_at: str
+
+
+@router.get("", summary="List config folders", description="Get all config folders for the current user.")
+async def list_config_folders(
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """List config folders for the current user."""
+    query = select(ConfigFolder).where(ConfigFolder.user_id == user_id)
+    result = await session.execute(query)
+    folders = result.scalars().all()
+    
+    return {
+        "folders": [
+            {
+                "id": str(f.id),
+                "user_id": str(f.user_id),
+                "name": f.name,
+                "description": f.description,
+                "mount_path": f.mount_path,
+                "files": f.files,
+                "project_overrides": f.project_overrides,
+                "is_active": f.is_active,
+                "created_at": f.created_at.isoformat() if f.created_at else None,
+                "updated_at": f.updated_at.isoformat() if f.updated_at else None,
+            }
+            for f in folders
+        ]
+    }
+
+
+@router.post("", summary="Create config folder", description="Create a new config folder.", status_code=status.HTTP_201_CREATED)
+async def create_config_folder(
+    data: ConfigFolderCreate,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Create a config folder."""
+    # Check for duplicate name
+    existing = await session.scalar(
+        select(ConfigFolder).where(
+            ConfigFolder.user_id == user_id,
+            ConfigFolder.name == data.name,
+        )
+    )
+    if existing:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=f"config folder with name '{data.name}' already exists"
+        )
+    
+    folder = ConfigFolder(
+        user_id=user_id,
+        name=data.name,
+        description=data.description,
+        mount_path=data.mount_path,
+        files=data.files,
+    )
+    session.add(folder)
+    await session.commit()
+    await session.refresh(folder)
+    
+    return {
+        "id": str(folder.id),
+        "user_id": str(folder.user_id),
+        "name": folder.name,
+        "description": folder.description,
+        "mount_path": folder.mount_path,
+        "files": folder.files,
+        "project_overrides": folder.project_overrides,
+        "is_active": folder.is_active,
+        "created_at": folder.created_at.isoformat() if folder.created_at else None,
+        "updated_at": folder.updated_at.isoformat() if folder.updated_at else None,
+    }
+
+
+@router.put("/{folder_id}", summary="Update config folder", description="Update an existing config folder.")
+async def update_config_folder(
+    folder_id: uuid.UUID,
+    data: ConfigFolderUpdate,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Update a config folder."""
+    folder = await session.get(ConfigFolder, folder_id)
+    if folder is None or folder.user_id != user_id:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="config folder not found")
+    
+    if data.name is not None:
+        folder.name = data.name
+    if data.description is not None:
+        folder.description = data.description
+    if data.mount_path is not None:
+        folder.mount_path = data.mount_path
+    if data.files is not None:
+        folder.files = data.files
+    if data.is_active is not None:
+        folder.is_active = data.is_active
+    
+    await session.commit()
+    await session.refresh(folder)
+    
+    return {
+        "id": str(folder.id),
+        "user_id": str(folder.user_id),
+        "name": folder.name,
+        "description": folder.description,
+        "mount_path": folder.mount_path,
+        "files": folder.files,
+        "project_overrides": folder.project_overrides,
+        "is_active": folder.is_active,
+        "created_at": folder.created_at.isoformat() if folder.created_at else None,
+        "updated_at": folder.updated_at.isoformat() if folder.updated_at else None,
+    }
+
+
+@router.delete("/{folder_id}", summary="Delete config folder", description="Delete a config folder.", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_config_folder(
+    folder_id: uuid.UUID,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> None:
+    """Delete a config folder."""
+    folder = await session.get(ConfigFolder, folder_id)
+    if folder is None or folder.user_id != user_id:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="config folder not found")
+    
+    await session.delete(folder)
+    await session.commit()
+
+
+class ProjectOverrideWithId(ProjectOverrideCreate):
+    project_id: uuid.UUID = Field(description="Project ID for the override")
+
+
+@router.get("/{folder_id}", summary="Get config folder by ID", description="Get a single config folder by its ID.")
+async def get_config_folder(
+    folder_id: uuid.UUID,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Get a config folder by ID."""
+    folder = await session.get(ConfigFolder, folder_id)
+    if folder is None or folder.user_id != user_id:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="config folder not found")
+    
+    return {
+        "id": str(folder.id),
+        "user_id": str(folder.user_id),
+        "name": folder.name,
+        "description": folder.description,
+        "mount_path": folder.mount_path,
+        "files": folder.files,
+        "project_overrides": folder.project_overrides,
+        "is_active": folder.is_active,
+        "created_at": folder.created_at.isoformat() if folder.created_at else None,
+        "updated_at": folder.updated_at.isoformat() if folder.updated_at else None,
+    }
+
+
+@router.post("/{folder_id}/overrides", summary="Add project override", description="Add a project override to a config folder.")
+async def add_project_override(
+    folder_id: uuid.UUID,
+    data: ProjectOverrideWithId,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Add a project override to a config folder."""
+    folder = await session.get(ConfigFolder, folder_id)
+    if folder is None or folder.user_id != user_id:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="config folder not found")
+    
+    # Initialize project_overrides if None
+    if folder.project_overrides is None:
+        folder.project_overrides = {}
+    
+    # Add/update override
+    override_data = {}
+    if data.mount_path is not None:
+        override_data["mount_path"] = data.mount_path
+    if data.files is not None:
+        override_data["files"] = data.files
+    
+    # Use a copy to trigger SQLAlchemy change detection on JSONB
+    current_overrides = dict(folder.project_overrides or {})
+    current_overrides[str(data.project_id)] = override_data
+    folder.project_overrides = current_overrides
+    
+    await session.commit()
+    await session.refresh(folder)
+    
+    return {
+        "id": str(folder.id),
+        "project_overrides": folder.project_overrides,
+    }
+
+
+@router.put("/{folder_id}/overrides/{project_id}", summary="Update project override", description="Update a project override.")
+async def update_project_override(
+    folder_id: uuid.UUID,
+    project_id: uuid.UUID,
+    data: ProjectOverrideCreate,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Update a project override."""
+    folder = await session.get(ConfigFolder, folder_id)
+    if folder is None or folder.user_id != user_id:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="config folder not found")
+    
+    # Initialize project_overrides if None
+    if folder.project_overrides is None:
+        folder.project_overrides = {}
+    
+    # Update override
+    current_overrides = dict(folder.project_overrides or {})
+    override_data = current_overrides.get(str(project_id), {})
+    if data.mount_path is not None:
+        override_data["mount_path"] = data.mount_path
+    if data.files is not None:
+        override_data["files"] = data.files
+    
+    current_overrides[str(project_id)] = override_data
+    folder.project_overrides = current_overrides
+    
+    # Mark the field as modified to ensure SQLAlchemy detects the change
+    from sqlalchemy.orm.attributes import flag_modified
+    flag_modified(folder, "project_overrides")
+    
+    await session.commit()
+    await session.refresh(folder)
+    
+    return {
+        "id": str(folder.id),
+        "project_overrides": folder.project_overrides,
+    }
+
+
+@router.delete("/{folder_id}/overrides/{project_id}", summary="Remove project override", description="Remove a project override.")
+async def remove_project_override(
+    folder_id: uuid.UUID,
+    project_id: uuid.UUID,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> None:
+    """Remove a project override."""
+    folder = await session.get(ConfigFolder, folder_id)
+    if folder is None or folder.user_id != user_id:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="config folder not found")
+    
+    # Remove override if exists
+    current_overrides = dict(folder.project_overrides or {})
+    if str(project_id) in current_overrides:
+        del current_overrides[str(project_id)]
+        folder.project_overrides = current_overrides
+        await session.commit()
+        await session.refresh(folder)
+    
+    return {
+        "id": str(folder.id),
+        "project_overrides": folder.project_overrides or {},
+    }

apps/api/src/api/dashboard.py

@@ -12,11 +12,24 @@ from src.models.ssh_key import SSHKey
 router = APIRouter(prefix="/dashboard", tags=["dashboard"])
 
 
-@router.get("/summary")
+@router.get(
+    "/summary",
+    summary="Get dashboard summary",
+    description="Get a summary of the user's projects, repositories, SSH keys, and recent activity.",
+)
 async def get_dashboard_summary(
     user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> dict:
+    """Get a summary of the user's dashboard data.
+
+    Args:
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        Dictionary with counts of projects, repositories, SSH keys, and recent activity.
+    """
     # Count user's projects
     projects_result = await session.execute(
         select(func.count()).select_from(Project).where(Project.owner_id == user_id)

apps/api/src/api/git_repositories.py

@@ -1,3 +1,4 @@
+import logging
 import os
 import shutil
 import subprocess
@@ -20,13 +21,27 @@ from src.utils.git_files import (
     list_branches,
     list_tree,
 )
+from src.utils.git_control import (
+    checkout_branch,
+    commit_changes,
+    create_branch,
+    delete_branch,
+    fetch,
+    get_status,
+    merge,
+    pull,
+    push,
+)
 from src.utils.git_history import get_commit_detail, get_commit_history
 from src.utils.git_url_parser import parse_git_url
 
 router = APIRouter(prefix="/projects", tags=["git-repositories"])
 
+logger = logging.getLogger(__name__)
+
 
 async def _get_user(session: AsyncSession, user_id: uuid.UUID) -> User:
+    """Fetch a user by ID or raise 401 if not found."""
     user = await session.get(User, user_id)
     if user is None:
         raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="user not found")
@@ -38,6 +53,19 @@ async def _get_owned_project(
     user_id: uuid.UUID,
     session: AsyncSession,
 ) -> Project:
+    """Fetch a project and verify ownership.
+
+    Args:
+        project_id: UUID of the project.
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        The project if found and owned by the user.
+
+    Raises:
+        HTTPException: If project not found or user is not the owner.
+    """
     project = await session.get(Project, project_id)
     if project is None:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="project not found")
@@ -47,10 +75,102 @@ async def _get_owned_project(
 
 
 def _get_repo_path(user_id: uuid.UUID, project_id: uuid.UUID, name: str) -> str:
+    """Generate the filesystem path for a repository.
+
+    Args:
+        user_id: UUID of the repository owner.
+        project_id: UUID of the project.
+        name: Repository name.
+
+    Returns:
+        Absolute path to the repository directory.
+    """
     base = Settings().repo_base_path or "/data/repos"
     return os.path.join(base, str(user_id), str(project_id), f"{name}.git")
 
 
+def _build_provider_clone_url(owner: str, repo: str) -> str:
+    """Build the SSH clone URL for the fixed git provider."""
+    return f"git@git.commumedia.org:{owner}/{repo}.git"
+
+
+def _preflight_remote_repository(remote_url: str) -> None:
+    """Verify a remote repository is reachable before cloning."""
+    try:
+        result = subprocess.run(
+            ["git", "ls-remote", remote_url],
+            capture_output=True,
+            text=True,
+            timeout=60,
+        )
+    except subprocess.TimeoutExpired:
+        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")
+
+    if result.returncode != 0:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="repository not found or inaccessible",
+        )
+
+
+def _clone_working_repository(remote_url: str, repo_path: str) -> None:
+    try:
+        result = subprocess.run(
+            ["git", "clone", remote_url, repo_path],
+            capture_output=True,
+            text=True,
+            timeout=300,
+        )
+    except subprocess.TimeoutExpired:
+        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")
+
+    if result.returncode != 0:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"failed to clone repository: {result.stderr}",
+        )
+
+
+def _init_working_repository(repo_path: str) -> None:
+    try:
+        result = subprocess.run(
+            ["git", "init", "-b", "main", repo_path],
+            capture_output=True,
+            text=True,
+        )
+    except FileNotFoundError:
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="git command not found")
+
+    if result.returncode == 0:
+        return
+
+    fallback = subprocess.run(
+        ["git", "init", repo_path],
+        capture_output=True,
+        text=True,
+    )
+    if fallback.returncode != 0:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"failed to initialize repository: {fallback.stderr}",
+        )
+
+    ref_result = subprocess.run(
+        ["git", "-C", repo_path, "symbolic-ref", "HEAD", "refs/heads/main"],
+        capture_output=True,
+        text=True,
+    )
+    if ref_result.returncode != 0:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"failed to set initial branch: {ref_result.stderr}",
+        )
+
+
 class GitRepositoryCreate(BaseModel):
     name: str
     remote_url: str | None = None
@@ -86,12 +206,27 @@ class GitRepositoryResponse(BaseModel):
     updated_at: datetime
 
 
-@router.get("/{project_id}/repositories", response_model=list[GitRepositoryResponse])
+@router.get(
+    "/{project_id}/repositories",
+    response_model=list[GitRepositoryResponse],
+    summary="List repositories",
+    description="List all git repositories in a project.",
+)
 async def list_repositories(
     project_id: uuid.UUID,
     user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> list[GitRepository]:
+    """List all repositories in a project.
+
+    Args:
+        project_id: UUID of the project.
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        List of repositories in the project.
+    """
     _user = await _get_user(session, user_id)
     _project = await _get_owned_project(project_id, user_id, session)
 
@@ -101,13 +236,29 @@ async def list_repositories(
     return list(result.scalars().all())
 
 
-@router.delete("/{project_id}/repositories/{repo_id}", status_code=status.HTTP_204_NO_CONTENT)
+@router.delete(
+    "/{project_id}/repositories/{repo_id}",
+    status_code=status.HTTP_204_NO_CONTENT,
+    summary="Delete a repository",
+    description="Delete a git repository from the project and remove it from disk.",
+)
 async def delete_repository(
     project_id: uuid.UUID,
     repo_id: uuid.UUID,
     user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> Response:
+    """Delete a repository.
+
+    Args:
+        project_id: UUID of the project.
+        repo_id: UUID of the repository to delete.
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        Empty response with 204 status code.
+    """
     _user = await _get_user(session, user_id)
     _project = await _get_owned_project(project_id, user_id, session)
 
@@ -124,20 +275,49 @@ async def delete_repository(
     return Response(status_code=status.HTTP_204_NO_CONTENT)
 
 
-@router.post("/repositories/parse-url", response_model=URLParseResponse)
+@router.post(
+    "/repositories/parse-url",
+    response_model=URLParseResponse,
+    summary="Parse a git URL",
+    description="Parse a git URL and detect if it's a browser URL that needs correction.",
+)
 async def parse_repository_url(data: URLParseRequest) -> URLParseResponse:
-    """Parse a git URL and detect if it's a browser URL that needs correction."""
+    """Parse a git URL and detect if it's a browser URL that needs correction.
+
+    Args:
+        data: Request containing the URL to parse.
+
+    Returns:
+        Parsed URL information including whether it needs parsing and suggested corrections.
+    """
     result = parse_git_url(data.url)
     return URLParseResponse(**result)
 
 
-@router.post("/{project_id}/repositories", response_model=GitRepositoryResponse, status_code=status.HTTP_201_CREATED)
+@router.post(
+    "/{project_id}/repositories",
+    response_model=GitRepositoryResponse,
+    status_code=status.HTTP_201_CREATED,
+    summary="Create a repository",
+    description="Create a new git repository in a project. Can clone from remote or initialize a working repository.",
+)
 async def create_repository(
     project_id: uuid.UUID,
     data: GitRepositoryCreate,
     user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> GitRepository:
+    """Create a new git repository.
+
+    Args:
+        project_id: UUID of the project.
+        data: Repository creation data including name and optional remote URL.
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        The newly created repository.
+    """
     _user = await _get_user(session, user_id)
     _project = await _get_owned_project(project_id, user_id, session)
 
@@ -169,47 +349,25 @@ async def create_repository(
         if parse_result["base_url"]:
             remote_url = parse_result["base_url"]
 
+    if remote_url:
+        _preflight_remote_repository(remote_url)
+
     repo_path = _get_repo_path(user_id, project_id, data.name)
 
     # Ensure parent directory exists
     os.makedirs(os.path.dirname(repo_path), exist_ok=True)
 
     if remote_url:
-        # Clone as mirror
-        try:
-            result = subprocess.run(
-                ["git", "clone", "--mirror", remote_url, repo_path],
-                capture_output=True,
-                text=True,
-                timeout=300,
-            )
-            if result.returncode != 0:
-                raise HTTPException(
-                    status_code=status.HTTP_400_BAD_REQUEST,
-                    detail=f"failed to clone repository: {result.stderr}",
-                )
-        except subprocess.TimeoutExpired:
-            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")
+        _clone_working_repository(remote_url, repo_path)
     else:
-        # Init bare repo
-        try:
-            result = subprocess.run(
-                ["git", "init", "--bare", repo_path],
-                capture_output=True,
-                text=True,
-                check=True,
-            )
-        except FileNotFoundError:
-            raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="git command not found")
+        _init_working_repository(repo_path)
 
     repo = GitRepository(
         name=data.name,
         path=repo_path,
         project_id=project_id,
         owner_id=user_id,
-        is_mirror=bool(remote_url),
+        is_mirror=False,
         remote_url=remote_url,
     )
     session.add(repo)
@@ -218,7 +376,11 @@ async def create_repository(
     return repo
 
 
-@router.get("/{project_id}/repositories/{repo_id}/history")
+@router.get(
+    "/{project_id}/repositories/{repo_id}/history",
+    summary="Get repository history",
+    description="Get commit history for a repository with optional branch filtering.",
+)
 async def get_repository_history(
     project_id: uuid.UUID,
     repo_id: uuid.UUID,
@@ -229,7 +391,21 @@ async def get_repository_history(
     user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> dict:
-    """Get commit history for a repository."""
+    """Get commit history for a repository.
+
+    Args:
+        project_id: UUID of the project.
+        repo_id: UUID of the repository.
+        view: View type for history display (default: graph).
+        branch: Optional branch name to filter commits.
+        limit: Maximum number of commits to return (default: 100).
+        offset: Number of commits to skip (default: 0).
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        Dictionary containing commit history data.
+    """
     _user = await _get_user(session, user_id)
     _project = await _get_owned_project(project_id, user_id, session)
 
@@ -247,7 +423,11 @@ async def get_repository_history(
         raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=str(e))
 
 
-@router.get("/{project_id}/repositories/{repo_id}/commits/{commit_hash}")
+@router.get(
+    "/{project_id}/repositories/{repo_id}/commits/{commit_hash}",
+    summary="Get commit details",
+    description="Get detailed information about a specific commit.",
+)
 async def get_repository_commit(
     project_id: uuid.UUID,
     repo_id: uuid.UUID,
@@ -255,7 +435,18 @@ async def get_repository_commit(
     user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> dict:
-    """Get detailed information about a specific commit."""
+    """Get detailed information about a specific commit.
+
+    Args:
+        project_id: UUID of the project.
+        repo_id: UUID of the repository.
+        commit_hash: Hash of the commit to retrieve.
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        Dictionary containing commit details.
+    """
     _user = await _get_user(session, user_id)
     _project = await _get_owned_project(project_id, user_id, session)
 
@@ -311,7 +502,12 @@ class FileUpdateResponse(BaseModel):
     branch: str
 
 
-@router.get("/{project_id}/repositories/{repo_id}/files", response_model=FileListResponse)
+@router.get(
+    "/{project_id}/repositories/{repo_id}/files",
+    response_model=FileListResponse,
+    summary="List repository files",
+    description="List files and directories in a repository path.",
+)
 async def list_repository_files(
     project_id: uuid.UUID,
     repo_id: uuid.UUID,
@@ -320,7 +516,19 @@ async def list_repository_files(
     user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> FileListResponse:
-    """List files and directories in a repository path."""
+    """List files and directories in a repository path.
+
+    Args:
+        project_id: UUID of the project.
+        repo_id: UUID of the repository.
+        branch: Branch name to browse (default: main).
+        path: Directory path within the repository (default: root).
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        List of files and directories in the specified path.
+    """
     _user = await _get_user(session, user_id)
     _project = await _get_owned_project(project_id, user_id, session)
 
@@ -349,10 +557,23 @@ async def list_repository_files(
             ],
         )
     except RuntimeError as e:
+        logger.error(
+            "Failed to list files for repo %s (path=%s, branch=%s): %s",
+            repo_id,
+            path,
+            branch,
+            str(e),
+            exc_info=True,
+        )
         raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
 
 
-@router.get("/{project_id}/repositories/{repo_id}/files/content", response_model=FileContentResponse)
+@router.get(
+    "/{project_id}/repositories/{repo_id}/files/content",
+    response_model=FileContentResponse,
+    summary="Get file content",
+    description="Get the content of a file in a repository.",
+)
 async def get_repository_file_content(
     project_id: uuid.UUID,
     repo_id: uuid.UUID,
@@ -361,7 +582,19 @@ async def get_repository_file_content(
     user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> FileContentResponse:
-    """Get the content of a file."""
+    """Get the content of a file.
+
+    Args:
+        project_id: UUID of the project.
+        repo_id: UUID of the repository.
+        branch: Branch name where the file is located.
+        path: File path within the repository.
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        File content and metadata.
+    """
     _user = await _get_user(session, user_id)
     _project = await _get_owned_project(project_id, user_id, session)
 
@@ -390,14 +623,29 @@ async def get_repository_file_content(
         raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
 
 
-@router.get("/{project_id}/repositories/{repo_id}/branches", response_model=BranchesResponse)
+@router.get(
+    "/{project_id}/repositories/{repo_id}/branches",
+    response_model=BranchesResponse,
+    summary="List branches",
+    description="List all branches in the repository.",
+)
 async def get_repository_branches(
     project_id: uuid.UUID,
     repo_id: uuid.UUID,
     user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> BranchesResponse:
-    """List all branches in the repository."""
+    """List all branches in the repository.
+
+    Args:
+        project_id: UUID of the project.
+        repo_id: UUID of the repository.
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        List of branches and the default branch name.
+    """
     _user = await _get_user(session, user_id)
     _project = await _get_owned_project(project_id, user_id, session)
 
@@ -422,10 +670,21 @@ async def get_repository_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_400_BAD_REQUEST, detail=str(e))
 
 
-@router.post("/{project_id}/repositories/{repo_id}/files/content", response_model=FileUpdateResponse)
+@router.post(
+    "/{project_id}/repositories/{repo_id}/files/content",
+    response_model=FileUpdateResponse,
+    summary="Update file content",
+    description="Update a file and create a commit.",
+)
 async def update_repository_file(
     project_id: uuid.UUID,
     repo_id: uuid.UUID,
@@ -433,7 +692,18 @@ async def update_repository_file(
     user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> FileUpdateResponse:
-    """Update a file and create a commit."""
+    """Update a file and create a commit.
+
+    Args:
+        project_id: UUID of the project.
+        repo_id: UUID of the repository.
+        data: File update data including path, branch, content, and commit message.
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        Commit information for the file update.
+    """
     _user = await _get_user(session, user_id)
     _project = await _get_owned_project(project_id, user_id, session)
 
@@ -466,3 +736,463 @@ async def update_repository_file(
         )
     except RuntimeError as e:
         raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
+
+
+# Git Control Endpoints
+
+
+class StatusResponse(BaseModel):
+    branch: str
+    modified: list[str]
+    added: list[str]
+    deleted: list[str]
+    untracked: list[str]
+    renamed: list[str]
+    ahead: int
+    behind: int
+
+
+@router.get(
+    "/{project_id}/repositories/{repo_id}/status",
+    response_model=StatusResponse,
+    summary="Get repository status",
+    description="Get the working directory status including modified, added, and deleted files.",
+)
+async def get_repository_status(
+    project_id: uuid.UUID,
+    repo_id: uuid.UUID,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> StatusResponse:
+    """Get the working directory status.
+
+    Args:
+        project_id: UUID of the project.
+        repo_id: UUID of the repository.
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        Repository status including branch, modified files, and ahead/behind counts.
+    """
+    _user = await _get_user(session, user_id)
+    _project = await _get_owned_project(project_id, user_id, session)
+
+    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:
+        status_result = get_status(repo.path)
+        return StatusResponse(
+            branch=status_result.branch,
+            modified=status_result.modified,
+            added=status_result.added,
+            deleted=status_result.deleted,
+            untracked=status_result.untracked,
+            renamed=status_result.renamed,
+            ahead=status_result.ahead,
+            behind=status_result.behind,
+        )
+    except RuntimeError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
+
+
+class BranchCreateRequest(BaseModel):
+    name: str
+    base_branch: str = "HEAD"
+
+
+class CheckoutRequest(BaseModel):
+    branch: str
+
+
+@router.post(
+    "/{project_id}/repositories/{repo_id}/branches",
+    summary="Create a branch",
+    description="Create a new branch in the repository.",
+)
+async def create_repository_branch(
+    project_id: uuid.UUID,
+    repo_id: uuid.UUID,
+    data: BranchCreateRequest,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Create a new branch.
+
+    Args:
+        project_id: UUID of the project.
+        repo_id: UUID of the repository.
+        data: Branch creation data including name and optional base branch.
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        Dictionary with success message and branch name.
+    """
+    _user = await _get_user(session, user_id)
+    _project = await _get_owned_project(project_id, user_id, session)
+
+    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:
+        create_branch(repo.path, data.name, data.base_branch)
+        return {"message": f"Branch '{data.name}' created", "branch": data.name}
+    except RuntimeError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
+
+
+@router.delete(
+    "/{project_id}/repositories/{repo_id}/branches/{branch_name}",
+    summary="Delete a branch",
+    description="Delete a branch from the repository.",
+)
+async def delete_repository_branch(
+    project_id: uuid.UUID,
+    repo_id: uuid.UUID,
+    branch_name: str,
+    force: bool = False,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Delete a branch.
+
+    Args:
+        project_id: UUID of the project.
+        repo_id: UUID of the repository.
+        branch_name: Name of the branch to delete.
+        force: Whether to force delete the branch.
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        Dictionary with success message.
+    """
+    _user = await _get_user(session, user_id)
+    _project = await _get_owned_project(project_id, user_id, session)
+
+    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:
+        delete_branch(repo.path, branch_name, force)
+        return {"message": f"Branch '{branch_name}' deleted"}
+    except RuntimeError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
+
+
+@router.post(
+    "/{project_id}/repositories/{repo_id}/checkout",
+    summary="Checkout a branch",
+    description="Checkout a branch in the repository.",
+)
+async def checkout_repository_branch(
+    project_id: uuid.UUID,
+    repo_id: uuid.UUID,
+    data: CheckoutRequest,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Checkout a branch.
+
+    Args:
+        project_id: UUID of the project.
+        repo_id: UUID of the repository.
+        data: Checkout request containing the branch name.
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        Dictionary with success message and checked out branch name.
+    """
+    _user = await _get_user(session, user_id)
+    _project = await _get_owned_project(project_id, user_id, session)
+
+    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:
+        checkout_branch(repo.path, data.branch)
+        return {"message": f"Checked out branch '{data.branch}'", "branch": data.branch}
+    except RuntimeError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
+
+
+class CommitRequest(BaseModel):
+    message: str
+    files: list[str] | None = None
+
+
+class CommitResponse(BaseModel):
+    commit_hash: str
+    message: str
+
+
+@router.post(
+    "/{project_id}/repositories/{repo_id}/commit",
+    response_model=CommitResponse,
+    summary="Commit changes",
+    description="Commit changes to the repository.",
+)
+async def commit_repository_changes(
+    project_id: uuid.UUID,
+    repo_id: uuid.UUID,
+    data: CommitRequest,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> CommitResponse:
+    """Commit changes to the repository.
+
+    Args:
+        project_id: UUID of the project.
+        repo_id: UUID of the repository.
+        data: Commit request containing message and optional files to commit.
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        Commit information including hash and message.
+    """
+    _user = await _get_user(session, user_id)
+    _project = await _get_owned_project(project_id, user_id, session)
+
+    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")
+
+    # Get user info for commit
+    user = await _get_user(session, user_id)
+    author_name = user.name or "Unknown"
+    author_email = user.email or "unknown@example.com"
+
+    try:
+        commit_hash = commit_changes(
+            repo_path=repo.path,
+            message=data.message,
+            author_name=author_name,
+            author_email=author_email,
+            files=data.files,
+        )
+        return CommitResponse(
+            commit_hash=commit_hash,
+            message=data.message,
+        )
+    except RuntimeError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
+
+
+class FetchResponse(BaseModel):
+    message: str
+
+
+@router.post(
+    "/{project_id}/repositories/{repo_id}/fetch",
+    response_model=FetchResponse,
+    summary="Fetch from remote",
+    description="Fetch updates from the remote repository.",
+)
+async def fetch_repository(
+    project_id: uuid.UUID,
+    repo_id: uuid.UUID,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> FetchResponse:
+    """Fetch from remote.
+
+    Args:
+        project_id: UUID of the project.
+        repo_id: UUID of the repository.
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        Success message.
+    """
+    _user = await _get_user(session, user_id)
+    _project = await _get_owned_project(project_id, user_id, session)
+
+    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:
+        fetch(repo.path)
+        return FetchResponse(message="Fetched from remote")
+    except RuntimeError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
+
+
+class PullResponse(BaseModel):
+    message: str
+
+
+@router.post(
+    "/{project_id}/repositories/{repo_id}/pull",
+    response_model=PullResponse,
+    summary="Pull from remote",
+    description="Pull updates from the remote repository.",
+)
+async def pull_repository(
+    project_id: uuid.UUID,
+    repo_id: uuid.UUID,
+    branch: str | None = None,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> PullResponse:
+    """Pull updates from remote.
+
+    Args:
+        project_id: UUID of the project.
+        repo_id: UUID of the repository.
+        branch: Optional branch name to pull.
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        Success message.
+    """
+    _user = await _get_user(session, user_id)
+    _project = await _get_owned_project(project_id, user_id, session)
+
+    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:
+        pull(repo.path, branch)
+        return PullResponse(message="Pulled from remote")
+    except RuntimeError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
+
+
+class PushResponse(BaseModel):
+    message: str
+
+
+@router.post(
+    "/{project_id}/repositories/{repo_id}/push",
+    response_model=PushResponse,
+    summary="Push to remote",
+    description="Push changes to the remote repository.",
+)
+async def push_repository(
+    project_id: uuid.UUID,
+    repo_id: uuid.UUID,
+    branch: str | None = None,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> PushResponse:
+    """Push changes to remote.
+
+    Args:
+        project_id: UUID of the project.
+        repo_id: UUID of the repository.
+        branch: Optional branch name to push.
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        Success message.
+    """
+    _user = await _get_user(session, user_id)
+    _project = await _get_owned_project(project_id, user_id, session)
+
+    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:
+        push(repo.path, branch)
+        return PushResponse(message="Pushed to remote")
+    except RuntimeError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
+
+
+class MergeRequest(BaseModel):
+    source_branch: str
+    target_branch: str | None = None
+    message: str | None = None
+
+
+class MergeResponse(BaseModel):
+    commit_hash: str
+    message: str
+
+
+@router.post(
+    "/{project_id}/repositories/{repo_id}/merge",
+    response_model=MergeResponse,
+    summary="Merge branches",
+    description="Merge one branch into another.",
+)
+async def merge_repository_branches(
+    project_id: uuid.UUID,
+    repo_id: uuid.UUID,
+    data: MergeRequest,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> MergeResponse:
+    """Merge branches.
+
+    Args:
+        project_id: UUID of the project.
+        repo_id: UUID of the repository.
+        data: Merge request containing source branch, optional target branch, and message.
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        Merge result with commit hash and message.
+    """
+    _user = await _get_user(session, user_id)
+    _project = await _get_owned_project(project_id, user_id, session)
+
+    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:
+        commit_hash = merge(
+            repo_path=repo.path,
+            source_branch=data.source_branch,
+            target_branch=data.target_branch,
+            message=data.message,
+        )
+        return MergeResponse(
+            commit_hash=commit_hash,
+            message=data.message or f"Merge {data.source_branch}",
+        )
+    except RuntimeError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))

apps/api/src/api/health.py

@@ -0,0 +1,149 @@
+"""Health check endpoints and models."""
+
+import time
+from datetime import datetime, timezone
+from typing import Any
+
+from fastapi import APIRouter, status
+from pydantic import BaseModel, Field
+from sqlalchemy import text
+
+from src.config import Settings
+from src.database import SessionLocal
+
+router = APIRouter()
+
+# Track start time for uptime
+_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,
+    summary="Health check",
+    description="Returns overall system health status including database and disk checks.",
+    tags=["Health"],
+)
+async def health_check() -> dict[str, Any]:
+    """Check overall system health.
+
+    Returns:
+        HealthResponse with status, timestamp, version, checks, and uptime.
+    """
+    checks = HealthChecks()
+    overall_status = "healthy"
+
+    # Database check
+    try:
+        import time as time_module
+
+        start = time_module.perf_counter()
+        async with SessionLocal() as session:
+            await session.execute(text("SELECT 1"))
+        db_time = (time_module.perf_counter() - start) * 1000
+        checks.database = DatabaseHealth(
+            status="healthy",
+            response_time_ms=round(db_time, 2),
+        )
+    except Exception:
+        checks.database = DatabaseHealth(
+            status="unhealthy",
+            response_time_ms=0.0,
+        )
+        overall_status = "degraded"
+
+    # Disk check
+    try:
+        import shutil
+
+        disk = shutil.disk_usage("/")
+        free_gb = disk.free / (1024**3)
+        total_gb = disk.total / (1024**3)
+        disk_status = "healthy" if free_gb > 1.0 else "degraded"
+        if disk_status == "degraded":
+            overall_status = "degraded"
+        checks.disk = DiskHealth(
+            status=disk_status,
+            free_gb=round(free_gb, 2),
+            total_gb=round(total_gb, 2),
+        )
+    except Exception:
+        checks.disk = None
+
+    return HealthResponse(
+        status=overall_status,
+        timestamp=datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+        version="0.1.0",
+        checks=checks,
+        uptime_seconds=round(time.time() - _start_time, 2),
+    ).model_dump()
+
+
+@router.get(
+    "/health/db",
+    response_model=DatabaseHealthResponse,
+    summary="Database health check",
+    description="Returns database-specific health status with response time.",
+    tags=["Health"],
+)
+async def health_check_db() -> dict[str, Any]:
+    """Check database health.
+
+    Returns:
+        DatabaseHealthResponse with status and response time.
+    """
+    import time as time_module
+
+    try:
+        start = time_module.perf_counter()
+        async with SessionLocal() as session:
+            await session.execute(text("SELECT 1"))
+        db_time = (time_module.perf_counter() - start) * 1000
+        return DatabaseHealthResponse(
+            status="healthy",
+            response_time_ms=round(db_time, 2),
+        ).model_dump()
+    except Exception:
+        return DatabaseHealthResponse(
+            status="unhealthy",
+            response_time_ms=0.0,
+        ).model_dump()

apps/api/src/api/instance_proxy.py

@@ -0,0 +1,125 @@
+"""Instance proxy router for forwarding HTTP requests to running containers."""
+
+import logging
+import uuid
+from typing import Any
+
+import httpx
+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
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/instances", tags=["instance-proxy"])
+
+
+async def _proxy_request(
+    request: Request,
+    instance_id: uuid.UUID,
+    path: str,
+    user_id: uuid.UUID,
+    session: AsyncSession,
+) -> Response:
+    """Proxy an HTTP request to a running instance."""
+    instance = await session.get(ToolInstance, instance_id)
+    if instance is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="instance not found"
+        )
+
+    # Verify ownership
+    if instance.owner_id != user_id:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="not authorized to access this instance",
+        )
+
+    if instance.status != "running" or not instance.container_name:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="instance is not running",
+        )
+
+    # Get the tool type to find the internal port
+    tool_type = await session.get(ToolType, instance.tool_type_id)
+    internal_port = tool_type.default_port if tool_type and tool_type.default_port else instance.port
+
+    # Build target URL using internal port
+    target_url = f"http://{instance.container_name}:{internal_port}"
+    if path:
+        target_url += f"/{path}"
+
+    # Get query string
+    query_string = str(request.query_params)
+    if query_string:
+        target_url += f"?{query_string}"
+
+    # Forward headers (excluding host and cookies)
+    headers: dict[str, str] = {}
+    for key, value in request.headers.items():
+        if key.lower() not in ("host", "cookie", "content-length"):
+            headers[key] = value
+
+    # Forward the request
+    try:
+        async with httpx.AsyncClient() as client:
+            body = await request.body()
+            response = await client.request(
+                method=request.method,
+                url=target_url,
+                headers=headers,
+                content=body,
+                follow_redirects=False,
+                timeout=30.0,
+            )
+    except Exception as exc:
+        logger.error("Proxy error to %s: %s", target_url, exc)
+        raise HTTPException(
+            status_code=status.HTTP_502_BAD_GATEWAY,
+            detail=f"failed to reach instance: {exc}",
+        )
+
+    # Build response
+    response_headers = dict(response.headers)
+    # Remove hop-by-hop headers
+    for header in ("content-encoding", "transfer-encoding", "connection"):
+        response_headers.pop(header, None)
+
+    return Response(
+        content=response.content,
+        status_code=response.status_code,
+        headers=response_headers,
+    )
+
+
+@router.get("/{instance_id}/proxy/{path:path}")
+@router.post("/{instance_id}/proxy/{path:path}", include_in_schema=False)
+@router.put("/{instance_id}/proxy/{path:path}", include_in_schema=False)
+@router.delete("/{instance_id}/proxy/{path:path}", include_in_schema=False)
+@router.patch("/{instance_id}/proxy/{path:path}", include_in_schema=False)
+@router.head("/{instance_id}/proxy/{path:path}", include_in_schema=False)
+@router.options("/{instance_id}/proxy/{path:path}", include_in_schema=False)
+async def proxy_to_instance(
+    request: Request,
+    instance_id: uuid.UUID,
+    path: str = "",
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> Response:
+    """Proxy requests to a running tool instance.
+
+    Args:
+        request: The incoming HTTP request.
+        instance_id: UUID of the instance.
+        path: The path to proxy to the instance.
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        Response from the proxied instance.
+    """
+    return await _proxy_request(request, instance_id, path, user_id, session)

apps/api/src/api/projects.py

@@ -17,6 +17,7 @@ router = APIRouter(prefix="/projects", tags=["projects"])
 
 
 async def _get_user(session: AsyncSession, user_id: uuid.UUID) -> User:
+    """Fetch a user by ID or raise 401 if not found."""
     user = await session.get(User, user_id)
     if user is None:
         raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="user not found")
@@ -47,12 +48,28 @@ class SetDefaultSSHKeyRequest(BaseModel):
     ssh_key_id: uuid.UUID
 
 
-@router.post("", response_model=ProjectResponse, status_code=status.HTTP_201_CREATED)
+@router.post(
+    "",
+    response_model=ProjectResponse,
+    status_code=status.HTTP_201_CREATED,
+    summary="Create a new project",
+    description="Create a new project for the authenticated user.",
+)
 async def create_project(
     data: ProjectCreate,
     user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> Project:
+    """Create a new project.
+
+    Args:
+        data: Project creation data including name and optional description.
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        The newly created project.
+    """
     user = await _get_user(session, user_id)
     project = Project(
         name=data.name,
@@ -66,21 +83,73 @@ async def create_project(
     return project
 
 
-@router.get("", response_model=list[ProjectResponse])
+@router.get(
+    "",
+    response_model=list[ProjectResponse],
+    summary="List all projects",
+    description="Retrieve all projects owned by the authenticated user.",
+)
 async def list_projects(
     user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> list[Project]:
+    """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.
+    """
     user = await _get_user(session, user_id)
     result = await session.execute(select(Project).where(Project.owner_id == user.id))
     return list(result.scalars().all())
 
 
+@router.get(
+    "/{project_id}",
+    response_model=ProjectResponse,
+    summary="Get a project",
+    description="Retrieve a specific project by ID.",
+)
+async def get_project(
+    project_id: uuid.UUID,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> Project:
+    """Get a specific project by ID.
+
+    Args:
+        project_id: UUID of the project to retrieve.
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        The requested project.
+    """
+    await _get_user(session, user_id)
+    return await _get_owned_project(project_id, user_id, session)
+
+
 async def _get_owned_project(
     project_id: uuid.UUID,
     user_id: uuid.UUID,
     session: AsyncSession,
 ) -> Project:
+    """Fetch a project and verify ownership.
+
+    Args:
+        project_id: UUID of the project.
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        The project if found and owned by the user.
+
+    Raises:
+        HTTPException: If project not found or user is not the owner.
+    """
     project = await session.get(Project, project_id)
     if project is None:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="project not found")
@@ -89,13 +158,29 @@ async def _get_owned_project(
     return project
 
 
-@router.patch("/{project_id}", response_model=ProjectResponse)
+@router.patch(
+    "/{project_id}",
+    response_model=ProjectResponse,
+    summary="Update a project",
+    description="Update a project's name or description.",
+)
 async def update_project(
     project_id: uuid.UUID,
     data: ProjectUpdate,
     user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> Project:
+    """Update a project.
+
+    Args:
+        project_id: UUID of the project to update.
+        data: Project update data with optional name and description.
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        The updated project.
+    """
     await _get_user(session, user_id)
     project = await _get_owned_project(project_id, user_id, session)
 
@@ -109,12 +194,27 @@ async def update_project(
     return project
 
 
-@router.delete("/{project_id}", status_code=status.HTTP_204_NO_CONTENT)
+@router.delete(
+    "/{project_id}",
+    status_code=status.HTTP_204_NO_CONTENT,
+    summary="Delete a project",
+    description="Delete a project and all its associated repositories.",
+)
 async def delete_project(
     project_id: uuid.UUID,
     user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> Response:
+    """Delete a project and all its repositories.
+
+    Args:
+        project_id: UUID of the project to delete.
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        Empty response with 204 status code.
+    """
     await _get_user(session, user_id)
     project = await _get_owned_project(project_id, user_id, session)
 
@@ -131,13 +231,29 @@ async def delete_project(
     return Response(status_code=status.HTTP_204_NO_CONTENT)
 
 
-@router.patch("/{project_id}/default-ssh-key", response_model=ProjectResponse)
+@router.patch(
+    "/{project_id}/default-ssh-key",
+    response_model=ProjectResponse,
+    summary="Set default SSH key",
+    description="Set the default SSH key for a project.",
+)
 async def set_default_ssh_key(
     project_id: uuid.UUID,
     data: SetDefaultSSHKeyRequest,
     user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> Project:
+    """Set the default SSH key for a project.
+
+    Args:
+        project_id: UUID of the project.
+        data: Request containing the SSH key ID to set as default.
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        The updated project.
+    """
     user = await _get_user(session, user_id)
     project = await _get_owned_project(project_id, user_id, session)
 

apps/api/src/api/ssh_keys.py

@@ -18,6 +18,7 @@ router = APIRouter(prefix="/ssh-keys", tags=["ssh-keys"])
 
 
 async def _get_user(session: AsyncSession, user_id: uuid.UUID) -> User:
+    """Fetch a user by ID or raise 401 if not found."""
     user = await session.get(User, user_id)
     if user is None:
         raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="user not found")
@@ -38,6 +39,11 @@ def _get_fernet() -> Fernet:
 
 
 def generate_ssh_key_pair() -> tuple[str, str]:
+    """Generate a new Ed25519 SSH key pair.
+
+    Returns:
+        Tuple of (private_key, public_key) as strings.
+    """
     private_key = Ed25519PrivateKey.generate()
     public_key = private_key.public_key()
 
@@ -68,12 +74,28 @@ class SSHKeyResponse(BaseModel):
     created_at: datetime
 
 
-@router.post("", response_model=SSHKeyResponse, status_code=status.HTTP_201_CREATED)
+@router.post(
+    "",
+    response_model=SSHKeyResponse,
+    status_code=status.HTTP_201_CREATED,
+    summary="Create SSH key",
+    description="Generate a new Ed25519 SSH key pair for the authenticated user.",
+)
 async def create_ssh_key(
     data: SSHKeyCreate,
     user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> SSHKey:
+    """Create a new SSH key pair.
+
+    Args:
+        data: SSH key creation data including the key name.
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        The newly created SSH key with public key exposed.
+    """
     user = await _get_user(session, user_id)
     private_key, public_key = generate_ssh_key_pair()
 
@@ -92,22 +114,51 @@ async def create_ssh_key(
     return ssh_key
 
 
-@router.get("", response_model=list[SSHKeyResponse])
+@router.get(
+    "",
+    response_model=list[SSHKeyResponse],
+    summary="List SSH keys",
+    description="List all SSH keys for the authenticated user.",
+)
 async def list_ssh_keys(
     user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> list[SSHKey]:
+    """List all SSH keys for the authenticated user.
+
+    Args:
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        List of SSH keys owned by the user.
+    """
     user = await _get_user(session, user_id)
     result = await session.execute(select(SSHKey).where(SSHKey.user_id == user.id))
     return list(result.scalars().all())
 
 
-@router.delete("/{key_id}", status_code=status.HTTP_204_NO_CONTENT)
+@router.delete(
+    "/{key_id}",
+    status_code=status.HTTP_204_NO_CONTENT,
+    summary="Delete SSH key",
+    description="Delete an SSH key by ID.",
+)
 async def delete_ssh_key(
     key_id: uuid.UUID,
     user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> None:
+    """Delete an SSH key.
+
+    Args:
+        key_id: UUID of the SSH key to delete.
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        None with 204 status code.
+    """
     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:

apps/api/src/api/terminal.py

@@ -0,0 +1,124 @@
+"""WebSocket terminal endpoint for tool instances."""
+
+import asyncio
+import logging
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException, WebSocket, WebSocketDisconnect, status
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from src.auth.dependencies import get_db_session
+from src.models.tool_instance import ToolInstance
+from src.services.terminal_manager import terminal_manager
+
+router = APIRouter()
+logger = logging.getLogger(__name__)
+
+
+@router.websocket(
+    "/ws/tool-instances/{instance_id}/terminal",
+)
+async def terminal_websocket(
+    websocket: WebSocket,
+    instance_id: str,
+    db_session: AsyncSession = Depends(get_db_session),
+) -> None:
+    """WebSocket endpoint for terminal access to a tool instance.
+
+    Provides an interactive terminal session inside a running tool instance container.
+
+    Args:
+        websocket: The WebSocket connection.
+        instance_id: UUID string of the tool instance.
+        db_session: Database session.
+
+    Returns:
+        None. Communicates via WebSocket messages.
+    """
+    logger.info("Terminal WebSocket connection attempt for instance %s", instance_id)
+    await websocket.accept()
+
+    try:
+        # Parse instance_id
+        instance_uuid = uuid.UUID(instance_id)
+    except ValueError:
+        logger.error("Invalid instance ID: %s", instance_id)
+        await websocket.close(code=4001, reason="Invalid instance ID")
+        return
+
+    # Authenticate user from session cookie
+    user_id = await _get_user_from_websocket(websocket, db_session)
+    if user_id is None:
+        logger.warning("Unauthorized terminal access attempt for instance %s", instance_id)
+        await websocket.close(code=4003, reason="Unauthorized")
+        return
+
+    # Get instance and verify ownership
+    instance = await db_session.get(ToolInstance, instance_uuid)
+    if instance is None:
+        logger.warning("Instance %s not found", instance_id)
+        await websocket.close(code=4004, reason="Instance not found")
+        return
+
+    if instance.owner_id != user_id:
+        logger.warning("Forbidden terminal access for instance %s by user %s", instance_id, user_id)
+        await websocket.close(code=4003, reason="Forbidden")
+        return
+
+    if instance.status != "running" or not instance.container_id:
+        logger.warning("Instance %s not running (status=%s, container_id=%s)", instance_id, instance.status, instance.container_id)
+        await websocket.close(code=4004, reason="Instance not running")
+        return
+
+    logger.info("Creating terminal session for instance %s (container_id=%s)", instance_id, instance.container_id)
+    # Create terminal session
+    try:
+        session = await terminal_manager.create_session(
+            instance_uuid,
+            instance.container_id,
+            websocket,
+        )
+        logger.info("Terminal session created successfully for instance %s", instance_id)
+
+        # Send connected status
+        await websocket.send_json({"type": "status", "status": "connected"})
+
+        # Keep connection alive until session ends
+        # The terminal_manager handles I/O loops, we just wait here
+        while session.is_alive() and not session._closed:
+            await asyncio.sleep(0.5)
+
+    except Exception as exc:
+        logger.error("Terminal session error for instance %s: %s", instance_id, str(exc), exc_info=True)
+        await websocket.close(code=4000, reason=f"Error: {exc}")
+    finally:
+        # Cleanup will be handled by the session manager
+        pass
+
+
+async def _get_user_from_websocket(
+    websocket: WebSocket,
+    db_session: AsyncSession,
+) -> uuid.UUID | None:
+    """Extract and validate user ID from session cookie in WebSocket.
+
+    Args:
+        websocket: The WebSocket connection.
+        db_session: Database session.
+
+    Returns:
+        The user's UUID if authenticated, None otherwise.
+    """
+    from src.auth.session import decode_session_cookie
+    from src.config import Settings
+
+    session_cookie = websocket.cookies.get("session")
+    if not session_cookie:
+        return None
+
+    settings = Settings()
+    try:
+        payload = decode_session_cookie(settings=settings, cookie_value=session_cookie)
+        return uuid.UUID(str(payload["user_id"]))
+    except (ValueError, KeyError):
+        return None

apps/api/src/api/tool_configs.py

@@ -0,0 +1,322 @@
+"""Tool configuration API endpoints."""
+
+import logging
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from pydantic import BaseModel, Field, field_validator
+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_config import ToolConfig
+from src.models.tool_type import ToolType
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/tool-configs", tags=["tool-configs"])
+
+
+class ToolConfigCreate(BaseModel):
+    tool_type_id: str = Field(description="UUID of the tool type")
+    project_id: str | None = Field(default=None, description="Optional project ID for project-scoped config")
+    key: str = Field(description="Config key name")
+    value: str = Field(description="Config value")
+    config_type: str = Field(default="env", description="Type: env or file")
+    file_path: str | None = Field(default=None, description="File path for file-type configs")
+    port_override: int | None = Field(default=None, description="Port override (1-65535)")
+    start_command: str | None = Field(default=None, description="Override container start command")
+    working_directory: str | None = Field(default=None, description="Working directory inside container")
+    environment_variables: dict | None = Field(default=None, description="Environment variables as JSON object")
+    volumes: list[dict] | None = Field(default=None, description="Volume mounts as JSON array")
+
+    @field_validator("port_override")
+    @classmethod
+    def validate_port(cls, v: int | None) -> int | None:
+        if v is None:
+            return v
+        if v < 1 or v > 65535:
+            raise ValueError("Port must be between 1 and 65535")
+        return v
+
+    @field_validator("environment_variables")
+    @classmethod
+    def validate_env_vars(cls, v: dict | None) -> dict | None:
+        if v is None:
+            return v
+        if not isinstance(v, dict):
+            raise ValueError("environment_variables must be a JSON object")
+        return v
+
+    @field_validator("volumes")
+    @classmethod
+    def validate_volumes(cls, v: list | None) -> list | None:
+        if v is None:
+            return v
+        if not isinstance(v, list):
+            raise ValueError("volumes must be a JSON array")
+        for i, vol in enumerate(v):
+            if not isinstance(vol, dict):
+                raise ValueError(f"Volume at index {i} must be an object")
+            if "source" not in vol:
+                raise ValueError(f"Volume at index {i} must have 'source' field")
+            if "target" not in vol:
+                raise ValueError(f"Volume at index {i} must have 'target' field")
+        return v
+
+
+class ToolConfigUpdate(BaseModel):
+    key: str | None = Field(default=None, description="Config key name")
+    value: str | None = Field(default=None, description="Config value")
+    config_type: str | None = Field(default=None, description="Type: env or file")
+    file_path: str | None = Field(default=None, description="File path for file-type configs")
+    port_override: int | None = Field(default=None, description="Port override (1-65535)")
+    start_command: str | None = Field(default=None, description="Override container start command")
+    working_directory: str | None = Field(default=None, description="Working directory inside container")
+    environment_variables: dict | None = Field(default=None, description="Environment variables as JSON object")
+    volumes: list[dict] | None = Field(default=None, description="Volume mounts as JSON array")
+
+    @field_validator("port_override")
+    @classmethod
+    def validate_port(cls, v: int | None) -> int | None:
+        if v is None:
+            return v
+        if v < 1 or v > 65535:
+            raise ValueError("Port must be between 1 and 65535")
+        return v
+
+    @field_validator("environment_variables")
+    @classmethod
+    def validate_env_vars(cls, v: dict | None) -> dict | None:
+        if v is None:
+            return v
+        if not isinstance(v, dict):
+            raise ValueError("environment_variables must be a JSON object")
+        return v
+
+    @field_validator("volumes")
+    @classmethod
+    def validate_volumes(cls, v: list | None) -> list | None:
+        if v is None:
+            return v
+        if not isinstance(v, list):
+            raise ValueError("volumes must be a JSON array")
+        for i, vol in enumerate(v):
+            if not isinstance(vol, dict):
+                raise ValueError(f"Volume at index {i} must be an object")
+            if "source" not in vol:
+                raise ValueError(f"Volume at index {i} must have 'source' field")
+            if "target" not in vol:
+                raise ValueError(f"Volume at index {i} must have 'target' field")
+        return v
+
+
+class ToolConfigResponse(BaseModel):
+    id: str
+    tool_type_id: str
+    project_id: str | None
+    key: str
+    value: str
+    config_type: str
+    file_path: str | None
+    port_override: int | None
+    start_command: str | None
+    working_directory: str | None
+    environment_variables: dict | None
+    volumes: list[dict] | None
+
+
+@router.get("", summary="List tool configs", description="Get all tool configs for the current user.")
+async def list_configs(
+    tool_type_id: str | None = None,
+    project_id: str | None = None,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> list:
+    """List tool configs for the current user."""
+    query = select(ToolConfig).where(ToolConfig.user_id == user_id)
+    
+    if tool_type_id:
+        query = query.where(ToolConfig.tool_type_id == uuid.UUID(tool_type_id))
+    if project_id:
+        query = query.where(ToolConfig.project_id == uuid.UUID(project_id))
+    else:
+        # If no project specified, get only global configs (project_id is None)
+        query = query.where(ToolConfig.project_id.is_(None))
+    
+    result = await session.execute(query)
+    configs = result.scalars().all()
+    
+    return [
+        {
+            "id": str(c.id),
+            "tool_type_id": str(c.tool_type_id),
+            "project_id": str(c.project_id) if c.project_id else None,
+            "key": c.key,
+            "value": c.value,
+            "config_type": c.config_type,
+            "file_path": c.file_path,
+            "port_override": c.port_override,
+            "start_command": c.start_command,
+            "working_directory": c.working_directory,
+            "environment_variables": c.environment_variables,
+            "volumes": c.volumes,
+        }
+        for c in configs
+    ]
+
+
+@router.post("", summary="Create tool config", description="Create a new tool config.", status_code=status.HTTP_201_CREATED)
+async def create_config(
+    data: ToolConfigCreate,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Create a tool config."""
+    # Verify tool type exists
+    tool_type = await session.get(ToolType, uuid.UUID(data.tool_type_id))
+    if tool_type is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="tool type not found")
+    
+    # Check for existing config with same key
+    query = select(ToolConfig).where(
+        ToolConfig.user_id == user_id,
+        ToolConfig.tool_type_id == uuid.UUID(data.tool_type_id),
+        ToolConfig.key == data.key,
+    )
+    if data.project_id:
+        query = query.where(ToolConfig.project_id == uuid.UUID(data.project_id))
+    else:
+        query = query.where(ToolConfig.project_id.is_(None))
+    
+    existing = await session.scalar(query)
+    if existing:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=f"config with key '{data.key}' already exists"
+        )
+    
+    config = ToolConfig(
+        user_id=user_id,
+        tool_type_id=uuid.UUID(data.tool_type_id),
+        project_id=uuid.UUID(data.project_id) if data.project_id else None,
+        key=data.key,
+        value=data.value,
+        config_type=data.config_type,
+        file_path=data.file_path,
+        port_override=data.port_override,
+        start_command=data.start_command,
+        working_directory=data.working_directory,
+        environment_variables=data.environment_variables,
+        volumes=data.volumes,
+    )
+    session.add(config)
+    await session.commit()
+    await session.refresh(config)
+    
+    return {
+        "id": str(config.id),
+        "tool_type_id": str(config.tool_type_id),
+        "project_id": str(config.project_id) if config.project_id else None,
+        "key": config.key,
+        "value": config.value,
+        "config_type": config.config_type,
+        "file_path": config.file_path,
+        "port_override": config.port_override,
+        "start_command": config.start_command,
+        "working_directory": config.working_directory,
+        "environment_variables": config.environment_variables,
+        "volumes": config.volumes,
+    }
+
+
+@router.put("/{config_id}", summary="Update tool config", description="Update an existing tool config.")
+async def update_config(
+    config_id: uuid.UUID,
+    data: ToolConfigUpdate,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Update a tool config."""
+    config = await session.get(ToolConfig, config_id)
+    if config is None or config.user_id != user_id:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="config not found")
+    
+    if data.key is not None:
+        config.key = data.key
+    if data.value is not None:
+        config.value = data.value
+    if data.config_type is not None:
+        config.config_type = data.config_type
+    if data.file_path is not None:
+        config.file_path = data.file_path
+    if data.port_override is not None:
+        config.port_override = data.port_override
+    if data.start_command is not None:
+        config.start_command = data.start_command
+    if data.working_directory is not None:
+        config.working_directory = data.working_directory
+    if data.environment_variables is not None:
+        config.environment_variables = data.environment_variables
+    if data.volumes is not None:
+        config.volumes = data.volumes
+    
+    await session.commit()
+    await session.refresh(config)
+    
+    return {
+        "id": str(config.id),
+        "tool_type_id": str(config.tool_type_id),
+        "project_id": str(config.project_id) if config.project_id else None,
+        "key": config.key,
+        "value": config.value,
+        "config_type": config.config_type,
+        "file_path": config.file_path,
+        "port_override": config.port_override,
+        "start_command": config.start_command,
+        "working_directory": config.working_directory,
+        "environment_variables": config.environment_variables,
+        "volumes": config.volumes,
+    }
+
+
+@router.get("/defaults/{tool_type_id}", summary="Get default configs", description="Get suggested default configs for a tool type.")
+async def get_default_configs(
+    tool_type_id: str,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Get suggested default configs for a tool type."""
+    tool_type = await session.get(ToolType, uuid.UUID(tool_type_id))
+    if tool_type is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="tool type not found")
+    
+    # Return suggested defaults based on required_variables
+    defaults = []
+    for var in tool_type.required_variables:
+        defaults.append({
+            "key": var,
+            "value": "",
+            "config_type": "env",
+            "description": f"Required variable: {var}",
+        })
+    
+    return {
+        "tool_type_id": tool_type_id,
+        "suggested_configs": defaults,
+    }
+
+
+@router.delete("/{config_id}", summary="Delete tool config", description="Delete a tool config.")
+async def delete_config(
+    config_id: uuid.UUID,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> None:
+    """Delete a tool config."""
+    config = await session.get(ToolConfig, config_id)
+    if config is None or config.user_id != user_id:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="config not found")
+    
+    await session.delete(config)
+    await session.commit()

apps/api/src/api/tool_types.py

@@ -3,7 +3,7 @@ from datetime import datetime
 
 import yaml
 from fastapi import APIRouter, Depends, HTTPException, status
-from pydantic import BaseModel, ConfigDict, field_validator
+from pydantic import BaseModel, ConfigDict, field_validator, model_validator
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
@@ -15,6 +15,7 @@ router = APIRouter(prefix="/tool-types", tags=["tool-types"])
 
 
 async def _get_user(session: AsyncSession, user_id: uuid.UUID) -> User:
+    """Fetch a user by ID or raise 401 if not found."""
     user = await session.get(User, user_id)
     if user is None:
         raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="user not found")
@@ -22,6 +23,11 @@ async def _get_user(session: AsyncSession, user_id: uuid.UUID) -> User:
 
 
 async def _require_admin(user: User) -> None:
+    """Check if user has admin privileges.
+
+    For now, all authenticated users can manage tool types.
+    In production, this should check user.role or similar.
+    """
     # For now, all authenticated users can manage tool types
     # In production, check user.role or similar
     pass
@@ -31,12 +37,33 @@ class ToolTypeCreate(BaseModel):
     name: str
     display_name: str
     description: str | None = None
-    compose_template: str
+    default_port: int
+    definition_type: str = "compose"
+    compose_template: str | None = None
+    dockerfile_template: str | None = None
+    build_context: dict | None = None
+    readiness_probe: dict | None = None
     required_variables: list[str] = []
+    category: str = "other"
+    interfaces: list[str] = ["web"]
+
+    @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) -> str:
+    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'")
+        
         try:
             parsed = yaml.safe_load(v)
         except yaml.YAMLError as e:
@@ -53,18 +80,79 @@ class ToolTypeCreate(BaseModel):
         
         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("default_port")
+    @classmethod
+    def validate_default_port(cls, v: int, info) -> int:
+        if v <= 0 or v > 65535:
+            raise ValueError("Port must be between 1 and 65535")
+        
+        # Get compose_template from the model data
+        data = info.data
+        if data.get("definition_type") != "compose":
+            return v
+        
+        template = data.get("compose_template")
+        if not template:
+            return v
+        
+        try:
+            parsed = yaml.safe_load(template)
+        except yaml.YAMLError:
+            return v
+        
+        # Check if the port is exposed in any service
+        port_str = str(v)
+        port_exposed = False
+        
+        if isinstance(parsed, dict) and "services" in parsed:
+            for service_name, service_config in parsed["services"].items():
+                if isinstance(service_config, dict) and "ports" in service_config:
+                    for port_mapping in service_config["ports"]:
+                        if isinstance(port_mapping, str):
+                            # Format: "8443:8443" or "8443"
+                            if port_str in port_mapping:
+                                port_exposed = True
+                                break
+                        elif isinstance(port_mapping, int) and port_mapping == v:
+                            port_exposed = True
+                            break
+                if port_exposed:
+                    break
+        
+        if not port_exposed:
+            raise ValueError(f"Port {v} is not exposed in the compose template. Add it to the 'ports' section.")
+        
+        return v
+
     @field_validator("required_variables")
     @classmethod
     def validate_required_variables(cls, v: list[str], info) -> list[str]:
         if not v:
             return v
         
-        # Get compose_template from the model data
         data = info.data
-        if "compose_template" not in data:
+        if data.get("definition_type") != "compose":
+            return v
+        
+        template = data.get("compose_template")
+        if not template:
             return v
         
-        template = data["compose_template"]
         for var in v:
             placeholder = f"{{{{{var}}}}}"
             if placeholder not in template:
@@ -72,19 +160,48 @@ class ToolTypeCreate(BaseModel):
         
         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'")
+        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
     required_variables: list[str] | None = None
+    category: str | None = None
+    interfaces: list[str] | 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("compose_template")
     @classmethod
-    def validate_compose_template(cls, v: str | None) -> str | None:
+    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
+        
         try:
             parsed = yaml.safe_load(v)
         except yaml.YAMLError as e:
@@ -101,6 +218,22 @@ class ToolTypeUpdate(BaseModel):
         
         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)
@@ -109,7 +242,14 @@ class ToolTypeResponse(BaseModel):
     name: str
     display_name: str
     description: str | None
-    compose_template: str
+    category: str
+    interfaces: list[str]
+    default_port: int
+    definition_type: str
+    compose_template: str | None
+    dockerfile_template: str | None
+    build_context: dict | None
+    readiness_probe: dict | None
     required_variables: list[str]
     is_builtin: bool
     created_by_id: uuid.UUID | None
@@ -117,12 +257,28 @@ class ToolTypeResponse(BaseModel):
     updated_at: datetime
 
 
-@router.post("", response_model=ToolTypeResponse, status_code=status.HTTP_201_CREATED)
+@router.post(
+    "",
+    response_model=ToolTypeResponse,
+    status_code=status.HTTP_201_CREATED,
+    summary="Create tool type",
+    description="Create a new custom tool type with a Docker Compose template.",
+)
 async def create_tool_type(
     data: ToolTypeCreate,
     user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> ToolType:
+    """Create a new tool type.
+
+    Args:
+        data: Tool type creation data including name, display name, and compose template.
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        The newly created tool type.
+    """
     user = await _get_user(session, user_id)
     await _require_admin(user)
     
@@ -135,8 +291,15 @@ async def create_tool_type(
         name=data.name,
         display_name=data.display_name,
         description=data.description,
+        default_port=data.default_port,
+        definition_type=data.definition_type,
         compose_template=data.compose_template,
+        dockerfile_template=data.dockerfile_template,
+        build_context=data.build_context,
+        readiness_probe=data.readiness_probe,
         required_variables=data.required_variables,
+        category=data.category,
+        interfaces=data.interfaces,
         is_builtin=False,
         created_by_id=user.id,
     )
@@ -146,22 +309,51 @@ async def create_tool_type(
     return tool_type
 
 
-@router.get("", response_model=list[ToolTypeResponse])
+@router.get(
+    "",
+    response_model=list[ToolTypeResponse],
+    summary="List tool types",
+    description="List all available tool types including built-in and custom ones.",
+)
 async def list_tool_types(
     user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> list[ToolType]:
+    """List all tool types.
+
+    Args:
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        List of all tool types ordered by name.
+    """
     await _get_user(session, user_id)
     result = await session.execute(select(ToolType).order_by(ToolType.name))
     return list(result.scalars().all())
 
 
-@router.get("/{tool_type_id}", response_model=ToolTypeResponse)
+@router.get(
+    "/{tool_type_id}",
+    response_model=ToolTypeResponse,
+    summary="Get tool type",
+    description="Get a specific tool type by ID.",
+)
 async def get_tool_type(
     tool_type_id: uuid.UUID,
     user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> ToolType:
+    """Get a specific tool type by ID.
+
+    Args:
+        tool_type_id: UUID of the tool type to retrieve.
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        The requested tool type.
+    """
     await _get_user(session, user_id)
     tool_type = await session.get(ToolType, tool_type_id)
     if tool_type is None:
@@ -169,13 +361,29 @@ async def get_tool_type(
     return tool_type
 
 
-@router.put("/{tool_type_id}", response_model=ToolTypeResponse)
+@router.put(
+    "/{tool_type_id}",
+    response_model=ToolTypeResponse,
+    summary="Update tool type",
+    description="Update a custom tool type. Built-in tool types cannot be modified.",
+)
 async def update_tool_type(
     tool_type_id: uuid.UUID,
     data: ToolTypeUpdate,
     user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> ToolType:
+    """Update a tool type.
+
+    Args:
+        tool_type_id: UUID of the tool type to update.
+        data: Tool type update data with optional fields.
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        The updated tool type.
+    """
     user = await _get_user(session, user_id)
     await _require_admin(user)
     
@@ -188,7 +396,49 @@ async def update_tool_type(
     
     update_data = data.model_dump(exclude_unset=True)
     
-    # Validate required variables if both are being updated
+    # Validate port if being updated
+    if "default_port" in update_data:
+        new_port = update_data["default_port"]
+        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"
+            )
+        
+        # Only validate port exposure for compose definitions
+        definition_type = update_data.get("definition_type", tool_type.definition_type)
+        if definition_type == "compose":
+            template = update_data.get("compose_template", tool_type.compose_template)
+            if template:
+                try:
+                    parsed = yaml.safe_load(template)
+                except yaml.YAMLError:
+                    parsed = None
+                
+                if parsed and isinstance(parsed, dict) and "services" in parsed:
+                    port_str = str(new_port)
+                    port_exposed = False
+                    for service_config in parsed["services"].values():
+                        if isinstance(service_config, dict) and "ports" in service_config:
+                            for port_mapping in service_config["ports"]:
+                                if isinstance(port_mapping, str) and port_str in port_mapping:
+                                    port_exposed = True
+                                    break
+                                elif isinstance(port_mapping, int) and port_mapping == new_port:
+                                    port_exposed = True
+                                    break
+                        if port_exposed:
+                            break
+                    
+                    if not port_exposed:
+                        raise HTTPException(
+                            status_code=status.HTTP_400_BAD_REQUEST,
+                            detail=f"Port {new_port} is not exposed in the compose template"
+                        )
+    
+    # Validate required variables for compose definitions
+    definition_type = update_data.get("definition_type", tool_type.definition_type)
+    if definition_type == "compose":
         if "required_variables" in update_data and "compose_template" in update_data:
             template = update_data["compose_template"]
             for var in update_data["required_variables"]:
@@ -199,8 +449,8 @@ async def update_tool_type(
                         detail=f"Required variable '{var}' not found in compose template"
                     )
         elif "required_variables" in update_data:
-        # Only updating variables, check against existing template
             template = tool_type.compose_template
+            if template:
                 for var in update_data["required_variables"]:
                     placeholder = f"{{{{{var}}}}}"
                     if placeholder not in template:
@@ -217,12 +467,141 @@ async def update_tool_type(
     return tool_type
 
 
-@router.delete("/{tool_type_id}", status_code=status.HTTP_204_NO_CONTENT)
+class ToolTypeValidateRequest(BaseModel):
+    definition_type: str
+    compose_template: str | None = None
+    dockerfile_template: str | None = None
+
+
+@router.post(
+    "/validate",
+    summary="Validate tool type template",
+    description="Validate a compose template or dockerfile syntax before creating a tool type.",
+)
+async def validate_tool_type_template(
+    data: ToolTypeValidateRequest,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Validate a tool type template syntax.
+
+    Args:
+        data: Validation request with definition type and template.
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        Validation result with success status and any errors.
+    """
+    await _get_user(session, user_id)
+
+    errors = []
+
+    if data.definition_type == "compose":
+        if not data.compose_template:
+            errors.append("Compose template is required")
+        else:
+            try:
+                parsed = yaml.safe_load(data.compose_template)
+                if not isinstance(parsed, dict):
+                    errors.append("Compose template must be a YAML mapping")
+                elif "services" not in parsed:
+                    errors.append("Compose template must contain 'services' key")
+                elif not parsed["services"]:
+                    errors.append("Compose template must define at least one service")
+            except yaml.YAMLError as e:
+                errors.append(f"Invalid YAML: {e}")
+
+    elif data.definition_type == "dockerfile":
+        if not data.dockerfile_template:
+            errors.append("Dockerfile template is required")
+        elif not data.dockerfile_template.strip().startswith("FROM"):
+            errors.append("Dockerfile must start with a FROM instruction")
+
+    else:
+        errors.append("definition_type must be 'compose' or 'dockerfile'")
+
+    return {
+        "valid": len(errors) == 0,
+        "errors": errors,
+    }
+
+
+@router.get(
+    "/{tool_type_id}/validate",
+    summary="Validate tool type",
+    description="Validate the compose template or dockerfile syntax of a tool type.",
+)
+async def validate_tool_type(
+    tool_type_id: uuid.UUID,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Validate a tool type's template syntax.
+
+    Args:
+        tool_type_id: UUID of the tool type to validate.
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        Validation result with success status and any errors.
+    """
+    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")
+    
+    errors = []
+    
+    if tool_type.definition_type == "compose":
+        if not tool_type.compose_template:
+            errors.append("Compose template is empty")
+        else:
+            try:
+                parsed = yaml.safe_load(tool_type.compose_template)
+                if not isinstance(parsed, dict):
+                    errors.append("Compose template must be a YAML mapping")
+                elif "services" not in parsed:
+                    errors.append("Compose template must contain 'services' key")
+                elif not parsed["services"]:
+                    errors.append("Compose template must define at least one service")
+            except yaml.YAMLError as e:
+                errors.append(f"Invalid YAML: {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")
+    
+    return {
+        "valid": len(errors) == 0,
+        "errors": errors,
+    }
+
+
+@router.delete(
+    "/{tool_type_id}",
+    status_code=status.HTTP_204_NO_CONTENT,
+    summary="Delete tool type",
+    description="Delete a custom tool type. Built-in tool types cannot be deleted.",
+)
 async def delete_tool_type(
     tool_type_id: uuid.UUID,
     user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> None:
+    """Delete a tool type.
+
+    Args:
+        tool_type_id: UUID of the tool type to delete.
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        None with 204 status code.
+    """
     user = await _get_user(session, user_id)
     await _require_admin(user)
     

apps/api/src/api/user_config.py

@@ -1,6 +1,9 @@
+import logging
 import uuid
 
 from fastapi import APIRouter, Depends, HTTPException, status
+
+logger = logging.getLogger(__name__)
 from pydantic import BaseModel, ConfigDict
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
@@ -13,6 +16,7 @@ router = APIRouter(prefix="/users/me", tags=["user-config"])
 
 
 async def _get_user(session: AsyncSession, user_id: uuid.UUID) -> User:
+    """Fetch a user by ID or raise 401 if not found."""
     user = await session.get(User, user_id)
     if user is None:
         raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="user not found")
@@ -20,6 +24,15 @@ async def _get_user(session: AsyncSession, user_id: uuid.UUID) -> User:
 
 
 async def _get_or_create_config(session: AsyncSession, user_id: uuid.UUID) -> UserConfig:
+    """Get or create user config record.
+
+    Args:
+        session: Database session.
+        user_id: UUID of the user.
+
+    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))
     config = result.scalar_one_or_none()
     if config is None:
@@ -37,6 +50,7 @@ class UserConfigResponse(BaseModel):
     theme: str = "system"
     git_user_name: str | None = None
     git_user_email: str | None = None
+    last_session_id: str | None = None
 
 
 class UserConfigUpdate(BaseModel):
@@ -44,31 +58,64 @@ class UserConfigUpdate(BaseModel):
     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)
+@router.get(
+    "/config",
+    response_model=UserConfigResponse,
+    summary="Get user config",
+    description="Get the current user's configuration settings.",
+)
 async def get_user_config(
     user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> UserConfigResponse:
+    """Get the current user's configuration.
+
+    Args:
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        The user's configuration settings.
+    """
     _user = await _get_user(session, user_id)
     config = await _get_or_create_config(session, user_id)
     return UserConfigResponse.model_validate(config.config)
 
 
-@router.patch("/config", response_model=UserConfigResponse)
+@router.patch(
+    "/config",
+    response_model=UserConfigResponse,
+    summary="Update user config",
+    description="Update the current user's configuration settings.",
+)
 async def update_user_config(
     data: UserConfigUpdate,
     user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> UserConfigResponse:
+    """Update the current user's configuration.
+
+    Args:
+        data: Configuration update data with optional fields.
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        The updated user configuration.
+    """
     _user = await _get_user(session, user_id)
     config = await _get_or_create_config(session, user_id)
 
     # Merge updates
-    update_data = data.model_dump(exclude_unset=True, exclude_none=True)
-    config.config.update(update_data)
+    update_data = data.model_dump(exclude_unset=True)
+    logger.info("Updating user config for user %s: %s", user_id, update_data)
+    # SQLAlchemy JSON doesn't track dict mutations, so we replace the whole dict
+    config.config = {**config.config, **update_data}
 
     await session.commit()
     await session.refresh(config)
+    logger.info("Updated config: %s", config.config)
     return UserConfigResponse.model_validate(config.config)

apps/api/src/api/users.py

@@ -17,6 +17,7 @@ MAX_AVATAR_SIZE = 2 * 1024 * 1024  # 2MB
 
 
 async def _get_user(session: AsyncSession, user_id: uuid.UUID) -> User:
+    """Fetch a user by ID or raise 401 if not found."""
     user = await session.get(User, user_id)
     if user is None:
         raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="user not found")
@@ -37,20 +38,49 @@ class UserProfileUpdate(BaseModel):
     email: str | None = None
 
 
-@router.get("/me", response_model=UserProfileResponse)
+@router.get(
+    "/me",
+    response_model=UserProfileResponse,
+    summary="Get current user profile",
+    description="Retrieve the profile of the currently authenticated user.",
+)
 async def get_profile(
     user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> User:
+    """Get the current user's profile.
+
+    Args:
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        The user's profile information.
+    """
     return await _get_user(session, user_id)
 
 
-@router.put("/me", response_model=UserProfileResponse)
+@router.put(
+    "/me",
+    response_model=UserProfileResponse,
+    summary="Update user profile",
+    description="Update the current user's profile information.",
+)
 async def update_profile(
     data: UserProfileUpdate,
     user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> User:
+    """Update the current user's profile.
+
+    Args:
+        data: Profile update data with optional name and email.
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        The updated user profile.
+    """
     user = await _get_user(session, user_id)
 
     if data.name is not None:
@@ -68,12 +98,27 @@ async def update_profile(
     return user
 
 
-@router.post("/me/avatar", response_model=UserProfileResponse)
+@router.post(
+    "/me/avatar",
+    response_model=UserProfileResponse,
+    summary="Upload avatar",
+    description="Upload a profile avatar image (PNG or JPG, max 2MB).",
+)
 async def upload_avatar(
     file: UploadFile,
     user_id: uuid.UUID = Depends(get_current_user_id),
     session: AsyncSession = Depends(get_db_session),
 ) -> User:
+    """Upload a profile avatar image.
+
+    Args:
+        file: The image file to upload (PNG or JPG, max 2MB).
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        The updated user profile with new avatar URL.
+    """
     user = await _get_user(session, user_id)
 
     if file.content_type not in ALLOWED_CONTENT_TYPES:

apps/api/src/config.py

@@ -50,6 +50,11 @@ class Settings(BaseSettings):
     # Repository storage
     repo_base_path: str = "/data/repos"
     
+    # Tool instance storage
+    instance_base_path: str = "/data/instances"
+
+
+
     model_config = SettingsConfigDict(env_file=".env", extra="ignore", populate_by_name=True)
 
     @property

apps/api/src/main.py

@@ -1,16 +1,26 @@
+import json
 import logging
 import os
 
-from fastapi import FastAPI
+from fastapi import FastAPI, Request
+from fastapi.exceptions import RequestValidationError
 from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
 from fastapi.staticfiles import StaticFiles
 from sqlalchemy import select, text
 
 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_folders import router as config_folders_router
+from src.api.tool_configs import router as tool_configs_router
+from src.api.tool_instances import router as tool_instances_router
+from src.api.tool_instances import sessions_router
 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
@@ -32,9 +42,15 @@ settings = Settings()
 app = FastAPI(title="Headquarter API")
 
 # Configure CORS - must be before other middleware
+# Build allowed origins list including web and api domains
+cors_origins = [settings.web_base_url]
+if settings.api_base_url != settings.web_base_url:
+    cors_origins.append(settings.api_base_url)
+logger.info("CORS configured with origins: %s", cors_origins)
+
 app.add_middleware(
     CORSMiddleware,
-    allow_origins=[settings.web_base_url],
+    allow_origins=cors_origins,
     allow_credentials=True,
     allow_methods=["*"],
     allow_headers=["*"],
@@ -44,6 +60,49 @@ app.add_middleware(RequestLoggingMiddleware)
 app.add_middleware(ExceptionLoggingMiddleware)
 
 
+def _sanitize_validation_errors(errors):
+    """Convert validation errors to JSON-safe format."""
+    sanitized = []
+    for error in errors:
+        safe_error = {
+            "type": error.get("type"),
+            "loc": error.get("loc"),
+            "msg": error.get("msg"),
+            "input": str(error.get("input")) if error.get("input") is not None else None,
+        }
+        # Convert ctx to safe format
+        ctx = error.get("ctx")
+        if ctx:
+            safe_ctx = {}
+            for key, value in ctx.items():
+                if isinstance(value, Exception):
+                    safe_ctx[key] = str(value)
+                elif isinstance(value, (str, int, float, bool, type(None))):
+                    safe_ctx[key] = value
+                else:
+                    safe_ctx[key] = str(value)
+            safe_error["ctx"] = safe_ctx
+        sanitized.append(safe_error)
+    return sanitized
+
+
+@app.exception_handler(RequestValidationError)
+async def validation_exception_handler(request: Request, exc: RequestValidationError):
+    """Log validation errors and return detailed response."""
+    errors = exc.errors()
+    logger.warning(
+        "Validation error for %s %s: %s",
+        request.method,
+        request.url.path,
+        errors,
+    )
+    safe_errors = _sanitize_validation_errors(errors)
+    return JSONResponse(
+        status_code=422,
+        content={"detail": safe_errors},
+    )
+
+
 async def _table_exists(session, table_name: str) -> bool:
     """Check if a table exists in the database."""
     try:
@@ -77,6 +136,8 @@ async def seed_builtin_tool_types():
                 "name": "code-server",
                 "display_name": "VS Code Server",
                 "description": "VS Code running in the browser via code-server",
+                "category": "editor",
+                "interfaces": ["web"],
                 "compose_template": """version: "3.8"
 services:
   code-server:
@@ -91,12 +152,16 @@ services:
     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",
+                "interfaces": ["web"],
+                "default_port": 8888,
                 "compose_template": """version: "3.8"
 services:
   jupyter:
@@ -111,6 +176,47 @@ services:
     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",
+                "interfaces": ["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:
@@ -120,11 +226,27 @@ services:
                     name=tool_data["name"],
                     display_name=tool_data["display_name"],
                     description=tool_data["description"],
+                    category=tool_data["category"],
+                    interfaces=tool_data["interfaces"],
+                    definition_type="compose",
                     compose_template=tool_data["compose_template"],
                     required_variables=tool_data["required_variables"],
+                    default_port=tool_data.get("default_port"),
                     is_builtin=True,
                 )
                 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.interfaces = tool_data["interfaces"]
+                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")
+                logger.info("Updated built-in tool type: %s", tool_data["name"])
 
         await session.commit()
         logger.info("Built-in tool types seeded successfully.")
@@ -145,17 +267,7 @@ async def on_startup():
     await seed_builtin_tool_types()
     logger.info("Startup complete.")
 
-@app.get("/health")
-async def health_check():
-    try:
-        from sqlalchemy import text
-        async with SessionLocal() as session:
-            await session.execute(text("SELECT 1"))
-        return {"status": "healthy", "database": "connected"}
-    except Exception as exc:
-        logger.error("Health check failed: %s", exc)
-        return {"status": "unhealthy", "database": "disconnected", "error": str(exc)}
-
+app.include_router(health_router)
 app.include_router(auth_router)
 app.include_router(dashboard_router)
 app.include_router(projects_router)
@@ -164,4 +276,10 @@ app.include_router(ssh_keys_router)
 app.include_router(git_repositories_router)
 app.include_router(user_config_router)
 app.include_router(tool_types_router)
+app.include_router(config_folders_router)
+app.include_router(tool_instances_router)
+app.include_router(tool_configs_router)
+app.include_router(sessions_router)
+app.include_router(instance_proxy_router)
+app.include_router(terminal_router)
 app.mount("/uploads", StaticFiles(directory="uploads"), name="uploads")

apps/api/src/models/__init__.py

@@ -1,9 +1,11 @@
 from src.models.base import Base
+from src.models.config_folder import ConfigFolder
 from src.models.git_repository import GitRepository
 from src.models.project import Project
 from src.models.ssh_key import SSHKey
+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
 
-__all__ = ["Base", "GitRepository", "Project", "SSHKey", "ToolType", "User", "UserConfig"]
+__all__ = ["Base", "ConfigFolder", "GitRepository", "Project", "SSHKey", "ToolInstance", "ToolType", "User", "UserConfig"]

apps/api/src/models/config_folder.py

@@ -0,0 +1,31 @@
+import uuid
+from typing import TYPE_CHECKING
+
+from sqlalchemy import Boolean, ForeignKey, JSON, String, Text
+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 ConfigFolder(UUIDPrimaryKeyMixin, TimestampMixin, Base):
+    __tablename__ = "config_folders"
+
+    user_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(), ForeignKey("users.id", ondelete="CASCADE"), nullable=False
+    )
+    name: Mapped[str] = mapped_column(String(255), nullable=False)
+    description: Mapped[str | None] = mapped_column(Text, nullable=True)
+    mount_path: Mapped[str] = mapped_column(String(1024), nullable=False)
+    files: Mapped[dict] = mapped_column(
+        JSON, default=dict, nullable=False
+    )  # {"relative/path": "content", ...}
+    project_overrides: Mapped[dict | None] = mapped_column(
+        JSON, default=dict, nullable=True
+    )  # {"project_id": {"mount_path": "...", "files": {...}}}
+    is_active: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
+
+    user: Mapped["User"] = relationship()

apps/api/src/models/tool_config.py

@@ -0,0 +1,48 @@
+import uuid
+from typing import TYPE_CHECKING
+
+from sqlalchemy import ForeignKey, JSON, String, Text
+from sqlalchemy import Uuid as UUID
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from src.models.base import Base, TimestampMixin, UUIDPrimaryKeyMixin
+
+if TYPE_CHECKING:
+    from src.models.project import Project
+    from src.models.tool_type import ToolType
+    from src.models.user import User
+
+
+class ToolConfig(UUIDPrimaryKeyMixin, TimestampMixin, Base):
+    __tablename__ = "tool_configs"
+
+    user_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(), ForeignKey("users.id"), nullable=False
+    )
+    tool_type_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(), ForeignKey("tool_types.id"), nullable=False
+    )
+    project_id: Mapped[uuid.UUID | None] = mapped_column(
+        UUID(), ForeignKey("projects.id"), nullable=True
+    )
+    key: Mapped[str] = mapped_column(String(255), nullable=False)
+    value: Mapped[str] = mapped_column(Text, nullable=False)
+    config_type: Mapped[str] = mapped_column(
+        String(20), nullable=False, default="env"
+    )  # "env" or "file"
+    file_path: Mapped[str | None] = mapped_column(
+        String(1024), nullable=True
+    )  # Only for file type
+    port_override: Mapped[int | None] = mapped_column(nullable=True)
+    start_command: Mapped[str | None] = mapped_column(Text, nullable=True)
+    working_directory: Mapped[str | None] = mapped_column(Text, nullable=True)
+    environment_variables: Mapped[dict | None] = mapped_column(
+        JSON, default=dict, nullable=True
+    )
+    volumes: Mapped[list[dict] | None] = mapped_column(
+        JSON, default=list, nullable=True
+    )
+
+    user: Mapped["User"] = relationship()
+    tool_type: Mapped["ToolType"] = relationship()
+    project: Mapped["Project | None"] = relationship()

apps/api/src/models/tool_instance.py

@@ -0,0 +1,72 @@
+import uuid
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+from sqlalchemy import DateTime, ForeignKey, Integer, JSON, String
+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.git_repository import GitRepository
+    from src.models.project import Project
+    from src.models.tool_type import ToolType
+    from src.models.user import User
+
+
+class ToolInstance(UUIDPrimaryKeyMixin, TimestampMixin, Base):
+    __tablename__ = "tool_instances"
+
+    name: Mapped[str] = mapped_column(String(255), nullable=False)
+    display_name: Mapped[str] = mapped_column(String(255), nullable=False)
+    tool_type_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(), ForeignKey("tool_types.id"), nullable=False
+    )
+    repository_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(), ForeignKey("git_repositories.id"), nullable=False
+    )
+    project_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(), ForeignKey("projects.id"), nullable=False
+    )
+    owner_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(), ForeignKey("users.id"), nullable=False
+    )
+    status: Mapped[str] = mapped_column(
+        String(50), nullable=False, default="pending"
+    )
+    container_id: Mapped[str | None] = mapped_column(
+        String(255), nullable=True
+    )
+    container_name: Mapped[str | None] = mapped_column(
+        String(255), nullable=True
+    )
+    compose_path: Mapped[str | None] = mapped_column(
+        String(1024), nullable=True
+    )
+    url: Mapped[str | None] = mapped_column(
+        String(1024), nullable=True
+    )
+    public_url: Mapped[str | None] = mapped_column(
+        String(1024), nullable=True
+    )
+    tunnel_id: Mapped[str | None] = mapped_column(
+        String(255), nullable=True
+    )
+    port: Mapped[int | None] = mapped_column(
+        Integer, nullable=True
+    )
+    last_started_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+    last_stopped_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+    probe_result: Mapped[dict | None] = mapped_column(
+        JSON, nullable=True
+    )
+
+    tool_type: Mapped["ToolType"] = relationship()
+    repository: Mapped["GitRepository"] = relationship()
+    project: Mapped["Project"] = relationship()
+    owner: Mapped["User"] = relationship()

apps/api/src/models/tool_type.py

@@ -17,7 +17,18 @@ class ToolType(UUIDPrimaryKeyMixin, TimestampMixin, Base):
     name: Mapped[str] = mapped_column(String(255), unique=True, nullable=False)
     display_name: Mapped[str] = mapped_column(String(255), nullable=False)
     description: Mapped[str | None] = mapped_column(Text, nullable=True)
-    compose_template: Mapped[str] = mapped_column(Text, nullable=False)
+    category: Mapped[str] = mapped_column(String(50), nullable=False, default="other")
+    interfaces: Mapped[list[str]] = mapped_column(JSON, default=list, nullable=False)
+    default_port: Mapped[int] = mapped_column(nullable=False)
+    definition_type: Mapped[str] = mapped_column(
+        String(20), nullable=False, default="compose"
+    )  # "compose" or "dockerfile"
+    compose_template: Mapped[str | None] = mapped_column(Text, nullable=True)
+    dockerfile_template: Mapped[str | None] = mapped_column(Text, nullable=True)
+    build_context: Mapped[dict | None] = mapped_column(
+        JSON, default=dict, nullable=True
+    )
+    readiness_probe: Mapped[dict | None] = mapped_column(JSON, nullable=True)
     required_variables: Mapped[list[str]] = mapped_column(JSON, default=list, nullable=False)
     is_builtin: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
     created_by_id: Mapped[uuid.UUID | None] = mapped_column(

apps/api/src/services/docker.py

@@ -0,0 +1,563 @@
+"""Docker service for managing tool instances."""
+
+import os
+import subprocess
+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 write_config_folder_files(instance_dir: str, folders: list, project_id: str | None = None) -> list[dict]:
+    """Write config folder files to the instance directory and return volume mounts.
+
+    Args:
+        instance_dir: Path to instance directory
+        folders: List of ConfigFolder objects
+        project_id: Optional project ID for applying overrides
+
+    Returns:
+        List of volume mount dicts [{"source": "...", "target": "...", "type": "..."}]
+    """
+    instance_path = Path(instance_dir)
+    volume_mounts = []
+
+    for folder in folders:
+        # Determine mount path (with project override if applicable)
+        mount_path = folder.mount_path
+        files = folder.files.copy()
+        
+        if project_id and folder.project_overrides:
+            override = folder.project_overrides.get(str(project_id))
+            if override:
+                if override.get("mount_path"):
+                    mount_path = override["mount_path"]
+                if override.get("files"):
+                    files.update(override["files"])
+        
+        # Write files to instance directory
+        folder_dir = instance_path / "volumes" / folder.name
+        folder_dir.mkdir(parents=True, exist_ok=True)
+        
+        for file_path, content in files.items():
+            # Security: ensure path doesn't escape folder_dir
+            full_path = folder_dir / file_path
+            try:
+                full_path.resolve().relative_to(folder_dir.resolve())
+            except ValueError:
+                logger.warning("Config folder file path escapes directory: %s", file_path)
+                continue
+            
+            full_path.parent.mkdir(parents=True, exist_ok=True)
+            full_path.write_text(content)
+        
+        # Add volume mount
+        volume_mounts.append({
+            "source": str(folder_dir),
+            "target": mount_path,
+            "type": "bind",
+        })
+    
+    return volume_mounts
+
+
+def execute_compose_command(
+    compose_path: str, action: str, timeout: int = 60, env_file: str | None = None
+) -> tuple[int, str, str]:
+    """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.
+
+    Args:
+        instance_name: The service name in compose
+
+    Returns:
+        Container ID or None if not found
+    """
+    result = subprocess.run(
+        ["docker", "ps", "-q", "--filter", f"name={instance_name}"],
+        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.
+
+    Args:
+        instance_name: The service name in compose
+
+    Returns:
+        Container name or None if not found
+    """
+    result = subprocess.run(
+        ["docker", "ps", "--format", "{{.Names}}", "--filter", f"name={instance_name}"],
+        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)
+    """
+    import time
+
+    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}")
+
+
+import subprocess
+import time
+import re
+
+
+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 time
+    import re
+    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
+
+    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 os
+    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_build.py

@@ -0,0 +1,69 @@
+"""Docker build service for building images from Dockerfiles."""
+
+import logging
+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]:
+    """Build a Docker image from a Dockerfile.
+
+    Args:
+        instance_dir: Directory containing the Dockerfile
+        dockerfile: Dockerfile content
+        tag: Image tag to apply
+        build_context: Optional build context files {path: content}
+
+    Returns:
+        Tuple of (returncode, stdout, stderr)
+    """
+    import os
+    from pathlib import Path
+
+    # Write Dockerfile
+    dockerfile_path = Path(instance_dir) / "Dockerfile"
+    dockerfile_path.write_text(dockerfile)
+    logger.info("Wrote Dockerfile to %s", dockerfile_path)
+
+    # Write build context files
+    if build_context:
+        for file_path, content in build_context.items():
+            full_path = Path(instance_dir) / file_path
+            # Security: ensure path doesn't escape instance_dir
+            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")
+            
+            full_path.parent.mkdir(parents=True, exist_ok=True)
+            full_path.write_text(content)
+            logger.info("Wrote build context file: %s", full_path)
+
+    # Build image
+    logger.info("Building Docker image with tag: %s", tag)
+    cmd = [
+        "docker", "build",
+        "-t", tag,
+        "-f", str(dockerfile_path),
+        instance_dir,
+    ]
+
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=300,  # 5 minute timeout for builds
+        )
+        logger.info("Docker build completed: returncode=%d", result.returncode)
+        if result.returncode != 0:
+            logger.error("Docker build failed: %s", result.stderr[:1000])
+        return result.returncode, result.stdout, result.stderr
+    except subprocess.TimeoutExpired:
+        logger.error("Docker build timed out after 300 seconds")
+        return 1, "", "Build timed out after 300 seconds"
+    except Exception as exc:
+        logger.exception("Docker build failed: %s", exc)
+        return 1, "", str(exc)

apps/api/src/services/readiness_probe.py

@@ -0,0 +1,66 @@
+"""Readiness probe service for checking if containers are ready."""
+
+import asyncio
+import logging
+import subprocess
+
+logger = logging.getLogger(__name__)
+
+
+async def execute_probe(
+    container_id: str,
+    command: str,
+    timeout: int = 30,
+    interval: int = 2,
+) -> tuple[bool, list[str]]:
+    """Execute a readiness probe command inside a container.
+
+    Args:
+        container_id: Docker container ID or name
+        command: Command to execute inside the container
+        timeout: Maximum total time to wait (seconds)
+        interval: Time between retries (seconds)
+
+    Returns:
+        Tuple of (success, logs)
+    """
+    logs = []
+    start_time = asyncio.get_event_loop().time()
+    attempt = 0
+
+    while True:
+        attempt += 1
+        elapsed = asyncio.get_event_loop().time() - start_time
+        
+        if elapsed >= timeout:
+            logs.append(f"Probe timed out after {timeout}s ({attempt} attempts)")
+            return False, logs
+
+        try:
+            logger.debug("Probe attempt %d: %s", attempt, command)
+            
+            # Execute command inside container
+            result = subprocess.run(
+                ["docker", "exec", container_id, "sh", "-c", command],
+                capture_output=True,
+                text=True,
+                timeout=interval,  # Each attempt has its own timeout
+            )
+            
+            if result.returncode == 0:
+                logs.append(f"Attempt {attempt}: Success")
+                if result.stdout:
+                    logs.append(f"Output: {result.stdout.strip()}")
+                return True, logs
+            else:
+                logs.append(f"Attempt {attempt}: Failed (exit code {result.returncode})")
+                if result.stderr:
+                    logs.append(f"Stderr: {result.stderr.strip()[:200]}")
+                
+        except subprocess.TimeoutExpired:
+            logs.append(f"Attempt {attempt}: Command timed out")
+        except Exception as exc:
+            logs.append(f"Attempt {attempt}: Error - {exc}")
+
+        # Wait before next attempt
+        await asyncio.sleep(interval)

apps/api/src/services/terminal_manager.py

@@ -0,0 +1,96 @@
+"""Terminal session manager for WebSocket connections."""
+
+import asyncio
+import uuid
+from typing import Any
+
+from fastapi import WebSocket
+
+from src.services.terminal_session import TerminalSession
+
+
+class TerminalManager:
+    """Manages active terminal sessions."""
+
+    def __init__(self) -> None:
+        self._sessions: dict[str, TerminalSession] = {}
+
+    async def create_session(
+        self,
+        instance_id: uuid.UUID,
+        container_id: str,
+        websocket: WebSocket,
+    ) -> TerminalSession:
+        """Create a new terminal session."""
+        session_id = str(uuid.uuid4())
+        session = TerminalSession(session_id, instance_id, container_id)
+        await session.start()
+        self._sessions[session_id] = session
+
+        # Start background tasks for I/O streaming
+        asyncio.create_task(self._read_loop(session, websocket))
+        asyncio.create_task(self._write_loop(session, websocket))
+
+        return session
+
+    async def _read_loop(self, session: TerminalSession, websocket: WebSocket) -> None:
+        """Read output from the container and send to WebSocket."""
+        try:
+            while session.is_alive() and not session._closed:
+                data = await session.read_output()
+                if data:
+                    await websocket.send_bytes(data)
+                else:
+                    await asyncio.sleep(0.01)
+        except Exception:
+            pass
+        finally:
+            await self._cleanup_session(session)
+
+    async def _write_loop(self, session: TerminalSession, websocket: WebSocket) -> None:
+        """Read input from WebSocket and send to container."""
+        try:
+            while session.is_alive() and not session._closed:
+                message = await websocket.receive()
+                if message["type"] == "websocket.receive":
+                    if "bytes" in message:
+                        await session.write_input(message["bytes"])
+                    elif "text" in message:
+                        text = message["text"]
+                        if text.startswith("{"):
+                            # Control message (JSON)
+                            import json
+                            try:
+                                ctrl = json.loads(text)
+                                if ctrl.get("type") == "resize":
+                                    await session.resize(
+                                        ctrl.get("cols", 80),
+                                        ctrl.get("rows", 24),
+                                    )
+                            except json.JSONDecodeError:
+                                pass
+                        else:
+                            await session.write_input(text.encode("utf-8"))
+                elif message["type"] == "websocket.disconnect":
+                    break
+        except Exception:
+            pass
+        finally:
+            await self._cleanup_session(session)
+
+    async def _cleanup_session(self, session: TerminalSession) -> None:
+        """Clean up a session."""
+        if session.session_id in self._sessions:
+            del self._sessions[session.session_id]
+        await session.close()
+
+    async def close_all(self) -> None:
+        """Close all active sessions."""
+        sessions = list(self._sessions.values())
+        self._sessions.clear()
+        for session in sessions:
+            await session.close()
+
+
+# Global terminal manager instance
+terminal_manager = TerminalManager()

apps/api/src/services/terminal_session.py

@@ -0,0 +1,117 @@
+"""Terminal session management for tool instances."""
+
+import asyncio
+import os
+import pty
+import select
+import struct
+import fcntl
+import uuid
+from typing import Any
+
+
+class TerminalSession:
+    """Manages a single terminal session connected to a docker container."""
+
+    def __init__(self, session_id: str, instance_id: uuid.UUID, container_id: str) -> None:
+        self.session_id = session_id
+        self.instance_id = instance_id
+        self.container_id = container_id
+        self.process: asyncio.subprocess.Process | None = None
+        self._closed = False
+        self._master_fd: int | None = None
+        self._slave_fd: int | None = None
+
+    async def start(self) -> None:
+        """Start the docker exec process with a shell using a PTY."""
+        # Create a pseudo-terminal on the host
+        self._master_fd, self._slave_fd = pty.openpty()
+        
+        # Set the terminal size initially
+        self._set_terminal_size(80, 24)
+        
+        # Start docker exec with the slave fd as stdin/stdout/stderr
+        # Using -it because the slave fd IS a TTY
+        self.process = await asyncio.create_subprocess_exec(
+            "docker",
+            "exec",
+            "-it",
+            "-e",
+            "TERM=xterm",
+            self.container_id,
+            "bash",
+            "-il",
+            stdin=self._slave_fd,
+            stdout=self._slave_fd,
+            stderr=self._slave_fd,
+        )
+        
+        # Close slave fd in parent process
+        os.close(self._slave_fd)
+        self._slave_fd = None
+
+    def _set_terminal_size(self, cols: int, rows: int) -> None:
+        """Set the terminal size using TIOCSWINSZ."""
+        if self._master_fd is None:
+            return
+        # TIOCSWINSZ = 0x5414 on Linux
+        TIOCSWINSZ = 0x5414
+        size = struct.pack('HHHH', rows, cols, 0, 0)
+        try:
+            fcntl.ioctl(self._master_fd, TIOCSWINSZ, size)
+        except (OSError, IOError):
+            pass
+
+    async def read_output(self) -> bytes:
+        """Read output from the PTY master."""
+        if self._master_fd is None or self._closed:
+            return b""
+        try:
+            # Use select to check if data is available
+            readable, _, _ = select.select([self._master_fd], [], [], 0.1)
+            if readable:
+                return os.read(self._master_fd, 4096)
+            return b""
+        except (OSError, IOError, ValueError):
+            return b""
+
+    async def write_input(self, data: bytes) -> None:
+        """Write input to the PTY master."""
+        if self._master_fd is None or self._closed:
+            return
+        try:
+            os.write(self._master_fd, data)
+        except (OSError, IOError):
+            pass
+
+    async def resize(self, cols: int, rows: int) -> None:
+        """Resize the terminal."""
+        if self._closed:
+            return
+        self._set_terminal_size(cols, rows)
+
+    async def close(self) -> None:
+        """Close the session and cleanup."""
+        if self._closed:
+            return
+        self._closed = True
+
+        if self._master_fd is not None:
+            try:
+                os.close(self._master_fd)
+            except OSError:
+                pass
+            self._master_fd = None
+
+        if self.process is not None:
+            try:
+                self.process.kill()
+                await asyncio.wait_for(self.process.wait(), timeout=2.0)
+            except (asyncio.TimeoutError, ProcessLookupError):
+                pass
+
+    def is_alive(self) -> bool:
+        """Check if the session process is still running."""
+        if self.process is None:
+            return False
+        return self.process.returncode is None

apps/api/src/utils/git_control.py

@@ -0,0 +1,314 @@
+"""Git control utilities for repository operations."""
+
+import subprocess
+from dataclasses import dataclass, field
+from typing import Any
+
+
+def _run_git_command(repo_path: str, *args: str) -> str:
+    """Run a git command in the repository directory."""
+    result = subprocess.run(
+        ["git", *args],
+        cwd=repo_path,
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(f"Git command failed: {result.stderr}")
+    return result.stdout
+
+
+@dataclass
+class GitStatus:
+    """Represents the working directory status."""
+
+    branch: str
+    modified: list[str] = field(default_factory=list)
+    added: list[str] = field(default_factory=list)
+    deleted: list[str] = field(default_factory=list)
+    untracked: list[str] = field(default_factory=list)
+    renamed: list[str] = field(default_factory=list)
+    ahead: int = 0
+    behind: int = 0
+
+
+def get_status(repo_path: str) -> GitStatus:
+    """Get the working directory status.
+
+    Args:
+        repo_path: Path to the git repository
+
+    Returns:
+        GitStatus with changes
+    """
+    # Get current branch
+    try:
+        branch = _run_git_command(repo_path, "rev-parse", "--abbrev-ref", "HEAD").strip()
+    except RuntimeError:
+        try:
+            branch = _run_git_command(repo_path, "symbolic-ref", "--short", "HEAD").strip()
+        except RuntimeError:
+            branch = "HEAD"
+
+    status = GitStatus(branch=branch)
+
+    # Get status with porcelain format
+    try:
+        output = _run_git_command(repo_path, "status", "--porcelain", "--branch")
+    except RuntimeError:
+        return status
+
+    for line in output.strip().split("\n"):
+        if not line:
+            continue
+
+        # Branch info line starts with ##
+        if line.startswith("## "):
+            branch_info = line[3:]
+            # Parse ahead/behind info
+            if "[ahead " in branch_info:
+                ahead_str = branch_info.split("[ahead ")[1].split("]")[0]
+                status.ahead = int(ahead_str.split(",")[0])
+            if "[behind " in branch_info:
+                behind_str = branch_info.split("[behind ")[1].split("]")[0]
+                status.behind = int(behind_str.split(",")[0])
+            continue
+
+        # Parse status code
+        if len(line) < 3:
+            continue
+
+        index_status = line[0]
+        worktree_status = line[1]
+        filename = line[3:]
+
+        # Untracked files
+        if index_status == "?" and worktree_status == "?":
+            status.untracked.append(filename)
+            continue
+
+        # Added files
+        if index_status == "A" or worktree_status == "A":
+            status.added.append(filename)
+            continue
+
+        # Deleted files
+        if index_status == "D" or worktree_status == "D":
+            status.deleted.append(filename)
+            continue
+
+        # Renamed files
+        if index_status == "R" or worktree_status == "R":
+            status.renamed.append(filename)
+            continue
+
+        # Modified files
+        if index_status == "M" or worktree_status == "M":
+            status.modified.append(filename)
+            continue
+
+    return status
+
+
+def create_branch(repo_path: str, name: str, base_branch: str = "HEAD") -> None:
+    """Create a new branch.
+
+    Args:
+        repo_path: Path to the git repository
+        name: Branch name
+        base_branch: Base branch to create from (default: HEAD)
+
+    Raises:
+        RuntimeError: If branch creation fails
+    """
+    try:
+        _run_git_command(repo_path, "rev-parse", "--verify", "HEAD^{commit}")
+    except RuntimeError:
+        # No commits yet - empty repository
+        try:
+            _run_git_command(repo_path, "checkout", "--orphan", name)
+        except RuntimeError as e:
+            if "work tree" in str(e).lower():
+                # Bare repository - use symbolic-ref instead
+                _run_git_command(repo_path, "symbolic-ref", "HEAD", f"refs/heads/{name}")
+                return
+            raise
+        return
+
+    _run_git_command(repo_path, "branch", name, base_branch)
+
+
+def delete_branch(repo_path: str, name: str, force: bool = False) -> None:
+    """Delete a branch.
+
+    Args:
+        repo_path: Path to the git repository
+        name: Branch name
+        force: Force delete even if not merged
+
+    Raises:
+        RuntimeError: If branch deletion fails
+    """
+    flag = "-D" if force else "-d"
+    _run_git_command(repo_path, "branch", flag, name)
+
+
+def checkout_branch(repo_path: str, name: str) -> None:
+    """Checkout a branch.
+
+    Args:
+        repo_path: Path to the git repository
+        name: Branch name
+
+    Raises:
+        RuntimeError: If checkout fails
+    """
+    try:
+        _run_git_command(repo_path, "checkout", name)
+    except RuntimeError as e:
+        if "work tree" in str(e).lower():
+            # Bare repository - use symbolic-ref instead
+            _run_git_command(repo_path, "symbolic-ref", "HEAD", f"refs/heads/{name}")
+            return
+        raise
+
+
+def commit_changes(
+    repo_path: str,
+    message: str,
+    author_name: str,
+    author_email: str,
+    files: list[str] | None = None,
+) -> str:
+    """Commit changes to the repository.
+
+    Args:
+        repo_path: Path to the git repository
+        message: Commit message
+        author_name: Author name
+        author_email: Author email
+        files: Specific files to commit (None = all staged)
+
+    Returns:
+        Commit hash
+
+    Raises:
+        RuntimeError: If commit fails
+    """
+    # Stage files if specified
+    if files:
+        for file in files:
+            _run_git_command(repo_path, "add", file)
+    else:
+        _run_git_command(repo_path, "add", "-A")
+
+    # Commit
+    _run_git_command(
+        repo_path,
+        "commit",
+        "-m",
+        message,
+        f"--author={author_name} <{author_email}>",
+    )
+
+    # Return commit hash
+    return _run_git_command(repo_path, "rev-parse", "HEAD").strip()
+
+
+def fetch(repo_path: str) -> None:
+    """Fetch from remote.
+
+    Args:
+        repo_path: Path to the git repository
+
+    Raises:
+        RuntimeError: If fetch fails
+    """
+    _run_git_command(repo_path, "fetch", "--all")
+
+
+def pull(repo_path: str, branch: str | None = None) -> None:
+    """Pull updates from remote.
+
+    Args:
+        repo_path: Path to the git repository
+        branch: Branch to pull (default: current branch)
+
+    Raises:
+        RuntimeError: If pull fails
+    """
+    args = ["pull"]
+    if branch:
+        args.append("origin")
+        args.append(branch)
+    _run_git_command(repo_path, *args)
+
+
+def push(repo_path: str, branch: str | None = None) -> None:
+    """Push changes to remote.
+
+    Args:
+        repo_path: Path to the git repository
+        branch: Branch to push (default: current branch)
+
+    Raises:
+        RuntimeError: If push fails
+    """
+    args = ["push"]
+    if branch:
+        args.extend(["origin", branch])
+    _run_git_command(repo_path, *args)
+
+
+def merge(
+    repo_path: str,
+    source_branch: str,
+    target_branch: str | None = None,
+    message: str | None = None,
+) -> str:
+    """Merge a branch into the current branch.
+
+    Args:
+        repo_path: Path to the git repository
+        source_branch: Branch to merge from
+        target_branch: Branch to merge into (default: current branch)
+        message: Merge commit message
+
+    Returns:
+        Merge commit hash
+
+    Raises:
+        RuntimeError: If merge fails (including conflicts)
+    """
+    # Checkout target branch if specified
+    if target_branch:
+        checkout_branch(repo_path, target_branch)
+
+    # Merge
+    args = ["merge", source_branch]
+    if message:
+        args.extend(["-m", message])
+
+    _run_git_command(repo_path, *args)
+
+    # Return merge commit hash
+    return _run_git_command(repo_path, "rev-parse", "HEAD").strip()
+
+
+def get_current_branch(repo_path: str) -> str:
+    """Get the current branch name.
+
+    Args:
+        repo_path: Path to the git repository
+
+    Returns:
+        Current branch name
+    """
+    try:
+        branch = _run_git_command(repo_path, "rev-parse", "--abbrev-ref", "HEAD").strip()
+        if branch != "HEAD":
+            return branch
+    except RuntimeError:
+        pass
+
+    return _run_git_command(repo_path, "symbolic-ref", "--short", "HEAD").strip()

apps/api/src/utils/git_files.py

@@ -1,5 +1,6 @@
 """Git file utilities for browsing repository contents."""
 
+import logging
 import subprocess
 from dataclasses import dataclass
 from pathlib import Path
@@ -50,10 +51,31 @@ def _run_git_command(repo_path: str, *args: str) -> str:
         text=True,
     )
     if result.returncode != 0:
-        raise RuntimeError(f"Git command failed: {result.stderr}")
+        stderr = result.stderr
+        # Handle "dubious ownership" security error
+        if "dubious ownership" in stderr.lower():
+            logger.warning("Git ownership mismatch for %s, adding to safe.directory", repo_path)
+            # Add this directory to git's safe.directory list
+            subprocess.run(
+                ["git", "config", "--global", "--add", "safe.directory", repo_path],
+                capture_output=True,
+            )
+            # Retry the command
+            result = subprocess.run(
+                ["git", *args],
+                cwd=repo_path,
+                capture_output=True,
+                text=True,
+            )
+            if result.returncode == 0:
+                return result.stdout
+            stderr = result.stderr
+        raise RuntimeError(f"Git command failed: {stderr}")
     return result.stdout
 
 
+logger = logging.getLogger(__name__)
+
 def list_tree(repo_path: str, branch: str = "main", path: str = "") -> list[FileTreeEntry]:
     """List files and directories in a repository path.
 
@@ -69,10 +91,20 @@ def list_tree(repo_path: str, branch: str = "main", path: str = "") -> list[File
 
     try:
         output = _run_git_command(repo_path, "ls-tree", "-l", tree_path)
-    except RuntimeError:
+    except RuntimeError as e:
+        logger.warning("git ls-tree failed for %s with branch '%s': %s", repo_path, tree_path, str(e))
         # Try with HEAD if branch doesn't exist
         tree_path = f"HEAD:{path}" if path else "HEAD"
+        try:
             output = _run_git_command(repo_path, "ls-tree", "-l", tree_path)
+        except RuntimeError as e:
+            logger.error("git ls-tree failed for %s with HEAD: %s", repo_path, str(e))
+            # Check if this is an empty repository (no commits yet)
+            error_msg = str(e).lower()
+            if "not a valid object name" in error_msg or "does not exist" in error_msg:
+                # Empty repository - return empty list
+                return []
+            raise
 
     entries = []
     for line in output.strip().split("\n"):
@@ -190,18 +222,17 @@ def get_file_content(repo_path: str, branch: str, path: str) -> FileContent:
 
 
 def _is_binary_file(repo_path: str, branch: str, path: str) -> bool:
-    """Check if a file is binary."""
+    """Check if a file is binary using raw bytes to avoid encoding issues."""
     try:
-        _run_git_command(
-            repo_path,
-            "diff",
-            "--numstat",
-            "--",
-            path,
+        result = subprocess.run(
+            ["git", "show", f"{branch}:{path}"],
+            cwd=repo_path,
+            capture_output=True,
         )
-        # Alternative: use git show and check for null bytes
-        content = _run_git_command(repo_path, "show", f"{branch}:{path}")
-        return b"\x00" in content.encode("utf-8", errors="replace")
+        if result.returncode != 0:
+            raise RuntimeError(f"Git command failed: {result.stderr.decode()}")
+        # A file is binary if it contains null bytes
+        return b"\x00" in result.stdout
     except RuntimeError:
         return True
 
@@ -249,7 +280,11 @@ def list_branches(repo_path: str) -> tuple[list[BranchInfo], str]:
         Tuple of (list of BranchInfo, default branch name)
     """
     # Get all branches
+    try:
         output = _run_git_command(repo_path, "branch", "-a", "--format=%(refname:short)")
+    except RuntimeError as e:
+        logger.error("Failed to list branches for %s: %s", repo_path, str(e))
+        raise
 
     branches: list[BranchInfo] = []
     default_branch = "main"
@@ -310,6 +345,19 @@ def list_branches(repo_path: str) -> tuple[list[BranchInfo], str]:
                     )
                 )
                 default_branch = branch_name
+        except RuntimeError:
+            try:
+                output = _run_git_command(repo_path, "symbolic-ref", "--short", "HEAD")
+                branch_name = output.strip()
+                if branch_name:
+                    branches.append(
+                        BranchInfo(
+                            name=branch_name,
+                            is_default=True,
+                            last_commit=None,
+                        )
+                    )
+                    default_branch = branch_name
             except RuntimeError:
                 pass
 

apps/api/tests/conftest.py

@@ -3,6 +3,7 @@
 import asyncio
 import os
 from typing import AsyncGenerator, Generator
+from unittest.mock import patch
 
 import pytest
 import pytest_asyncio
@@ -11,82 +12,142 @@ from sqlalchemy import create_engine, text
 from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
 from sqlalchemy.orm import sessionmaker
 
+# Set test environment BEFORE importing app modules
+os.environ["APP_ENV"] = "testing"
+os.environ["SECRET_KEY"] = "test-secret-key-for-testing-only-do-not-use-in-production"
+os.environ["DATABASE_URL"] = "sqlite+aiosqlite:///:memory:"
+
 from src.config import Settings, build_database_url
 from src.models.base import Base
 from src.main import app
-
-
-# Unit test fixtures (SQLite in-memory)
-
-@pytest.fixture(scope="session")
-def sqlite_engine():
-    """Create a SQLite in-memory engine for unit tests."""
-    engine = create_engine("sqlite:///:memory:", connect_args={"check_same_thread": False})
-    Base.metadata.create_all(engine)
-    yield engine
-    engine.dispose()
-
-
-@pytest.fixture
-def sqlite_session(sqlite_engine) -> Generator:
-    """Provide a SQLite session for unit tests."""
-    connection = sqlite_engine.connect()
-    transaction = connection.begin()
-    session = sessionmaker(bind=connection)()
-    
-    yield session
-    
-    session.close()
-    transaction.rollback()
-    connection.close()
-
-
-# Integration test fixtures (PostgreSQL)
-
-TEST_DATABASE_URL = build_database_url(
-    user="headquarter",
-    password="headquarter",
-    host="localhost",
-    port=5432,
-    database="headquarter",
-)
-
-
-@pytest_asyncio.fixture(scope="session")
-async def postgres_engine():
-    """Create a PostgreSQL engine for integration tests."""
-    engine = create_async_engine(TEST_DATABASE_URL)
-    async with engine.begin() as conn:
-        await conn.run_sync(Base.metadata.create_all)
-    yield engine
-    await engine.dispose()
-
-
-@pytest_asyncio.fixture
-async def db_session(postgres_engine) -> AsyncGenerator[AsyncSession, None]:
-    """Provide a database session with transaction rollback."""
-    async with postgres_engine.connect() as connection:
-        transaction = await connection.begin_nested()
-        session_factory = async_sessionmaker(
-            connection, expire_on_commit=False, class_=AsyncSession
-        )
-        session = session_factory()
-        
-        yield session
-        
-        await session.close()
-        await transaction.rollback()
+from src.auth.dependencies import get_db_session
 
 
 @pytest.fixture
 def test_client() -> Generator[TestClient, None, None]:
-    """Provide a FastAPI test client."""
+    """Provide a FastAPI test client with SQLite database."""
+    # Create a single engine for this test
+    engine = create_async_engine(
+        "sqlite+aiosqlite:///:memory:",
+        connect_args={"check_same_thread": False},
+    )
+    
+    # Create tables
+    async def init_db():
+        async with engine.begin() as conn:
+            await conn.run_sync(Base.metadata.create_all)
+    
+    asyncio.run(init_db())
+    
+    async def override_get_db_session() -> AsyncGenerator[AsyncSession, None]:
+        async with async_sessionmaker(engine, expire_on_commit=False)() as session:
+            yield session
+
+    # Override the dependency
+    app.dependency_overrides[get_db_session] = override_get_db_session
+    
+    # Patch startup events to prevent PostgreSQL connection attempts
+    with patch("src.main.init_database") as mock_init, \
+         patch("src.main.seed_builtin_tool_types") as mock_seed:
+        mock_init.return_value = True
+        mock_seed.return_value = None
+        
+        try:
             with TestClient(app) as client:
                 yield client
+        finally:
+            # Clean up overrides
+            app.dependency_overrides.pop(get_db_session, None)
+            asyncio.run(engine.dispose())
 
 
-@pytest.fixture(autouse=True)
-def configure_test_env(monkeypatch):
-    """Configure environment for testing."""
-    monkeypatch.setenv("DATABASE_URL", TEST_DATABASE_URL)
-    monkeypatch.setenv("APP_ENV", "testing")
+@pytest.fixture
+def authenticated_client(test_client) -> Generator[TestClient, None, None]:
+    """Provide an authenticated test client with a test user."""
+    import uuid
+    from src.auth.session import create_session_cookie
+    from src.models.user import User
+    
+    user_id = str(uuid.uuid4())
+    settings = Settings()
+    
+    # Create user in database using the same engine as test_client
+    # We need to access the engine from the test_client fixture
+    # Since we can't easily do that, we'll create the user via API call
+    # But we need the user to exist before any API calls
+    # So we need to create the user using the overridden dependency
+    
+    async def create_test_user():
+        # Get the override function
+        override_fn = app.dependency_overrides.get(get_db_session)
+        if override_fn:
+            gen = override_fn()
+            session = await gen.asend(None)
+            try:
+                user = User(
+                    id=uuid.UUID(user_id),
+                    email="test@headquarter.local",
+                    name="Test User",
+                    authentik_id=f"authentik-{user_id}",
+                    avatar_url=None,
+                )
+                session.add(user)
+                await session.commit()
+            finally:
+                await gen.aclose()
+    
+    asyncio.run(create_test_user())
+    
+    # Create session cookie
+    session_cookie = create_session_cookie(
+        settings=settings,
+        user_id=user_id,
+    )
+    
+    # Set cookie on client
+    test_client.cookies.set("session", session_cookie)
+    
+    yield test_client
+
+
+@pytest.fixture
+def admin_client(test_client) -> Generator[TestClient, None, None]:
+    """Provide an authenticated test client with an admin user."""
+    import uuid
+    from src.auth.session import create_session_cookie
+    from src.models.user import User
+    
+    user_id = str(uuid.uuid4())
+    settings = Settings()
+    
+    async def create_admin_user():
+        override_fn = app.dependency_overrides.get(get_db_session)
+        if override_fn:
+            gen = override_fn()
+            session = await gen.asend(None)
+            try:
+                user = User(
+                    id=uuid.UUID(user_id),
+                    email="admin@headquarter.local",
+                    name="Admin User",
+                    authentik_id=f"authentik-admin-{user_id}",
+                    avatar_url=None,
+                    is_admin=True,
+                )
+                session.add(user)
+                await session.commit()
+            finally:
+                await gen.aclose()
+    
+    asyncio.run(create_admin_user())
+    
+    # Create session cookie
+    session_cookie = create_session_cookie(
+        settings=settings,
+        user_id=user_id,
+    )
+    
+    # Set cookie on client
+    test_client.cookies.set("session", session_cookie)
+    
+    yield test_client

apps/api/tests/integration/test_config_folders_api.py

@@ -0,0 +1,255 @@
+import uuid
+import pytest
+from fastapi.testclient import TestClient
+
+
+@pytest.mark.integration
+class TestConfigFoldersAPI:
+    """Integration tests for config folders API."""
+
+    def test_list_config_folders_requires_authentication(self, test_client: TestClient) -> None:
+        """Test that listing config folders requires authentication."""
+        response = test_client.get("/config-folders")
+        assert response.status_code == 401
+
+    def test_list_config_folders_returns_user_folders(self, authenticated_client: TestClient) -> None:
+        """Test that authenticated users can list their folders."""
+        response = authenticated_client.get("/config-folders")
+        assert response.status_code == 200
+        data = response.json()
+        assert isinstance(data, dict)
+        assert "folders" in data
+        assert isinstance(data["folders"], list)
+
+    def test_create_config_folder_successfully(self, authenticated_client: TestClient) -> None:
+        """Test creating a config folder."""
+        response = authenticated_client.post(
+            "/config-folders",
+            json={
+                "name": "test-folder",
+                "description": "Test folder",
+                "mount_path": "/home/user",
+                "files": {"test.txt": "hello world"},
+            },
+        )
+        assert response.status_code == 201
+        data = response.json()
+        assert data["name"] == "test-folder"
+        assert data["mount_path"] == "/home/user"
+        assert data["files"] == {"test.txt": "hello world"}
+
+    def test_create_config_folder_duplicate_name(self, authenticated_client: TestClient) -> None:
+        """Test that duplicate folder names are rejected."""
+        # Create first folder
+        response = authenticated_client.post(
+            "/config-folders",
+            json={
+                "name": "duplicate-folder",
+                "mount_path": "/home/user",
+                "files": {},
+            },
+        )
+        assert response.status_code == 201
+
+        # Try to create second with same name
+        response = authenticated_client.post(
+            "/config-folders",
+            json={
+                "name": "duplicate-folder",
+                "mount_path": "/home/user",
+                "files": {},
+            },
+        )
+        assert response.status_code == 409
+
+    def test_create_config_folder_exceeds_size_limit(self, authenticated_client: TestClient) -> None:
+        """Test that folders exceeding 10MB are rejected."""
+        large_content = "x" * (11 * 1024 * 1024)  # 11MB
+        response = authenticated_client.post(
+            "/config-folders",
+            json={
+                "name": "large-folder",
+                "mount_path": "/home/user",
+                "files": {"large.txt": large_content},
+            },
+        )
+        assert response.status_code == 422
+
+    def test_create_config_folder_path_traversal_attack(self, authenticated_client: TestClient) -> None:
+        """Test that path traversal in file paths is prevented."""
+        response = authenticated_client.post(
+            "/config-folders",
+            json={
+                "name": "bad-folder",
+                "mount_path": "/home/user",
+                "files": {"../../../etc/passwd": "malicious"},
+            },
+        )
+        assert response.status_code == 422
+
+    def test_get_config_folder_by_id(self, authenticated_client: TestClient) -> None:
+        """Test getting a config folder by ID."""
+        # Create folder first
+        create_response = authenticated_client.post(
+            "/config-folders",
+            json={
+                "name": "get-test",
+                "mount_path": "/home/user",
+                "files": {},
+            },
+        )
+        folder_id = create_response.json()["id"]
+
+        # Get it back
+        response = authenticated_client.get(f"/config-folders/{folder_id}")
+        assert response.status_code == 200
+        data = response.json()
+        assert data["name"] == "get-test"
+
+    def test_get_config_folder_not_found(self, authenticated_client: TestClient) -> None:
+        """Test getting a non-existent folder."""
+        response = authenticated_client.get(f"/config-folders/{uuid.uuid4()}")
+        assert response.status_code == 404
+
+    def test_update_config_folder_successfully(self, authenticated_client: TestClient) -> None:
+        """Test updating a config folder."""
+        # Create folder first
+        create_response = authenticated_client.post(
+            "/config-folders",
+            json={
+                "name": "update-test",
+                "mount_path": "/home/user",
+                "files": {},
+            },
+        )
+        folder_id = create_response.json()["id"]
+
+        # Update it
+        response = authenticated_client.put(
+            f"/config-folders/{folder_id}",
+            json={
+                "name": "updated-name",
+                "mount_path": "/workspace",
+                "files": {"new.txt": "content"},
+            },
+        )
+        assert response.status_code == 200
+        data = response.json()
+        assert data["name"] == "updated-name"
+        assert data["mount_path"] == "/workspace"
+
+    def test_delete_config_folder_successfully(self, authenticated_client: TestClient) -> None:
+        """Test deleting a config folder."""
+        # Create folder first
+        create_response = authenticated_client.post(
+            "/config-folders",
+            json={
+                "name": "delete-test",
+                "mount_path": "/home/user",
+                "files": {},
+            },
+        )
+        folder_id = create_response.json()["id"]
+
+        # Delete it
+        response = authenticated_client.delete(f"/config-folders/{folder_id}")
+        assert response.status_code == 204
+
+        # Verify it's gone
+        get_response = authenticated_client.get(f"/config-folders/{folder_id}")
+        assert get_response.status_code == 404
+
+    def test_add_project_override_successfully(self, authenticated_client: TestClient) -> None:
+        """Test adding a project override."""
+        # Create folder first
+        create_response = authenticated_client.post(
+            "/config-folders",
+            json={
+                "name": "override-test",
+                "mount_path": "/home/user",
+                "files": {"global.txt": "global"},
+            },
+        )
+        folder_id = create_response.json()["id"]
+        project_id = str(uuid.uuid4())
+
+        # Add override
+        response = authenticated_client.post(
+            f"/config-folders/{folder_id}/overrides",
+            json={
+                "project_id": project_id,
+                "mount_path": "/workspace",
+                "files": {"project.txt": "project"},
+            },
+        )
+        assert response.status_code == 200
+        data = response.json()
+        assert project_id in data["project_overrides"]
+
+    def test_update_project_override_successfully(self, authenticated_client: TestClient) -> None:
+        """Test updating a project override."""
+        # Create folder with override
+        create_response = authenticated_client.post(
+            "/config-folders",
+            json={
+                "name": "update-override-test",
+                "mount_path": "/home/user",
+                "files": {},
+            },
+        )
+        folder_id = create_response.json()["id"]
+        project_id = str(uuid.uuid4())
+
+        # Add override
+        authenticated_client.post(
+            f"/config-folders/{folder_id}/overrides",
+            json={
+                "project_id": project_id,
+                "mount_path": "/workspace",
+                "files": {"old.txt": "old"},
+            },
+        )
+
+        # Update override
+        response = authenticated_client.put(
+            f"/config-folders/{folder_id}/overrides/{project_id}",
+            json={
+                "mount_path": "/app",
+                "files": {"new.txt": "new"},
+            },
+        )
+        assert response.status_code == 200
+        data = response.json()
+        assert data["project_overrides"][project_id]["mount_path"] == "/app"
+
+    def test_delete_project_override_successfully(self, authenticated_client: TestClient) -> None:
+        """Test deleting a project override."""
+        # Create folder with override
+        create_response = authenticated_client.post(
+            "/config-folders",
+            json={
+                "name": "delete-override-test",
+                "mount_path": "/home/user",
+                "files": {},
+            },
+        )
+        folder_id = create_response.json()["id"]
+        project_id = str(uuid.uuid4())
+
+        # Add override
+        authenticated_client.post(
+            f"/config-folders/{folder_id}/overrides",
+            json={
+                "project_id": project_id,
+                "mount_path": "/workspace",
+                "files": {},
+            },
+        )
+
+        # Delete override
+        response = authenticated_client.delete(
+            f"/config-folders/{folder_id}/overrides/{project_id}"
+        )
+        assert response.status_code == 200
+        data = response.json()
+        assert project_id not in data["project_overrides"]

apps/api/tests/integration/test_git_control.py

@@ -0,0 +1,164 @@
+"""Tests for git control utilities."""
+
+import os
+import tempfile
+
+import pytest
+
+from src.utils.git_control import (
+    GitStatus,
+    checkout_branch,
+    commit_changes,
+    create_branch,
+    delete_branch,
+    get_current_branch,
+    get_status,
+)
+
+
+@pytest.fixture
+def temp_repo():
+    """Create a temporary git repository."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        # Initialize git repo
+        os.system(f"cd {tmpdir} && git init && git config user.email 'test@test.com' && git config user.name 'Test User'")
+        
+        # Create initial commit
+        with open(os.path.join(tmpdir, "README.md"), "w") as f:
+            f.write("# Test Repo\n")
+        os.system(f"cd {tmpdir} && git add README.md && git commit -m 'Initial commit'")
+        
+        yield tmpdir
+
+
+class TestGitStatus:
+    """Tests for get_status function."""
+
+    def test_clean_repo(self, temp_repo):
+        """Test status of a clean repository."""
+        status = get_status(temp_repo)
+        assert isinstance(status, GitStatus)
+        assert status.branch in ["main", "master"]
+        assert len(status.modified) == 0
+        assert len(status.added) == 0
+        assert len(status.deleted) == 0
+        assert len(status.untracked) == 0
+
+    def test_modified_file(self, temp_repo):
+        """Test detecting modified files."""
+        # Modify a file
+        with open(os.path.join(temp_repo, "README.md"), "w") as f:
+            f.write("# Modified\n")
+        
+        status = get_status(temp_repo)
+        assert "README.md" in status.modified
+
+    def test_untracked_file(self, temp_repo):
+        """Test detecting untracked files."""
+        # Create new file
+        with open(os.path.join(temp_repo, "new.py"), "w") as f:
+            f.write("print('hello')\n")
+        
+        status = get_status(temp_repo)
+        assert "new.py" in status.untracked
+
+
+def test_get_current_branch_handles_unborn_main() -> None:
+    with tempfile.TemporaryDirectory() as tmpdir:
+        os.system(f"git init -b main {tmpdir} >/dev/null 2>&1")
+
+        assert get_current_branch(tmpdir) == "main"
+
+
+def test_create_branch_on_bare_repo_with_no_commits() -> None:
+    with tempfile.TemporaryDirectory() as tmpdir:
+        os.system(f"git init --bare {tmpdir}/bare.git >/dev/null 2>&1")
+        create_branch(f"{tmpdir}/bare.git", "main")
+        assert get_current_branch(f"{tmpdir}/bare.git") == "main"
+
+
+def test_checkout_branch_on_bare_repo_with_no_commits() -> None:
+    with tempfile.TemporaryDirectory() as tmpdir:
+        os.system(f"git init --bare {tmpdir}/bare.git >/dev/null 2>&1")
+        checkout_branch(f"{tmpdir}/bare.git", "main")
+        assert get_current_branch(f"{tmpdir}/bare.git") == "main"
+
+
+class TestBranchOperations:
+    """Tests for branch management functions."""
+
+    def test_create_branch(self, temp_repo):
+        """Test creating a new branch."""
+        # Get the actual default branch name
+        default_branch = get_current_branch(temp_repo)
+        create_branch(temp_repo, "feature/test", default_branch)
+        
+        # Check branch exists
+        branches = get_status(temp_repo)
+        # Branch should still be on default
+        assert branches.branch == default_branch
+
+    def test_checkout_branch(self, temp_repo):
+        """Test checking out a branch."""
+        default_branch = get_current_branch(temp_repo)
+        create_branch(temp_repo, "feature/test", default_branch)
+        checkout_branch(temp_repo, "feature/test")
+        
+        current = get_current_branch(temp_repo)
+        assert current == "feature/test"
+
+    def test_delete_branch(self, temp_repo):
+        """Test deleting a branch."""
+        default_branch = get_current_branch(temp_repo)
+        create_branch(temp_repo, "feature/delete", default_branch)
+        delete_branch(temp_repo, "feature/delete")
+        
+        # Should be back on default
+        current = get_current_branch(temp_repo)
+        assert current == default_branch
+
+    def test_get_current_branch(self, temp_repo):
+        """Test getting current branch."""
+        branch = get_current_branch(temp_repo)
+        assert branch in ["main", "master"]
+
+
+class TestCommit:
+    """Tests for commit function."""
+
+    def test_commit_changes(self, temp_repo):
+        """Test committing changes."""
+        # Modify file
+        with open(os.path.join(temp_repo, "README.md"), "w") as f:
+            f.write("# Updated\n")
+        
+        # Commit
+        commit_changes(
+            temp_repo,
+            "Update README",
+            "Test User",
+            "test@test.com",
+            ["README.md"]
+        )
+        
+        # Check status is clean
+        status = get_status(temp_repo)
+        assert "README.md" not in status.modified
+
+    def test_commit_all_changes(self, temp_repo):
+        """Test committing all changes."""
+        # Modify file
+        with open(os.path.join(temp_repo, "README.md"), "w") as f:
+            f.write("# All updated\n")
+        
+        # Commit all
+        commit_changes(
+            temp_repo,
+            "Update all",
+            "Test User",
+            "test@test.com"
+        )
+        
+        # Check status is clean
+        status = get_status(temp_repo)
+        assert len(status.modified) == 0

apps/api/tests/integration/test_models.py

@@ -5,7 +5,6 @@ from src.models import Base
 from src.models.base import TimestampMixin, UUIDPrimaryKeyMixin
 from src.models.git_repository import GitRepository
 from src.models.project import Project
-from src.models.refresh_token import RefreshToken
 from src.models.ssh_key import SSHKey
 from src.models.user import User
 from src.models.user_config import UserConfig

apps/api/tests/integration/test_projects_api.py

@@ -6,7 +6,7 @@ import pytest
 from sqlalchemy import text
 from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker
 
-from src.auth.jwt_service import mint_access_token
+from src.auth.session import create_session_cookie
 from src.config import Settings, build_database_url
 from src.models import Base
 from src.models.project import Project
@@ -53,7 +53,7 @@ def _load_app():
 
 def _mint_token(user_id: str) -> str:
     settings = Settings()
-    return mint_access_token(
+    return create_session_cookie(
         settings=settings,
         subject=user_id,
         email="test@headquarter.local",

apps/api/tests/integration/test_tool_configs_api_extended.py

@@ -0,0 +1,256 @@
+import uuid
+import pytest
+from fastapi.testclient import TestClient
+
+
+@pytest.mark.integration
+class TestToolConfigsAPIExtended:
+    """Integration tests for tool configs API with new fields."""
+
+    def test_create_tool_config_with_new_fields(self, authenticated_client: TestClient) -> None:
+        """Test creating a tool config with all new fields."""
+        # Create a tool type first
+        tool_response = authenticated_client.post(
+            "/tool-types",
+            json={
+                "name": "config-test-tool",
+                "display_name": "Config Test Tool",
+                "default_port": 8080,
+                "definition_type": "compose",
+                "compose_template": "version: '3.8'\nservices:\n  app:\n    image: nginx",
+                "required_variables": [],
+            },
+        )
+        tool_id = tool_response.json()["id"]
+
+        # Create config with new fields
+        response = authenticated_client.post(
+            "/tool-configs",
+            json={
+                "tool_type_id": tool_id,
+                "key": "ADVANCED_CONFIG",
+                "value": "test-value",
+                "config_type": "env",
+                "port_override": 9090,
+                "start_command": "python app.py",
+                "working_directory": "/app",
+                "environment_variables": {"DEBUG": "true", "LOG_LEVEL": "debug"},
+                "volumes": [
+                    {"source": "data", "target": "/data", "type": "bind"}
+                ],
+            },
+        )
+        assert response.status_code == 201
+        data = response.json()
+        assert data["key"] == "ADVANCED_CONFIG"
+        assert data["port_override"] == 9090
+        assert data["start_command"] == "python app.py"
+        assert data["working_directory"] == "/app"
+        assert data["environment_variables"] == {"DEBUG": "true", "LOG_LEVEL": "debug"}
+        assert data["volumes"] == [{"source": "data", "target": "/data", "type": "bind"}]
+
+    def test_create_tool_config_invalid_port(self, authenticated_client: TestClient) -> None:
+        """Test that invalid port numbers are rejected."""
+        # Create a tool type first
+        tool_response = authenticated_client.post(
+            "/tool-types",
+            json={
+                "name": "port-test-tool",
+                "display_name": "Port Test Tool",
+                "default_port": 8080,
+                "definition_type": "compose",
+                "compose_template": "version: '3.8'\nservices:\n  app:\n    image: nginx",
+                "required_variables": [],
+            },
+        )
+        tool_id = tool_response.json()["id"]
+
+        # Try to create config with invalid port
+        response = authenticated_client.post(
+            "/tool-configs",
+            json={
+                "tool_type_id": tool_id,
+                "key": "BAD_PORT",
+                "value": "test",
+                "config_type": "env",
+                "port_override": 99999,
+            },
+        )
+        assert response.status_code == 422
+
+    def test_create_tool_config_invalid_volume_structure(self, authenticated_client: TestClient) -> None:
+        """Test that invalid volume structures are rejected."""
+        # Create a tool type first
+        tool_response = authenticated_client.post(
+            "/tool-types",
+            json={
+                "name": "volume-test-tool",
+                "display_name": "Volume Test Tool",
+                "default_port": 8080,
+                "definition_type": "compose",
+                "compose_template": "version: '3.8'\nservices:\n  app:\n    image: nginx",
+                "required_variables": [],
+            },
+        )
+        tool_id = tool_response.json()["id"]
+
+        # Try to create config with invalid volume
+        response = authenticated_client.post(
+            "/tool-configs",
+            json={
+                "tool_type_id": tool_id,
+                "key": "BAD_VOLUME",
+                "value": "test",
+                "config_type": "env",
+                "volumes": [{"invalid": "structure"}],
+            },
+        )
+        assert response.status_code == 422
+
+    def test_update_tool_config_with_new_fields(self, authenticated_client: TestClient) -> None:
+        """Test updating a tool config with new fields."""
+        # Create a tool type first
+        tool_response = authenticated_client.post(
+            "/tool-types",
+            json={
+                "name": "update-config-tool",
+                "display_name": "Update Config Tool",
+                "default_port": 8080,
+                "definition_type": "compose",
+                "compose_template": "version: '3.8'\nservices:\n  app:\n    image: nginx",
+                "required_variables": [],
+            },
+        )
+        tool_id = tool_response.json()["id"]
+
+        # Create config
+        create_response = authenticated_client.post(
+            "/tool-configs",
+            json={
+                "tool_type_id": tool_id,
+                "key": "UPDATE_TEST",
+                "value": "original",
+                "config_type": "env",
+            },
+        )
+        config_id = create_response.json()["id"]
+
+        # Update with new fields
+        response = authenticated_client.put(
+            f"/tool-configs/{config_id}",
+            json={
+                "value": "updated",
+                "port_override": 3000,
+                "start_command": "npm start",
+                "working_directory": "/workspace",
+                "environment_variables": {"NODE_ENV": "production"},
+                "volumes": [{"source": "src", "target": "/app/src", "type": "bind"}],
+            },
+        )
+        assert response.status_code == 200
+        data = response.json()
+        assert data["value"] == "updated"
+        assert data["port_override"] == 3000
+        assert data["start_command"] == "npm start"
+        assert data["working_directory"] == "/workspace"
+        assert data["environment_variables"] == {"NODE_ENV": "production"}
+
+    def test_list_tool_configs_returns_new_fields(self, authenticated_client: TestClient) -> None:
+        """Test that listing configs returns new fields."""
+        # Create a tool type first
+        tool_response = authenticated_client.post(
+            "/tool-types",
+            json={
+                "name": "list-config-tool",
+                "display_name": "List Config Tool",
+                "default_port": 8080,
+                "definition_type": "compose",
+                "compose_template": "version: '3.8'\nservices:\n  app:\n    image: nginx",
+                "required_variables": [],
+            },
+        )
+        tool_id = tool_response.json()["id"]
+
+        # Create config with new fields
+        authenticated_client.post(
+            "/tool-configs",
+            json={
+                "tool_type_id": tool_id,
+                "key": "LIST_TEST",
+                "value": "test",
+                "config_type": "env",
+                "port_override": 5000,
+                "environment_variables": {"TEST": "true"},
+            },
+        )
+
+        # List configs
+        response = authenticated_client.get("/tool-configs")
+        assert response.status_code == 200
+        data = response.json()
+        assert len(data) > 0
+        config = data[0]
+        assert "port_override" in config
+        assert "start_command" in config
+        assert "working_directory" in config
+        assert "environment_variables" in config
+        assert "volumes" in config
+
+    def test_get_tool_config_defaults(self, authenticated_client: TestClient) -> None:
+        """Test getting tool config defaults."""
+        # Create a tool type first
+        tool_response = authenticated_client.post(
+            "/tool-types",
+            json={
+                "name": "defaults-tool",
+                "display_name": "Defaults Tool",
+                "default_port": 8080,
+                "definition_type": "compose",
+                "compose_template": "version: '3.8'\nservices:\n  app:\n    image: nginx\n    volumes:\n      - \"{{REPO_PATH}}:/workspace\"\n",
+                "required_variables": ["REPO_PATH"],
+            },
+        )
+        tool_id = tool_response.json()["id"]
+
+        # Get defaults
+        response = authenticated_client.get(f"/tool-configs/defaults/{tool_id}")
+        assert response.status_code == 200
+        data = response.json()
+        assert data["tool_type_id"] == tool_id
+        assert "suggested_configs" in data
+
+    def test_tool_config_backward_compatibility(self, authenticated_client: TestClient) -> None:
+        """Test that old configs without new fields still work."""
+        # Create a tool type first
+        tool_response = authenticated_client.post(
+            "/tool-types",
+            json={
+                "name": "backward-compat-tool",
+                "display_name": "Backward Compat Tool",
+                "default_port": 8080,
+                "definition_type": "compose",
+                "compose_template": "version: '3.8'\nservices:\n  app:\n    image: nginx",
+                "required_variables": [],
+            },
+        )
+        tool_id = tool_response.json()["id"]
+
+        # Create config without new fields (simulating old client)
+        response = authenticated_client.post(
+            "/tool-configs",
+            json={
+                "tool_type_id": tool_id,
+                "key": "OLD_STYLE",
+                "value": "value",
+                "config_type": "env",
+            },
+        )
+        assert response.status_code == 201
+        data = response.json()
+        assert data["key"] == "OLD_STYLE"
+        # New fields should have default values
+        assert data["port_override"] is None
+        assert data["start_command"] is None
+        assert data["working_directory"] is None
+        assert data["environment_variables"] is None
+        assert data["volumes"] is None

apps/api/tests/integration/test_tool_types_api.py

@@ -7,7 +7,7 @@ from fastapi.testclient import TestClient
 from sqlalchemy import text
 from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker
 
-from src.auth.jwt_service import mint_access_token
+from src.auth.session import create_session_cookie
 from src.config import Settings, build_database_url
 from src.models import Base
 from src.models.tool_type import ToolType
@@ -54,7 +54,7 @@ def _load_app():
 
 def _mint_token(user_id: str) -> str:
     settings = Settings()
-    return mint_access_token(
+    return create_session_cookie(
         settings=settings,
         subject=user_id,
         email="test@headquarter.local",

apps/api/tests/integration/test_tool_types_api_extended.py

@@ -0,0 +1,188 @@
+import uuid
+import pytest
+from fastapi.testclient import TestClient
+
+
+@pytest.mark.integration
+class TestToolTypesAPIExtended:
+    """Integration tests for tool types API with new fields."""
+
+    def test_create_tool_type_with_dockerfile(self, authenticated_client: TestClient) -> None:
+        """Test creating a tool type with dockerfile definition."""
+        response = authenticated_client.post(
+            "/tool-types",
+            json={
+                "name": "dockerfile-tool",
+                "display_name": "Dockerfile Tool",
+                "category": "utility",
+                "interfaces": ["terminal"],
+                "default_port": 8080,
+                "definition_type": "dockerfile",
+                "dockerfile_template": "FROM python:3.11\nRUN pip install flask",
+                "required_variables": [],
+            },
+        )
+        assert response.status_code == 201
+        data = response.json()
+        assert data["name"] == "dockerfile-tool"
+        assert data["definition_type"] == "dockerfile"
+        assert data["dockerfile_template"] == "FROM python:3.11\nRUN pip install flask"
+
+    def test_create_tool_type_with_readiness_probe(self, authenticated_client: TestClient) -> None:
+        """Test creating a tool type with readiness probe."""
+        response = authenticated_client.post(
+            "/tool-types",
+            json={
+                "name": "probed-tool",
+                "display_name": "Probed Tool",
+                "category": "utility",
+                "interfaces": ["web"],
+                "default_port": 8080,
+                "definition_type": "compose",
+                "compose_template": "version: '3.8'\nservices:\n  app:\n    image: nginx",
+                "readiness_probe": {
+                    "command": "curl -f http://localhost:8080",
+                    "timeout": 30,
+                    "interval": 2,
+                },
+                "required_variables": [],
+            },
+        )
+        assert response.status_code == 201
+        data = response.json()
+        assert data["readiness_probe"]["command"] == "curl -f http://localhost:8080"
+        assert data["readiness_probe"]["timeout"] == 30
+
+    def test_create_tool_type_invalid_definition_type(self, authenticated_client: TestClient) -> None:
+        """Test that invalid definition types are rejected."""
+        response = authenticated_client.post(
+            "/tool-types",
+            json={
+                "name": "invalid-tool",
+                "display_name": "Invalid Tool",
+                "default_port": 8080,
+                "definition_type": "invalid",
+                "compose_template": "version: '3.8'\nservices:\n  app:\n    image: nginx",
+                "required_variables": [],
+            },
+        )
+        assert response.status_code == 422
+
+    def test_create_tool_type_dockerfile_without_template(self, authenticated_client: TestClient) -> None:
+        """Test that dockerfile type requires dockerfile_template."""
+        response = authenticated_client.post(
+            "/tool-types",
+            json={
+                "name": "no-dockerfile",
+                "display_name": "No Dockerfile",
+                "default_port": 8080,
+                "definition_type": "dockerfile",
+                "required_variables": [],
+            },
+        )
+        assert response.status_code == 422
+
+    def test_update_tool_type_with_new_fields(self, authenticated_client: TestClient) -> None:
+        """Test updating a tool type with new fields."""
+        # Create tool type first
+        create_response = authenticated_client.post(
+            "/tool-types",
+            json={
+                "name": "update-test-tool",
+                "display_name": "Update Test Tool",
+                "default_port": 8080,
+                "definition_type": "compose",
+                "compose_template": "version: '3.8'\nservices:\n  app:\n    image: nginx",
+                "required_variables": [],
+            },
+        )
+        tool_id = create_response.json()["id"]
+
+        # Update it
+        response = authenticated_client.put(
+            f"/tool-types/{tool_id}",
+            json={
+                "display_name": "Updated Name",
+                "readiness_probe": {
+                    "command": "curl -f http://localhost:8080/health",
+                    "timeout": 60,
+                    "interval": 5,
+                },
+            },
+        )
+        assert response.status_code == 200
+        data = response.json()
+        assert data["display_name"] == "Updated Name"
+        assert data["readiness_probe"]["command"] == "curl -f http://localhost:8080/health"
+
+    def test_validate_tool_type_compose(self, authenticated_client: TestClient) -> None:
+        """Test validating compose template."""
+        response = authenticated_client.post(
+            "/tool-types/validate",
+            json={
+                "definition_type": "compose",
+                "compose_template": "version: '3.8'\nservices:\n  app:\n    image: nginx",
+            },
+        )
+        assert response.status_code == 200
+        data = response.json()
+        assert data["valid"] is True
+
+    def test_validate_tool_type_invalid_compose(self, authenticated_client: TestClient) -> None:
+        """Test validating invalid compose template."""
+        response = authenticated_client.post(
+            "/tool-types/validate",
+            json={
+                "definition_type": "compose",
+                "compose_template": "invalid: yaml: [",
+            },
+        )
+        assert response.status_code == 200
+        data = response.json()
+        assert data["valid"] is False
+        assert "errors" in data
+
+    def test_validate_tool_type_dockerfile(self, authenticated_client: TestClient) -> None:
+        """Test validating dockerfile template."""
+        response = authenticated_client.post(
+            "/tool-types/validate",
+            json={
+                "definition_type": "dockerfile",
+                "dockerfile_template": "FROM python:3.11\nRUN pip install flask",
+            },
+        )
+        assert response.status_code == 200
+        data = response.json()
+        assert data["valid"] is True
+
+    def test_get_tool_type_returns_new_fields(self, authenticated_client: TestClient) -> None:
+        """Test that GET returns new fields."""
+        # Create tool type with all fields
+        create_response = authenticated_client.post(
+            "/tool-types",
+            json={
+                "name": "full-tool",
+                "display_name": "Full Tool",
+                "category": "editor",
+                "interfaces": ["web", "terminal"],
+                "default_port": 8443,
+                "definition_type": "compose",
+                "compose_template": "version: '3.8'\nservices:\n  app:\n    image: code-server\n    volumes:\n      - \"{{REPO_PATH}}:/workspace\"",
+                "readiness_probe": {
+                    "command": "curl -f http://localhost:8443",
+                    "timeout": 30,
+                    "interval": 2,
+                },
+                "required_variables": ["REPO_PATH"],
+            },
+        )
+        tool_id = create_response.json()["id"]
+
+        # Get it
+        response = authenticated_client.get(f"/tool-types/{tool_id}")
+        assert response.status_code == 200
+        data = response.json()
+        assert data["definition_type"] == "compose"
+        assert data["category"] == "editor"
+        assert data["interfaces"] == ["web", "terminal"]
+        assert "readiness_probe" in data

apps/api/tests/integration/test_users_api.py

@@ -8,7 +8,7 @@ import pytest
 from sqlalchemy import text
 from sqlalchemy.ext.asyncio import create_async_engine
 
-from src.auth.jwt_service import mint_access_token
+from src.auth.session import create_session_cookie
 from src.config import Settings, build_database_url
 from src.models import Base
 from src.models.user import User
@@ -78,7 +78,7 @@ def _insert_test_user(user_id: str) -> None:
 
 def _create_auth_cookie(user_id: str) -> str:
     settings = Settings()
-    return mint_access_token(
+    return create_session_cookie(
         settings=settings,
         subject=user_id,
         email="test@headquarter.local",

apps/api/tests/unit/test_docker_build.py

@@ -0,0 +1,151 @@
+"""Unit tests for docker build service."""
+
+import subprocess
+import tempfile
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from src.services.docker_build import build_image
+
+
+class TestBuildImage:
+    """Tests for build_image function."""
+
+    @patch("subprocess.run")
+    def test_builds_image_successfully(self, mock_run) -> None:
+        mock_run.return_value = MagicMock(
+            returncode=0,
+            stdout="Successfully built abc123",
+            stderr="",
+        )
+        
+        with tempfile.TemporaryDirectory() as tmpdir:
+            result = build_image(tmpdir, "FROM python:3.11", "test-image:latest")
+            
+            assert result[0] == 0
+            assert "Successfully built" in result[1]
+            mock_run.assert_called_once()
+            call_args = mock_run.call_args
+            assert "test-image:latest" in call_args[0][0]
+            assert "build" in call_args[0][0]
+
+    @patch("subprocess.run")
+    def test_build_fails(self, mock_run) -> None:
+        mock_run.return_value = MagicMock(
+            returncode=1,
+            stdout="",
+            stderr="Error: failed to build",
+        )
+        
+        with tempfile.TemporaryDirectory() as tmpdir:
+            result = build_image(tmpdir, "FROM invalid:image", "test-image:latest")
+            
+            assert result[0] == 1
+            assert "failed to build" in result[2]
+
+    @patch("subprocess.run")
+    def test_build_with_tag(self, mock_run) -> None:
+        mock_run.return_value = MagicMock(
+            returncode=0,
+            stdout="",
+            stderr="",
+        )
+        
+        with tempfile.TemporaryDirectory() as tmpdir:
+            build_image(tmpdir, "FROM python:3.11", "my-registry/tool:v1.0")
+            
+            call_args = mock_run.call_args[0][0]
+            assert "my-registry/tool:v1.0" in call_args
+
+    @patch("subprocess.run")
+    def test_build_command_structure(self, mock_run) -> None:
+        mock_run.return_value = MagicMock(returncode=0, stdout="", stderr="")
+        
+        with tempfile.TemporaryDirectory() as tmpdir:
+            build_image(tmpdir, "FROM python:3.11", "test:latest")
+            
+            cmd = mock_run.call_args[0][0]
+            assert cmd[0] == "docker"
+            assert cmd[1] == "build"
+            assert "-t" in cmd
+            assert "test:latest" in cmd
+            assert tmpdir in cmd
+
+    @patch("subprocess.run")
+    def test_build_writes_dockerfile(self, mock_run) -> None:
+        mock_run.return_value = MagicMock(returncode=0, stdout="", stderr="")
+        
+        with tempfile.TemporaryDirectory() as tmpdir:
+            dockerfile_content = "FROM python:3.11\\nRUN pip install flask"
+            build_image(tmpdir, dockerfile_content, "test:latest")
+            
+            dockerfile_path = Path(tmpdir) / "Dockerfile"
+            assert dockerfile_path.exists()
+            assert dockerfile_path.read_text() == dockerfile_content
+
+    @patch("subprocess.run")
+    def test_build_writes_context_files(self, mock_run) -> None:
+        mock_run.return_value = MagicMock(returncode=0, stdout="", stderr="")
+        
+        with tempfile.TemporaryDirectory() as tmpdir:
+            build_context = {
+                "requirements.txt": "flask==2.0\\nnumpy==1.21",
+                "app.py": "from flask import Flask\\napp = Flask(__name__)",
+            }
+            build_image(tmpdir, "FROM python:3.11", "test:latest", build_context)
+            
+            req_path = Path(tmpdir) / "requirements.txt"
+            app_path = Path(tmpdir) / "app.py"
+            assert req_path.exists()
+            assert req_path.read_text() == "flask==2.0\\nnumpy==1.21"
+            assert app_path.exists()
+            assert app_path.read_text() == "from flask import Flask\\napp = Flask(__name__)"
+
+    @patch("subprocess.run")
+    def test_build_creates_nested_directories(self, mock_run) -> None:
+        mock_run.return_value = MagicMock(returncode=0, stdout="", stderr="")
+        
+        with tempfile.TemporaryDirectory() as tmpdir:
+            build_context = {
+                "src/app.py": "print('hello')",
+            }
+            build_image(tmpdir, "FROM python:3.11", "test:latest", build_context)
+            
+            app_path = Path(tmpdir) / "src" / "app.py"
+            assert app_path.exists()
+
+    @patch("subprocess.run")
+    def test_build_prevents_path_traversal(self, mock_run) -> None:
+        mock_run.return_value = MagicMock(returncode=0, stdout="", stderr="")
+        
+        with tempfile.TemporaryDirectory() as tmpdir:
+            build_context = {
+                "../../../etc/passwd": "root:x:0:0",
+            }
+            
+            with pytest.raises(ValueError, match="escapes instance directory"):
+                build_image(tmpdir, "FROM python:3.11", "test:latest", build_context)
+            
+            mock_run.assert_not_called()
+
+    @patch("subprocess.run")
+    def test_build_timeout(self, mock_run) -> None:
+        mock_run.side_effect = subprocess.TimeoutExpired(cmd=["docker", "build"], timeout=300)
+        
+        with tempfile.TemporaryDirectory() as tmpdir:
+            result = build_image(tmpdir, "FROM python:3.11", "test:latest")
+            
+            assert result[0] == 1
+            assert "timed out" in result[2].lower()
+
+    @patch("subprocess.run")
+    def test_build_exception(self, mock_run) -> None:
+        mock_run.side_effect = OSError("Docker not available")
+        
+        with tempfile.TemporaryDirectory() as tmpdir:
+            result = build_image(tmpdir, "FROM python:3.11", "test:latest")
+            
+            assert result[0] == 1
+            assert "Docker not available" in result[2]

apps/api/tests/unit/test_git_repository_clone_preflight.py

@@ -0,0 +1,28 @@
+from unittest.mock import Mock, patch
+
+import pytest
+from fastapi import HTTPException
+
+from src.api.git_repositories import _build_provider_clone_url, _preflight_remote_repository
+
+
+def test_build_provider_clone_url_uses_fixed_host() -> None:
+    assert _build_provider_clone_url("alice", "demo") == "git@git.commumedia.org:alice/demo.git"
+
+
+def test_preflight_remote_repository_allows_accessible_repo() -> None:
+    completed = Mock(returncode=0)
+    with patch("src.api.git_repositories.subprocess.run", return_value=completed) as run_mock:
+        _preflight_remote_repository("git@git.commumedia.org:alice/demo.git")
+
+    run_mock.assert_called_once()
+
+
+def test_preflight_remote_repository_rejects_missing_repo() -> None:
+    completed = Mock(returncode=128)
+    with patch("src.api.git_repositories.subprocess.run", return_value=completed):
+        with pytest.raises(HTTPException) as exc_info:
+            _preflight_remote_repository("git@git.commumedia.org:alice/missing.git")
+
+    assert exc_info.value.status_code == 400
+    assert exc_info.value.detail == "repository not found or inaccessible"

apps/api/tests/unit/test_git_repository_working_clones.py

@@ -0,0 +1,64 @@
+from unittest.mock import Mock, patch
+
+import pytest
+from fastapi import HTTPException
+
+from src.api.git_repositories import _clone_working_repository, _init_working_repository
+from src.utils.git_control import create_branch
+
+
+def test_clone_working_repository_uses_normal_clone() -> None:
+    completed = Mock(returncode=0, stderr="")
+    with patch("src.api.git_repositories.subprocess.run", return_value=completed) as run_mock:
+        _clone_working_repository("git@git.commumedia.org:alice/demo.git", "/tmp/demo.git")
+
+    run_mock.assert_called_once()
+    assert run_mock.call_args.args[0] == ["git", "clone", "git@git.commumedia.org:alice/demo.git", "/tmp/demo.git"]
+
+
+def test_clone_working_repository_raises_on_failure() -> None:
+    completed = Mock(returncode=128, stderr="fatal: repository not found")
+    with patch("src.api.git_repositories.subprocess.run", return_value=completed):
+        with pytest.raises(HTTPException) as exc_info:
+            _clone_working_repository("git@git.commumedia.org:alice/missing.git", "/tmp/missing.git")
+
+    assert exc_info.value.status_code == 400
+    assert "failed to clone repository" in exc_info.value.detail
+
+
+def test_init_working_repository_prefers_init_b() -> None:
+    init_b = Mock(returncode=0, stderr="")
+    with patch("src.api.git_repositories.subprocess.run", return_value=init_b) as run_mock:
+        _init_working_repository("/tmp/new-repo")
+
+    assert run_mock.call_args.args[0] == ["git", "init", "-b", "main", "/tmp/new-repo"]
+
+
+def test_init_working_repository_falls_back_to_symbolic_ref() -> None:
+    init_b = Mock(returncode=1, stderr="unknown switch `b'")
+    init_ok = Mock(returncode=0, stderr="")
+    symbolic_ref = Mock(returncode=0, stderr="")
+
+    with patch("src.api.git_repositories.subprocess.run", side_effect=[init_b, init_ok, symbolic_ref]) as run_mock:
+        _init_working_repository("/tmp/new-repo")
+
+    assert run_mock.call_args_list[0].args[0] == ["git", "init", "-b", "main", "/tmp/new-repo"]
+    assert run_mock.call_args_list[1].args[0] == ["git", "init", "/tmp/new-repo"]
+    assert run_mock.call_args_list[2].args[0] == ["git", "-C", "/tmp/new-repo", "symbolic-ref", "HEAD", "refs/heads/main"]
+
+
+def test_create_branch_uses_orphan_checkout_when_head_is_unborn() -> None:
+    call_count = 0
+
+    def mock_run(repo_path: str, *args: str) -> str:
+        nonlocal call_count
+        call_count += 1
+        if call_count == 1:
+            raise RuntimeError("fatal: Needed a single revision")
+        return ""
+
+    with patch("src.utils.git_control._run_git_command", side_effect=mock_run) as run_mock:
+        create_branch("/tmp/new-repo", "feature/test")
+
+    assert run_mock.call_args_list[0].args[1:] == ("rev-parse", "--verify", "HEAD^{commit}")
+    assert run_mock.call_args_list[1].args[1:] == ("checkout", "--orphan", "feature/test")

apps/api/tests/unit/test_readiness_probe.py

@@ -0,0 +1,217 @@
+"""Unit tests for readiness probe service."""
+
+import asyncio
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from src.services.readiness_probe import execute_probe
+
+
+class TestExecuteProbe:
+    """Tests for execute_probe function."""
+
+    @patch("subprocess.run")
+    async def test_probe_succeeds_first_attempt(self, mock_run) -> None:
+        mock_run.return_value = MagicMock(
+            returncode=0,
+            stdout="healthy",
+            stderr="",
+        )
+        
+        result, logs = await execute_probe("container-123", "curl -f http://localhost:8080")
+        
+        assert result is True
+        assert any("Success" in log for log in logs)
+        mock_run.assert_called_once_with(
+            ["docker", "exec", "container-123", "sh", "-c", "curl -f http://localhost:8080"],
+            capture_output=True,
+            text=True,
+            timeout=2,
+        )
+
+    @patch("subprocess.run")
+    async def test_probe_fails_then_succeeds(self, mock_run) -> None:
+        mock_run.side_effect = [
+            MagicMock(returncode=1, stdout="", stderr="Connection refused"),
+            MagicMock(returncode=1, stdout="", stderr="Connection refused"),
+            MagicMock(returncode=0, stdout="healthy", stderr=""),
+        ]
+        
+        result, logs = await execute_probe("container-123", "curl -f http://localhost:8080", timeout=10, interval=0.1)
+        
+        assert result is True
+        assert mock_run.call_count == 3
+        assert any("Attempt 1: Failed" in log for log in logs)
+        assert any("Attempt 3: Success" in log for log in logs)
+
+    @patch("subprocess.run")
+    async def test_probe_times_out(self, mock_run) -> None:
+        mock_run.return_value = MagicMock(
+            returncode=1,
+            stdout="",
+            stderr="Connection refused",
+        )
+        
+        result, logs = await execute_probe("container-123", "curl -f http://localhost:8080", timeout=0.5, interval=0.2)
+        
+        assert result is False
+        assert any("timed out" in log.lower() for log in logs)
+
+    @patch("subprocess.run")
+    async def test_probe_command_not_found(self, mock_run) -> None:
+        mock_run.return_value = MagicMock(
+            returncode=127,
+            stdout="",
+            stderr="command not found",
+        )
+        
+        result, logs = await execute_probe("container-123", "nonexistent-command", timeout=1, interval=0.3)
+        
+        assert result is False
+        assert any("exit code 127" in log for log in logs)
+
+    @patch("subprocess.run")
+    async def test_probe_exception(self, mock_run) -> None:
+        mock_run.side_effect = OSError("Docker not available")
+        
+        result, logs = await execute_probe("container-123", "curl http://localhost", timeout=1, interval=0.3)
+        
+        assert result is False
+        assert any("Error" in log for log in logs)
+
+    @patch("subprocess.run")
+    async def test_probe_with_special_characters(self, mock_run) -> None:
+        mock_run.return_value = MagicMock(
+            returncode=0,
+            stdout="",
+            stderr="",
+        )
+        
+        cmd = "bash -c 'echo \"hello world\" && exit 0'"
+        await execute_probe("container-123", cmd)
+        
+        call_args = mock_run.call_args
+        assert cmd in call_args[0][0]
+
+    @patch("subprocess.run")
+    async def test_probe_captures_stdout(self, mock_run) -> None:
+        mock_run.return_value = MagicMock(
+            returncode=0,
+            stdout="Server is ready\\nVersion: 1.0",
+            stderr="",
+        )
+        
+        result, logs = await execute_probe("container-123", "cat /app/status")
+        
+        assert result is True
+        assert any("Server is ready" in log for log in logs)
+
+
+class TestIntegrationScenarios:
+    """Integration-style tests with realistic scenarios."""
+
+    @patch("subprocess.run")
+    async def test_web_server_probe(self, mock_run) -> None:
+        """Test typical web server health check."""
+        mock_run.side_effect = [
+            MagicMock(returncode=1, stdout="", stderr=""),
+            MagicMock(returncode=1, stdout="", stderr=""),
+            MagicMock(returncode=1, stdout="", stderr=""),
+            MagicMock(returncode=0, stdout="OK", stderr=""),
+        ]
+        
+        result, logs = await execute_probe(
+            "web-container",
+            "curl -f http://localhost:8080/health",
+            timeout=10,
+            interval=0.2,
+        )
+        
+        assert result is True
+        assert mock_run.call_count == 4
+
+    @patch("subprocess.run")
+    async def test_command_probe(self, mock_run) -> None:
+        """Test command availability check."""
+        mock_run.return_value = MagicMock(
+            returncode=0,
+            stdout="opencode 1.0.0",
+            stderr="",
+        )
+        
+        result, logs = await execute_probe(
+            "tool-container",
+            "which opencode && opencode --version",
+            timeout=30,
+            interval=2,
+        )
+        
+        assert result is True
+        assert any("opencode 1.0.0" in log for log in logs)
+
+    @patch("subprocess.run")
+    async def test_database_probe(self, mock_run) -> None:
+        """Test database readiness check."""
+        mock_run.side_effect = [
+            MagicMock(returncode=1, stdout="", stderr=""),
+            MagicMock(returncode=1, stdout="", stderr=""),
+            MagicMock(returncode=0, stdout="/var/run/postgresql:5432 - accepting connections", stderr=""),
+        ]
+        
+        result, logs = await execute_probe(
+            "db-container",
+            "pg_isready -U postgres",
+            timeout=10,
+            interval=0.3,
+        )
+        
+        assert result is True
+        assert mock_run.call_count == 3
+
+    @patch("subprocess.run")
+    async def test_file_probe(self, mock_run) -> None:
+        """Test file existence check."""
+        mock_run.return_value = MagicMock(returncode=0, stdout="", stderr="")
+        
+        result, logs = await execute_probe(
+            "app-container",
+            "[ -f /app/ready ]",
+            timeout=10,
+            interval=1,
+        )
+        
+        assert result is True
+
+    @patch("subprocess.run")
+    async def test_slow_starting_service(self, mock_run) -> None:
+        """Test service that takes time to start."""
+        # Simulate 5 failures before success
+        side_effects = [MagicMock(returncode=1, stdout="", stderr="")] * 5
+        side_effects.append(MagicMock(returncode=0, stdout="Ready", stderr=""))
+        mock_run.side_effect = side_effects
+        
+        result, logs = await execute_probe(
+            "slow-container",
+            "curl -f http://localhost:8080",
+            timeout=10,
+            interval=0.2,
+        )
+        
+        assert result is True
+        assert mock_run.call_count == 6
+        assert any("Attempt 6: Success" in log for log in logs)
+
+    @patch("subprocess.run")
+    async def test_zero_timeout_immediate_return(self, mock_run) -> None:
+        mock_run.return_value = MagicMock(returncode=1, stdout="", stderr="")
+        
+        result, logs = await execute_probe(
+            "container",
+            "test",
+            timeout=0,
+            interval=1,
+        )
+        
+        assert result is False
+        assert any("timed out" in log.lower() for log in logs)

apps/web/index.html

@@ -4,6 +4,12 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Headquarter</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=IBM+Plex+Mono:wght@400;500;600&display=swap"
+      rel="stylesheet"
+    />
   </head>
   <body>
     <div id="root"></div>

apps/web/package-lock.json

@@ -8,11 +8,18 @@
       "name": "headquarter-web",
       "version": "0.1.0",
       "dependencies": {
+        "@phosphor-icons/react": "^2.1.10",
+        "@types/prismjs": "^1.26.6",
         "axios": "^1.6.0",
+        "prismjs": "^1.30.0",
         "react": "^18.2.0",
         "react-dom": "^18.2.0",
         "react-router-dom": "^6.20.0",
-        "tailwindcss": "^3.3.0"
+        "react-simple-code-editor": "^0.14.1",
+        "tailwindcss": "^3.3.0",
+        "xterm": "^5.3.0",
+        "xterm-addon-fit": "^0.8.0",
+        "xterm-addon-web-links": "^0.9.0"
       },
       "devDependencies": {
         "@testing-library/jest-dom": "^6.9.1",
@@ -1268,6 +1275,19 @@
         "url": "https://github.com/sponsors/Boshen"
       }
     },
+    "node_modules/@phosphor-icons/react": {
+      "version": "2.1.10",
+      "resolved": "https://registry.npmjs.org/@phosphor-icons/react/-/react-2.1.10.tgz",
+      "integrity": "sha512-vt8Tvq8GLjheAZZYa+YG/pW7HDbov8El/MANW8pOAz4eGxrwhnbfrQZq0Cp4q8zBEu8NIhHdnr+r8thnfRSNYA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=10"
+      },
+      "peerDependencies": {
+        "react": ">= 16.8",
+        "react-dom": ">= 16.8"
+      }
+    },
     "node_modules/@remix-run/router": {
       "version": "1.23.2",
       "resolved": "https://registry.npmjs.org/@remix-run/router/-/router-1.23.2.tgz",
@@ -2127,6 +2147,12 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/@types/prismjs": {
+      "version": "1.26.6",
+      "resolved": "https://registry.npmjs.org/@types/prismjs/-/prismjs-1.26.6.tgz",
+      "integrity": "sha512-vqlvI7qlMvcCBbVe0AKAb4f97//Hy0EBTaiW8AalRnG/xAN5zOiWWyrNqNXeq8+KAuvRewjCVY1+IPxk4RdNYw==",
+      "license": "MIT"
+    },
     "node_modules/@types/prop-types": {
       "version": "15.7.15",
       "resolved": "https://registry.npmjs.org/@types/prop-types/-/prop-types-15.7.15.tgz",
@@ -5091,6 +5117,15 @@
         "url": "https://github.com/chalk/ansi-styles?sponsor=1"
       }
     },
+    "node_modules/prismjs": {
+      "version": "1.30.0",
+      "resolved": "https://registry.npmjs.org/prismjs/-/prismjs-1.30.0.tgz",
+      "integrity": "sha512-DEvV2ZF2r2/63V+tK8hQvrR2ZGn10srHbXviTlcv7Kpzw8jWiNTqbVgjO3IY8RxrrOUF8VPMQQFysYYYv0YZxw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
     "node_modules/proxy-from-env": {
       "version": "2.1.0",
       "resolved": "https://registry.npmjs.org/proxy-from-env/-/proxy-from-env-2.1.0.tgz",
@@ -5205,6 +5240,16 @@
         "react-dom": ">=16.8"
       }
     },
+    "node_modules/react-simple-code-editor": {
+      "version": "0.14.1",
+      "resolved": "https://registry.npmjs.org/react-simple-code-editor/-/react-simple-code-editor-0.14.1.tgz",
+      "integrity": "sha512-BR5DtNRy+AswWJECyA17qhUDvrrCZ6zXOCfkQY5zSmb96BVUbpVAv03WpcjcwtCwiLbIANx3gebHOcXYn1EHow==",
+      "license": "MIT",
+      "peerDependencies": {
+        "react": ">=16.8.0",
+        "react-dom": ">=16.8.0"
+      }
+    },
     "node_modules/read-cache": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/read-cache/-/read-cache-1.0.0.tgz",
@@ -6310,6 +6355,33 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/xterm": {
+      "version": "5.3.0",
+      "resolved": "https://registry.npmjs.org/xterm/-/xterm-5.3.0.tgz",
+      "integrity": "sha512-8QqjlekLUFTrU6x7xck1MsPzPA571K5zNqWm0M0oroYEWVOptZ0+ubQSkQ3uxIEhcIHRujJy6emDWX4A7qyFzg==",
+      "deprecated": "This package is now deprecated. Move to @xterm/xterm instead.",
+      "license": "MIT"
+    },
+    "node_modules/xterm-addon-fit": {
+      "version": "0.8.0",
+      "resolved": "https://registry.npmjs.org/xterm-addon-fit/-/xterm-addon-fit-0.8.0.tgz",
+      "integrity": "sha512-yj3Np7XlvxxhYF/EJ7p3KHaMt6OdwQ+HDu573Vx1lRXsVxOcnVJs51RgjZOouIZOczTsskaS+CpXspK81/DLqw==",
+      "deprecated": "This package is now deprecated. Move to @xterm/addon-fit instead.",
+      "license": "MIT",
+      "peerDependencies": {
+        "xterm": "^5.0.0"
+      }
+    },
+    "node_modules/xterm-addon-web-links": {
+      "version": "0.9.0",
+      "resolved": "https://registry.npmjs.org/xterm-addon-web-links/-/xterm-addon-web-links-0.9.0.tgz",
+      "integrity": "sha512-LIzi4jBbPlrKMZF3ihoyqayWyTXAwGfu4yprz1aK2p71e9UKXN6RRzVONR0L+Zd+Ik5tPVI9bwp9e8fDTQh49Q==",
+      "deprecated": "This package is now deprecated. Move to @xterm/addon-web-links instead.",
+      "license": "MIT",
+      "peerDependencies": {
+        "xterm": "^5.0.0"
+      }
+    },
     "node_modules/yallist": {
       "version": "3.1.1",
       "resolved": "https://registry.npmjs.org/yallist/-/yallist-3.1.1.tgz",

apps/web/package.json

@@ -11,11 +11,18 @@
     "test": "vitest run"
   },
   "dependencies": {
+    "@phosphor-icons/react": "^2.1.10",
+    "@types/prismjs": "^1.26.6",
     "axios": "^1.6.0",
+    "prismjs": "^1.30.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "react-router-dom": "^6.20.0",
-    "tailwindcss": "^3.3.0"
+    "react-simple-code-editor": "^0.14.1",
+    "tailwindcss": "^3.3.0",
+    "xterm": "^5.3.0",
+    "xterm-addon-fit": "^0.8.0",
+    "xterm-addon-web-links": "^0.9.0"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.9.1",

apps/web/public/preview.html

@@ -0,0 +1,796 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Headquarter - UI Preview</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=IBM+Plex+Mono:wght@400;500&display=swap" rel="stylesheet">
+    <style>
+        :root {
+            --bg: #f4f1ea;
+            --panel: #fffef9;
+            --ink: #1d1d1b;
+            --muted: #5f5b55;
+            --brand: #275d4b;
+            --brand-strong: #154236;
+            --border: #d8d0c5;
+            --primary: #275d4b;
+            --primary-fg: #fffef9;
+            --color-primary: #275d4b;
+            --success: #2f8f62;
+            --success-light: rgba(47, 143, 98, 0.14);
+            --warning: #c08a1e;
+            --warning-light: rgba(192, 138, 30, 0.14);
+            --danger: #b94a3c;
+            --danger-light: rgba(185, 74, 60, 0.14);
+            --info: #4f7fb8;
+            --info-light: rgba(79, 127, 184, 0.14);
+            --space-1: 0.25rem;
+            --space-2: 0.5rem;
+            --space-3: 0.75rem;
+            --space-4: 1rem;
+            --space-5: 1.5rem;
+            --space-6: 2rem;
+            --font-size-xs: clamp(0.625rem, 0.6rem + 0.125vw, 0.75rem);
+            --font-size-sm: clamp(0.75rem, 0.7rem + 0.25vw, 0.875rem);
+            --font-size-base: clamp(0.875rem, 0.8rem + 0.35vw, 1rem);
+            --font-size-lg: clamp(1rem, 0.9rem + 0.5vw, 1.25rem);
+            --font-size-xl: clamp(1.25rem, 1.1rem + 0.75vw, 1.5rem);
+        }
+
+        * {
+            box-sizing: border-box;
+            margin: 0;
+            padding: 0;
+        }
+
+        body {
+            font-family: "Inter", "IBM Plex Sans", "Segoe UI", sans-serif;
+            background: var(--bg);
+            color: var(--ink);
+            line-height: 1.5;
+        }
+
+        /* App Shell */
+        .shell {
+            min-height: 100vh;
+            display: flex;
+            flex-direction: column;
+        }
+
+        .shell-header {
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+            padding: 0.85rem 1.25rem;
+            border-bottom: 1px solid var(--border);
+            background: color-mix(in srgb, var(--panel) 88%, transparent);
+            backdrop-filter: blur(7px);
+        }
+
+        .brand {
+            font-weight: 700;
+            letter-spacing: 0.02em;
+            color: var(--ink);
+            text-decoration: none;
+        }
+
+        .header-actions {
+            display: flex;
+            align-items: center;
+            gap: 0.75rem;
+        }
+
+        .user-chip {
+            border: 1px solid var(--border);
+            background: var(--panel);
+            border-radius: 999px;
+            padding: 0.35rem 0.7rem;
+            font-size: 0.9rem;
+            color: var(--ink);
+            text-decoration: none;
+        }
+
+        .ghost-button {
+            border: 1px solid var(--border);
+            background: transparent;
+            border-radius: 10px;
+            padding: 0.58rem 0.85rem;
+            cursor: pointer;
+            font: inherit;
+            color: var(--muted);
+        }
+
+        .shell-body {
+            display: grid;
+            grid-template-columns: 230px 1fr;
+            min-height: calc(100vh - 57px);
+        }
+
+        .shell-nav {
+            border-right: 1px solid var(--border);
+            padding: 1rem 0.75rem;
+            display: flex;
+            flex-direction: column;
+            gap: 0.4rem;
+            background: color-mix(in srgb, var(--panel) 65%, transparent);
+        }
+
+        .nav-item {
+            padding: 0.65rem 0.75rem;
+            border-radius: 10px;
+            color: var(--muted);
+            text-decoration: none;
+            display: flex;
+            align-items: center;
+            gap: 0.5rem;
+            font-size: 0.95rem;
+        }
+
+        .nav-item:hover {
+            background: #ece7df;
+            color: var(--ink);
+        }
+
+        .nav-item-active {
+            background: var(--brand);
+            color: #f7fff7;
+        }
+
+        .nav-badge {
+            display: inline-flex;
+            align-items: center;
+            justify-content: center;
+            min-width: 18px;
+            height: 18px;
+            padding: 0 5px;
+            background: var(--primary);
+            color: var(--primary-fg);
+            border-radius: 9px;
+            font-size: 11px;
+            font-weight: 600;
+            margin-left: auto;
+        }
+
+        .nav-divider {
+            height: 1px;
+            background: var(--border);
+            margin: 0.5rem 0;
+        }
+
+        .nav-section-title {
+            margin-top: 0.5rem;
+            padding: 0.25rem 0.75rem;
+            font-size: var(--font-size-xs);
+            text-transform: uppercase;
+            letter-spacing: 0.08em;
+            color: var(--muted);
+        }
+
+        .session-item {
+            font-size: 0.85rem;
+            padding: 0.5rem 0.75rem;
+        }
+
+        .session-status {
+            width: 8px;
+            height: 8px;
+            border-radius: 50%;
+            background: var(--muted);
+            display: inline-block;
+            margin-right: 0.25rem;
+        }
+
+        .session-status.running {
+            background: var(--success);
+        }
+
+        .shell-content {
+            padding: 1.25rem;
+            overflow-x: hidden;
+        }
+
+        /* Common Components */
+        .stack {
+            display: flex;
+            flex-direction: column;
+            gap: 1rem;
+        }
+
+        .stack-sm {
+            gap: 0.5rem;
+        }
+
+        .card {
+            background: var(--panel);
+            border: 1px solid var(--border);
+            border-radius: 14px;
+            padding: 1rem;
+        }
+
+        .muted {
+            color: var(--muted);
+        }
+
+        .eyebrow {
+            margin: 0;
+            font-size: var(--font-size-xs);
+            text-transform: uppercase;
+            letter-spacing: 0.08em;
+            color: var(--muted);
+        }
+
+        .page-header {
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+            flex-wrap: wrap;
+            gap: var(--space-3);
+        }
+
+        .primary-button {
+            background: var(--brand);
+            color: white;
+            border-radius: 10px;
+            border: 1px solid transparent;
+            padding: 0.58rem 0.85rem;
+            cursor: pointer;
+            font: inherit;
+        }
+
+        .primary-button:hover {
+            background: var(--brand-strong);
+        }
+
+        .secondary-button {
+            border-color: var(--border);
+            background: var(--panel);
+            border-radius: 10px;
+            border: 1px solid var(--border);
+            padding: 0.58rem 0.85rem;
+            cursor: pointer;
+            font: inherit;
+        }
+
+        /* Home Page */
+        .home-page {
+            max-width: 1240px;
+        }
+
+        .home-hero {
+            display: flex;
+            justify-content: space-between;
+            gap: var(--space-4);
+            align-items: flex-start;
+        }
+
+        .home-hero-actions {
+            display: flex;
+            gap: var(--space-2);
+            flex-wrap: wrap;
+        }
+
+        .home-summary-grid {
+            display: grid;
+            grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
+            gap: var(--space-4);
+        }
+
+        .home-summary-card .card-label {
+            margin: 0;
+            color: var(--muted);
+            font-size: 0.875rem;
+        }
+
+        .home-summary-card .card-value {
+            margin: 0.45rem 0 0;
+            font-size: 1.6rem;
+            font-weight: 700;
+        }
+
+        .home-section h2,
+        .home-section h3 {
+            margin: 0;
+        }
+
+        .home-session-grid,
+        .home-project-grid {
+            display: grid;
+            gap: var(--space-4);
+            grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+        }
+
+        .session-card {
+            box-shadow: 0 1px 0 rgba(0, 0, 0, 0.02);
+        }
+
+        .session-actions {
+            display: flex;
+            gap: var(--space-2);
+            flex-wrap: wrap;
+        }
+
+        .status-badge {
+            display: inline-flex;
+            align-items: center;
+            padding: 2px 8px;
+            border-radius: 4px;
+            font-size: 12px;
+            font-weight: 500;
+            text-transform: capitalize;
+        }
+
+        .status-badge.running {
+            background: var(--success-light);
+            color: var(--success);
+        }
+
+        .status-badge.building {
+            background: var(--warning-light);
+            color: var(--warning);
+        }
+
+        .status-badge.pending {
+            background: var(--info-light);
+            color: var(--info);
+        }
+
+        .recent-sessions-list {
+            display: flex;
+            flex-direction: column;
+            gap: var(--space-2);
+        }
+
+        .recent-session-item {
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+            padding: var(--space-3) var(--space-4);
+            background: var(--bg);
+            border: 1px solid var(--border);
+            border-radius: 8px;
+        }
+
+        .recent-session-name {
+            font-weight: 500;
+        }
+
+        .create-session-form .form-row {
+            display: grid;
+            grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+            gap: var(--space-4);
+        }
+
+        .form-field {
+            display: flex;
+            flex-direction: column;
+            gap: 0.35rem;
+        }
+
+        .form-field input,
+        .form-field select,
+        .form-field textarea {
+            padding: 0.55rem 0.7rem;
+            border: 1px solid var(--border);
+            border-radius: 10px;
+            font: inherit;
+            background: var(--panel);
+            color: var(--ink);
+        }
+
+        .form-actions {
+            display: flex;
+            gap: var(--space-3);
+            align-items: center;
+            flex-wrap: wrap;
+        }
+
+        /* Settings Page */
+        .settings-page {
+            max-width: 1240px;
+        }
+
+        .settings-header {
+            padding: 1.5rem;
+        }
+
+        .settings-tabs {
+            display: flex;
+            gap: var(--space-2);
+            flex-wrap: wrap;
+        }
+
+        .settings-tab {
+            padding: 0.6rem 0.9rem;
+            border-radius: 999px;
+            border: 1px solid var(--border);
+            color: var(--muted);
+            background: var(--panel);
+            text-decoration: none;
+            cursor: pointer;
+        }
+
+        .settings-tab.active {
+            background: var(--brand);
+            color: white;
+            border-color: transparent;
+        }
+
+        .settings-panel {
+            padding: 1.5rem;
+        }
+
+        .settings-actions {
+            display: flex;
+            gap: var(--space-3);
+            align-items: center;
+            flex-wrap: wrap;
+        }
+
+        .success-text {
+            color: var(--success);
+        }
+
+        .error-text {
+            color: var(--danger);
+        }
+
+        /* Preview Switcher */
+        .preview-switcher {
+            position: fixed;
+            bottom: 1rem;
+            right: 1rem;
+            display: flex;
+            gap: 0.5rem;
+            background: var(--panel);
+            border: 1px solid var(--border);
+            border-radius: 10px;
+            padding: 0.5rem;
+            box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
+            z-index: 1000;
+        }
+
+        .preview-switcher button {
+            padding: 0.5rem 1rem;
+            border: none;
+            background: transparent;
+            border-radius: 6px;
+            cursor: pointer;
+            font: inherit;
+            color: var(--muted);
+        }
+
+        .preview-switcher button.active {
+            background: var(--brand);
+            color: white;
+        }
+
+        .page-preview {
+            display: none;
+        }
+
+        .page-preview.active {
+            display: block;
+        }
+
+        /* Responsive */
+        @media (max-width: 767px) {
+            .shell-body {
+                grid-template-columns: 1fr;
+            }
+            .shell-nav {
+                flex-direction: row;
+                overflow-x: auto;
+                border-right: none;
+                border-bottom: 1px solid var(--border);
+            }
+            .home-hero {
+                flex-direction: column;
+            }
+        }
+    </style>
+</head>
+<body>
+    <div class="shell">
+        <header class="shell-header">
+            <a href="#" class="brand">Headquarter</a>
+            <div class="header-actions">
+                <a href="#" class="user-chip">User</a>
+                <button class="ghost-button">Logout</button>
+            </div>
+        </header>
+
+        <div class="shell-body">
+            <aside class="shell-nav" aria-label="Primary navigation">
+                <a href="#" class="nav-item nav-item-active">
+                    <span>🏠</span> Home
+                    <span class="nav-badge">3</span>
+                </a>
+                <a href="#" class="nav-item">
+                    <span>📁</span> Projects
+                </a>
+                <a href="#" class="nav-item">
+                    <span>⚙️</span> Settings
+                </a>
+
+                <div class="nav-divider"></div>
+                <div class="nav-section-title">Live sessions</div>
+                <a href="#" class="nav-item session-item">
+                    <span class="session-status running"></span>
+                    <span>Dev Environment</span>
+                </a>
+                <a href="#" class="nav-item session-item">
+                    <span class="session-status running"></span>
+                    <span>Jupyter Lab</span>
+                </a>
+                <a href="#" class="nav-item session-item">
+                    <span class="session-status"></span>
+                    <span>Code Server</span>
+                </a>
+            </aside>
+
+            <main class="shell-content">
+                <!-- HOME PAGE PREVIEW -->
+                <div id="home-preview" class="page-preview active">
+                    <section class="stack home-page">
+                        <header class="home-hero card">
+                            <div class="stack-sm">
+                                <p class="eyebrow">Workspace overview</p>
+                                <h1>Home</h1>
+                                <p class="muted">Open sessions, available projects, and the fastest path back into work.</p>
+                            </div>
+                            <div class="home-hero-actions">
+                                <button class="primary-button">New Project</button>
+                                <button class="secondary-button">Settings</button>
+                            </div>
+                        </header>
+
+                        <div class="home-summary-grid">
+                            <article class="card home-summary-card">
+                                <p class="card-label">Open sessions</p>
+                                <p class="card-value">3</p>
+                            </article>
+                            <article class="card home-summary-card">
+                                <p class="card-label">Projects</p>
+                                <p class="card-value">5</p>
+                            </article>
+                            <article class="card home-summary-card">
+                                <p class="card-label">Repositories</p>
+                                <p class="card-value">12</p>
+                            </article>
+                        </div>
+
+                        <section class="card stack home-section">
+                            <div class="page-header">
+                                <div>
+                                    <p class="eyebrow">Open sessions</p>
+                                    <h2>3</h2>
+                                </div>
+                            </div>
+                            <div class="home-session-grid">
+                                <article class="card session-card">
+                                    <div class="stack-sm">
+                                        <div style="display: flex; gap: 0.5rem; align-items: center;">
+                                            <h3>Dev Environment</h3>
+                                            <span class="status-badge running">running</span>
+                                        </div>
+                                        <p class="muted">Acme Corp · main</p>
+                                        <p class="muted">VS Code Server</p>
+                                    </div>
+                                    <div class="session-actions">
+                                        <button class="secondary-button" style="font-size: 0.85rem; padding: 0.42rem 0.7rem;">Open</button>
+                                        <button class="ghost-button" style="font-size: 0.85rem; padding: 0.42rem 0.7rem;">Tunnel</button>
+                                        <button class="ghost-button" style="font-size: 0.85rem; padding: 0.42rem 0.7rem;">Stop</button>
+                                        <button class="ghost-button" style="font-size: 0.85rem; padding: 0.42rem 0.7rem; color: var(--danger);">Delete</button>
+                                    </div>
+                                </article>
+
+                                <article class="card session-card">
+                                    <div class="stack-sm">
+                                        <div style="display: flex; gap: 0.5rem; align-items: center;">
+                                            <h3>Jupyter Lab</h3>
+                                            <span class="status-badge running">running</span>
+                                        </div>
+                                        <p class="muted">Data Science · experiments</p>
+                                        <p class="muted">Jupyter Notebook</p>
+                                    </div>
+                                    <div class="session-actions">
+                                        <button class="secondary-button" style="font-size: 0.85rem; padding: 0.42rem 0.7rem;">Open</button>
+                                        <button class="ghost-button" style="font-size: 0.85rem; padding: 0.42rem 0.7rem;">Tunnel</button>
+                                        <button class="ghost-button" style="font-size: 0.85rem; padding: 0.42rem 0.7rem;">Stop</button>
+                                        <button class="ghost-button" style="font-size: 0.85rem; padding: 0.42rem 0.7rem; color: var(--danger);">Delete</button>
+                                    </div>
+                                </article>
+
+                                <article class="card session-card">
+                                    <div class="stack-sm">
+                                        <div style="display: flex; gap: 0.5rem; align-items: center;">
+                                            <h3>Database Console</h3>
+                                            <span class="status-badge building">building</span>
+                                        </div>
+                                        <p class="muted">Backend API · staging</p>
+                                        <p class="muted">PostgreSQL Client</p>
+                                    </div>
+                                    <div class="session-actions">
+                                        <button class="secondary-button" style="font-size: 0.85rem; padding: 0.42rem 0.7rem;">Open</button>
+                                        <button class="ghost-button" style="font-size: 0.85rem; padding: 0.42rem 0.7rem;">Tunnel</button>
+                                        <button class="ghost-button" style="font-size: 0.85rem; padding: 0.42rem 0.7rem;">Stop</button>
+                                        <button class="ghost-button" style="font-size: 0.85rem; padding: 0.42rem 0.7rem; color: var(--danger);">Delete</button>
+                                    </div>
+                                </article>
+                            </div>
+                        </section>
+
+                        <section class="card stack home-section">
+                            <div class="page-header">
+                                <div>
+                                    <p class="eyebrow">Available projects</p>
+                                    <h2>5</h2>
+                                </div>
+                                <button class="secondary-button">View all</button>
+                            </div>
+                            <div class="home-project-grid">
+                                <article class="card" style="box-shadow: 0 1px 0 rgba(0,0,0,0.02);">
+                                    <div class="stack-sm">
+                                        <h3>Acme Corp</h3>
+                                        <p class="muted">Main product development</p>
+                                    </div>
+                                    <button class="ghost-button" style="font-size: 0.85rem; padding: 0.42rem 0.7rem; margin-top: 0.5rem;">Open Workspace</button>
+                                </article>
+
+                                <article class="card" style="box-shadow: 0 1px 0 rgba(0,0,0,0.02);">
+                                    <div class="stack-sm">
+                                        <h3>Data Science</h3>
+                                        <p class="muted">ML experiments and notebooks</p>
+                                    </div>
+                                    <button class="ghost-button" style="font-size: 0.85rem; padding: 0.42rem 0.7rem; margin-top: 0.5rem;">Open Workspace</button>
+                                </article>
+
+                                <article class="card" style="box-shadow: 0 1px 0 rgba(0,0,0,0.02);">
+                                    <div class="stack-sm">
+                                        <h3>Backend API</h3>
+                                        <p class="muted">REST API services</p>
+                                    </div>
+                                    <button class="ghost-button" style="font-size: 0.85rem; padding: 0.42rem 0.7rem; margin-top: 0.5rem;">Open Workspace</button>
+                                </article>
+                            </div>
+                        </section>
+
+                        <section class="card stack home-section">
+                            <div class="page-header">
+                                <div>
+                                    <p class="eyebrow">Quick create</p>
+                                    <h2>Start a session</h2>
+                                </div>
+                            </div>
+                            <form class="stack create-session-form">
+                                <div class="form-row">
+                                    <label class="form-field">
+                                        Project
+                                        <select>
+                                            <option>Select project...</option>
+                                            <option>Acme Corp</option>
+                                            <option>Data Science</option>
+                                        </select>
+                                    </label>
+                                    <label class="form-field">
+                                        Repository
+                                        <select disabled>
+                                            <option>Select repository...</option>
+                                        </select>
+                                    </label>
+                                    <label class="form-field">
+                                        Tool type
+                                        <select>
+                                            <option>Select tool...</option>
+                                            <option>VS Code Server</option>
+                                            <option>Jupyter Lab</option>
+                                        </select>
+                                    </label>
+                                </div>
+                                <label class="form-field">
+                                    Display name
+                                    <input type="text" placeholder="My Development Environment">
+                                </label>
+                                <div class="form-actions">
+                                    <button class="primary-button" type="submit">Create Session</button>
+                                </div>
+                            </form>
+                        </section>
+
+                        <section class="card stack home-section">
+                            <div class="page-header">
+                                <div>
+                                    <p class="eyebrow">Recent sessions</p>
+                                    <h2>2</h2>
+                                </div>
+                            </div>
+                            <div class="recent-sessions-list">
+                                <article class="recent-session-item">
+                                    <div style="display: flex; flex-direction: column; gap: 0.25rem;">
+                                        <span class="recent-session-name">Old Dev Box</span>
+                                        <span class="muted">Acme Corp · VS Code Server</span>
+                                    </div>
+                                    <button class="ghost-button" style="font-size: 0.85rem; padding: 0.42rem 0.7rem;">Open</button>
+                                </article>
+                                <article class="recent-session-item">
+                                    <div style="display: flex; flex-direction: column; gap: 0.25rem;">
+                                        <span class="recent-session-name">ML Training</span>
+                                        <span class="muted">Data Science · Jupyter Lab</span>
+                                    </div>
+                                    <button class="ghost-button" style="font-size: 0.85rem; padding: 0.42rem 0.7rem;">Open</button>
+                                </article>
+                            </div>
+                        </section>
+                    </section>
+                </div>
+
+                <!-- SETTINGS PAGE PREVIEW -->
+                <div id="settings-preview" class="page-preview">
+                    <section class="stack settings-page">
+                        <header class="settings-header card stack-sm">
+                            <div>
+                                <p class="eyebrow">Configuration</p>
+                                <h1>Settings</h1>
+                            </div>
+                            <p class="muted">General preferences, SSH keys, tool types, and tool configs live here.</p>
+                        </header>
+
+                        <nav class="settings-tabs" aria-label="Settings sections">
+                            <a href="#" class="settings-tab active">General</a>
+                            <a href="#" class="settings-tab">SSH Keys</a>
+                            <a href="#" class="settings-tab">Tool Types</a>
+                            <a href="#" class="settings-tab">Tool Configs</a>
+                        </nav>
+
+                        <div class="settings-panel card">
+                            <div class="stack">
+                                <h2>General</h2>
+                                <label class="form-field">
+                                    Theme
+                                    <select>
+                                        <option>System</option>
+                                        <option>Light</option>
+                                        <option>Dark</option>
+                                    </select>
+                                </label>
+                                <label class="form-field">
+                                    Git user name
+                                    <input type="text" placeholder="Your git commit name" value="John Doe">
+                                </label>
+                                <label class="form-field">
+                                    Git user email
+                                    <input type="email" placeholder="your.email@example.com" value="john@example.com">
+                                </label>
+                                <label class="form-field">
+                                    Default editor
+                                    <input type="text" placeholder="e.g., vscode, vim, cursor" value="vscode">
+                                </label>
+                                <div class="settings-actions">
+                                    <button class="primary-button">Save Settings</button>
+                                </div>
+                            </div>
+                        </div>
+                    </section>
+                </div>
+            </main>
+        </div>
+    </div>
+
+    <div class="preview-switcher">
+        <button class="active" onclick="showPage('home')">Home</button>
+        <button onclick="showPage('settings')">Settings</button>
+    </div>
+
+    <script>
+        function showPage(page) {
+            document.querySelectorAll('.page-preview').forEach(p => p.classList.remove('active'));
+            document.querySelectorAll('.preview-switcher button').forEach(b => b.classList.remove('active'));
+            document.getElementById(page + '-preview').classList.add('active');
+            event.target.classList.add('active');
+        }
+    </script>
+</body>
+</html>

apps/web/src/api/config_folders.test.ts

@@ -0,0 +1,131 @@
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  createConfigFolder,
+  deleteConfigFolder,
+  listConfigFolders,
+  updateConfigFolder,
+} from "../api/config_folders";
+
+const mockGet = vi.fn();
+const mockPost = vi.fn();
+const mockPut = vi.fn();
+const mockDelete = vi.fn();
+
+vi.mock("../api/client", () => ({
+  apiClient: {
+    get: (...args: unknown[]) => mockGet(...args),
+    post: (...args: unknown[]) => mockPost(...args),
+    put: (...args: unknown[]) => mockPut(...args),
+    delete: (...args: unknown[]) => mockDelete(...args),
+    interceptors: {
+      response: {
+        use: vi.fn(),
+      },
+    },
+  },
+  shouldSkipAuthRedirect: vi.fn(() => false),
+}));
+
+describe("config_folders API", () => {
+  describe("listConfigFolders", () => {
+    it("returns folders with files and overrides", async () => {
+      const mockResponse = {
+        data: [
+          {
+            id: "folder-1",
+            name: "my-dotfiles",
+            description: "My personal config files",
+            mount_path: "/home/user",
+            files: { ".zshrc": "export ZSH=\"$HOME/.oh-my-zsh\"" },
+            project_overrides: {},
+            is_active: true,
+            user_id: "user-1",
+            created_at: "2024-01-01T00:00:00Z",
+            updated_at: "2024-01-01T00:00:00Z",
+          },
+        ],
+      };
+      mockGet.mockResolvedValue(mockResponse);
+
+      const result = await listConfigFolders();
+
+      expect(result[0].name).toBe("my-dotfiles");
+      expect(result[0].files).toEqual({ ".zshrc": "export ZSH=\"$HOME/.oh-my-zsh\"" });
+      expect(mockGet).toHaveBeenCalledWith("/config-folders");
+    });
+  });
+
+  describe("createConfigFolder", () => {
+    it("creates folder with files", async () => {
+      const mockResponse = {
+        data: {
+          id: "folder-new",
+          name: "new-folder",
+          mount_path: "/workspace",
+          files: { ".env": "API_URL=http://localhost" },
+          is_active: true,
+          user_id: "user-1",
+          created_at: "2024-01-01T00:00:00Z",
+          updated_at: "2024-01-01T00:00:00Z",
+        },
+      };
+      mockPost.mockResolvedValue(mockResponse);
+
+      const result = await createConfigFolder({
+        name: "new-folder",
+        mount_path: "/workspace",
+        files: { ".env": "API_URL=http://localhost" },
+      });
+
+      expect(result.name).toBe("new-folder");
+      expect(mockPost).toHaveBeenCalledWith(
+        "/config-folders",
+        expect.objectContaining({
+          name: "new-folder",
+          mount_path: "/workspace",
+        })
+      );
+    });
+  });
+
+  describe("updateConfigFolder", () => {
+    it("updates folder files", async () => {
+      const mockResponse = {
+        data: {
+          id: "folder-1",
+          name: "updated-folder",
+          mount_path: "/home/user",
+          files: { ".bashrc": "alias ll='ls -la'" },
+          is_active: true,
+          user_id: "user-1",
+          created_at: "2024-01-01T00:00:00Z",
+          updated_at: "2024-01-01T00:00:00Z",
+        },
+      };
+      mockPut.mockResolvedValue(mockResponse);
+
+      const result = await updateConfigFolder("folder-1", {
+        files: { ".bashrc": "alias ll='ls -la'" },
+      });
+
+      expect(result.files).toEqual({ ".bashrc": "alias ll='ls -la'" });
+      expect(mockPut).toHaveBeenCalledWith(
+        "/config-folders/folder-1",
+        expect.objectContaining({
+          files: { ".bashrc": "alias ll='ls -la'" },
+        })
+      );
+    });
+  });
+
+  describe("deleteConfigFolder", () => {
+    it("deletes folder", async () => {
+      mockDelete.mockResolvedValue({ data: undefined });
+
+      await deleteConfigFolder("folder-1");
+
+      expect(mockDelete).toHaveBeenCalledWith("/config-folders/folder-1");
+    });
+  });
+});

apps/web/src/api/config_folders.ts

@@ -0,0 +1,95 @@
+import { apiClient } from "./client";
+
+export interface ConfigFolder {
+  id: string;
+  user_id: string;
+  name: string;
+  description: string | null;
+  mount_path: string;
+  files: Record<string, string>;
+  project_overrides: Record<string, { mount_path?: string; files?: Record<string, string> }> | null;
+  is_active: boolean;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface CreateConfigFolderRequest {
+  name: string;
+  description?: string;
+  mount_path: string;
+  files?: Record<string, string>;
+  is_active?: boolean;
+}
+
+export interface UpdateConfigFolderRequest {
+  name?: string;
+  description?: string;
+  mount_path?: string;
+  files?: Record<string, string>;
+  is_active?: boolean;
+}
+
+export interface ProjectOverrideRequest {
+  mount_path?: string;
+  files?: Record<string, string>;
+}
+
+export const listConfigFolders = async (): Promise<ConfigFolder[]> => {
+  const response = await apiClient.get<ConfigFolder[]>("/config-folders");
+  return response.data;
+};
+
+export const getConfigFolder = async (id: string): Promise<ConfigFolder> => {
+  const response = await apiClient.get<ConfigFolder>(`/config-folders/${id}`);
+  return response.data;
+};
+
+export const createConfigFolder = async (
+  data: CreateConfigFolderRequest
+): Promise<ConfigFolder> => {
+  const response = await apiClient.post<ConfigFolder>("/config-folders", data);
+  return response.data;
+};
+
+export const updateConfigFolder = async (
+  id: string,
+  data: UpdateConfigFolderRequest
+): Promise<ConfigFolder> => {
+  const response = await apiClient.put<ConfigFolder>(`/config-folders/${id}`, data);
+  return response.data;
+};
+
+export const deleteConfigFolder = async (id: string): Promise<void> => {
+  await apiClient.delete(`/config-folders/${id}`);
+};
+
+export const addProjectOverride = async (
+  id: string,
+  projectId: string,
+  data: ProjectOverrideRequest
+): Promise<ConfigFolder> => {
+  const response = await apiClient.post<ConfigFolder>(
+    `/config-folders/${id}/overrides/${projectId}`,
+    data
+  );
+  return response.data;
+};
+
+export const updateProjectOverride = async (
+  id: string,
+  projectId: string,
+  data: ProjectOverrideRequest
+): Promise<ConfigFolder> => {
+  const response = await apiClient.put<ConfigFolder>(
+    `/config-folders/${id}/overrides/${projectId}`,
+    data
+  );
+  return response.data;
+};
+
+export const deleteProjectOverride = async (
+  id: string,
+  projectId: string
+): Promise<void> => {
+  await apiClient.delete(`/config-folders/${id}/overrides/${projectId}`);
+};

apps/web/src/api/git_repositories.ts

@@ -112,3 +112,134 @@ export async function getCommitDetail(
   );
   return response.data;
 }
+
+// Git Control API
+
+export interface GitStatus {
+  branch: string;
+  modified: string[];
+  added: string[];
+  deleted: string[];
+  untracked: string[];
+  renamed: string[];
+  ahead: number;
+  behind: number;
+}
+
+export async function getRepositoryStatus(
+  projectId: string,
+  repoId: string
+): Promise<GitStatus> {
+  const response = await apiClient.get(
+    `/projects/${projectId}/repositories/${repoId}/status`
+  );
+  return response.data;
+}
+
+export async function createBranch(
+  projectId: string,
+  repoId: string,
+  name: string,
+  baseBranch: string = "HEAD"
+): Promise<{ message: string; branch: string }> {
+  const response = await apiClient.post(
+    `/projects/${projectId}/repositories/${repoId}/branches`,
+    { name, base_branch: baseBranch }
+  );
+  return response.data;
+}
+
+export async function deleteBranch(
+  projectId: string,
+  repoId: string,
+  branchName: string,
+  force: boolean = false
+): Promise<{ message: string }> {
+  const response = await apiClient.delete(
+    `/projects/${projectId}/repositories/${repoId}/branches/${branchName}?force=${force}`
+  );
+  return response.data;
+}
+
+export async function checkoutBranch(
+  projectId: string,
+  repoId: string,
+  branch: string
+): Promise<{ message: string; branch: string }> {
+  const response = await apiClient.post(
+    `/projects/${projectId}/repositories/${repoId}/checkout`,
+    { branch }
+  );
+  return response.data;
+}
+
+export interface CommitResponse {
+  commit_hash: string;
+  message: string;
+}
+
+export async function commitChanges(
+  projectId: string,
+  repoId: string,
+  message: string,
+  files?: string[]
+): Promise<CommitResponse> {
+  const response = await apiClient.post(
+    `/projects/${projectId}/repositories/${repoId}/commit`,
+    { message, files }
+  );
+  return response.data;
+}
+
+export async function fetchRepository(
+  projectId: string,
+  repoId: string
+): Promise<{ message: string }> {
+  const response = await apiClient.post(
+    `/projects/${projectId}/repositories/${repoId}/fetch`
+  );
+  return response.data;
+}
+
+export async function pullRepository(
+  projectId: string,
+  repoId: string,
+  branch?: string
+): Promise<{ message: string }> {
+  const params = branch ? `?branch=${branch}` : "";
+  const response = await apiClient.post(
+    `/projects/${projectId}/repositories/${repoId}/pull${params}`
+  );
+  return response.data;
+}
+
+export async function pushRepository(
+  projectId: string,
+  repoId: string,
+  branch?: string
+): Promise<{ message: string }> {
+  const params = branch ? `?branch=${branch}` : "";
+  const response = await apiClient.post(
+    `/projects/${projectId}/repositories/${repoId}/push${params}`
+  );
+  return response.data;
+}
+
+export interface MergeResponse {
+  commit_hash: string;
+  message: string;
+}
+
+export async function mergeBranches(
+  projectId: string,
+  repoId: string,
+  sourceBranch: string,
+  targetBranch?: string,
+  message?: string
+): Promise<MergeResponse> {
+  const response = await apiClient.post(
+    `/projects/${projectId}/repositories/${repoId}/merge`,
+    { source_branch: sourceBranch, target_branch: targetBranch, message }
+  );
+  return response.data;
+}

apps/web/src/api/sessions.ts

@@ -0,0 +1,138 @@
+import { apiClient } from "./client";
+
+export interface ToolInstance {
+  id: string;
+  name: string;
+  display_name: string;
+  tool_type_id: string;
+  tool_type_name: string;
+  tool_type_interfaces: string[];
+  status: string;
+  url: string | null;
+  port: number | null;
+  created_at: string;
+}
+
+export interface Session {
+  id: string;
+  display_name: string;
+  tool_type_name: string;
+  tool_icon: string;
+  tool_type_interfaces: string[];
+  repository_name: string;
+  repository_id: string;
+  project_name: string;
+  project_id: string;
+  status: string;
+  url: string | null;
+  container_status?: string;
+  probe_status?: string;
+}
+
+export async function listInstances(
+  projectId: string,
+  repoId: string
+): Promise<ToolInstance[]> {
+  const response = await apiClient.get(
+    `/projects/${projectId}/repositories/${repoId}/instances`
+  );
+  return response.data.instances;
+}
+
+export async function createInstance(
+  projectId: string,
+  repoId: string,
+  toolTypeId: string,
+  displayName?: string
+): Promise<ToolInstance> {
+  const response = await apiClient.post(
+    `/projects/${projectId}/repositories/${repoId}/instances`,
+    {
+      tool_type_id: toolTypeId,
+      display_name: displayName,
+    }
+  );
+  return response.data;
+}
+
+export async function startInstance(
+  projectId: string,
+  repoId: string,
+  instanceId: string
+): Promise<{ status: string; url?: string }> {
+  const response = await apiClient.post(
+    `/projects/${projectId}/repositories/${repoId}/instances/${instanceId}/start`
+  );
+  return response.data;
+}
+
+export async function stopInstance(
+  projectId: string,
+  repoId: string,
+  instanceId: string
+): Promise<{ status: string }> {
+  const response = await apiClient.post(
+    `/projects/${projectId}/repositories/${repoId}/instances/${instanceId}/stop`
+  );
+  return response.data;
+}
+
+export async function restartInstance(
+  projectId: string,
+  repoId: string,
+  instanceId: string
+): Promise<{ status: string; url?: string }> {
+  const response = await apiClient.post(
+    `/projects/${projectId}/repositories/${repoId}/instances/${instanceId}/restart`
+  );
+  return response.data;
+}
+
+export async function deleteInstance(
+  projectId: string,
+  repoId: string,
+  instanceId: string
+): Promise<void> {
+  await apiClient.delete(
+    `/projects/${projectId}/repositories/${repoId}/instances/${instanceId}`
+  );
+}
+
+export async function getUserSessions(): Promise<Session[]> {
+  const response = await apiClient.get("/users/me/sessions");
+  return response.data.sessions;
+}
+
+export interface InstanceHealth {
+  healthy: boolean;
+  container_status: string;
+  container_health: string | null;
+  container_exit_code: number | null;
+  tunnel_status: string;
+  tunnel_status_code: number | null;
+  probe_status: string;
+  last_probe_output: string | null;
+  error: string | null;
+}
+
+export async function checkInstanceHealth(
+  projectId: string,
+  repoId: string,
+  instanceId: string
+): Promise<InstanceHealth> {
+  const response = await apiClient.get(
+    `/projects/${projectId}/repositories/${repoId}/instances/${instanceId}/health`
+  );
+  return response.data;
+}
+
+export async function recreateInstanceTunnel(
+  projectId: string,
+  repoId: string,
+  instanceId: string
+): Promise<{ status: string; url?: string }> {
+  const response = await apiClient.post(
+    `/projects/${projectId}/repositories/${repoId}/instances/${instanceId}/recreate-tunnel`
+  );
+  return response.data;
+}

apps/web/src/api/settings.ts

@@ -5,13 +5,15 @@ export interface UserConfig {
   theme: string;
   git_user_name: string | null;
   git_user_email: string | null;
+  last_session_id: string | null;
 }
 
 export interface UserConfigUpdate {
-  default_editor?: string;
-  theme?: string;
-  git_user_name?: string;
-  git_user_email?: string;
+  default_editor?: string | null;
+  theme?: string | null;
+  git_user_name?: string | null;
+  git_user_email?: string | null;
+  last_session_id?: string | null;
 }
 
 export const getUserConfig = async (): Promise<UserConfig> => {

apps/web/src/api/tool_configs.ts

@@ -0,0 +1,75 @@
+import { apiClient } from "./client";
+
+export interface ToolConfig {
+  id: string;
+  tool_type_id: string;
+  project_id: string | null;
+  key: string;
+  value: string;
+  config_type: string;
+  file_path: string | null;
+  port_override: number | null;
+  start_command: string | null;
+  working_directory: string | null;
+  environment_variables: Record<string, string> | null;
+  volumes: Array<{ source: string; target: string; type?: string }> | null;
+}
+
+export interface CreateToolConfigRequest {
+  tool_type_id: string;
+  project_id?: string;
+  key: string;
+  value: string;
+  config_type?: string;
+  file_path?: string;
+  port_override?: number;
+  start_command?: string;
+  working_directory?: string;
+  environment_variables?: Record<string, string>;
+  volumes?: Array<{ source: string; target: string; type?: string }>;
+}
+
+export const listToolConfigs = async (
+  tool_type_id?: string,
+  project_id?: string
+): Promise<ToolConfig[]> => {
+  const params = new URLSearchParams();
+  if (tool_type_id) params.append("tool_type_id", tool_type_id);
+  if (project_id) params.append("project_id", project_id);
+  
+  const response = await apiClient.get<{ configs: ToolConfig[] }>(
+    `/tool-configs?${params.toString()}`
+  );
+  return response.data.configs;
+};
+
+export const createToolConfig = async (
+  data: CreateToolConfigRequest
+): Promise<ToolConfig> => {
+  const response = await apiClient.post<{ configs: ToolConfig[] }>("/tool-configs", data);
+  return response.data.configs[0];
+};
+
+export const updateToolConfig = async (
+  id: string,
+  data: CreateToolConfigRequest
+): Promise<ToolConfig> => {
+  const response = await apiClient.put<{ configs: ToolConfig[] }>(
+    `/tool-configs/${id}`,
+    data
+  );
+  return response.data.configs[0];
+};
+
+export const deleteToolConfig = async (id: string): Promise<void> => {
+  await apiClient.delete(`/tool-configs/${id}`);
+};
+
+export const getToolConfigDefaults = async (
+  toolTypeId: string
+): Promise<ToolConfig> => {
+  const response = await apiClient.get<ToolConfig>(
+    `/tool-configs/defaults/${toolTypeId}`
+  );
+  return response.data;
+};

apps/web/src/api/tool_types.test.ts

@@ -0,0 +1,227 @@
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  createToolType,
+  deleteToolType,
+  listToolTypes,
+  updateToolType,
+  validateToolType,
+} from "../api/tool_types";
+
+const mockGet = vi.fn();
+const mockPost = vi.fn();
+const mockPut = vi.fn();
+const mockDelete = vi.fn();
+
+vi.mock("../api/client", () => ({
+  apiClient: {
+    get: (...args: unknown[]) => mockGet(...args),
+    post: (...args: unknown[]) => mockPost(...args),
+    put: (...args: unknown[]) => mockPut(...args),
+    delete: (...args: unknown[]) => mockDelete(...args),
+    interceptors: {
+      response: {
+        use: vi.fn(),
+      },
+    },
+  },
+  shouldSkipAuthRedirect: vi.fn(() => false),
+}));
+
+describe("tool_types API", () => {
+  describe("listToolTypes", () => {
+    it("returns tool types with new fields", async () => {
+      const mockResponse = {
+        data: [
+          {
+            id: "type-1",
+            name: "custom-tool",
+            display_name: "Custom Tool",
+            definition_type: "dockerfile",
+            dockerfile_template: "FROM python:3.11",
+            readiness_probe: {
+              command: "python --version",
+              timeout: 30,
+              interval: 2,
+            },
+            build_context: null,
+            created_at: "2024-01-01T00:00:00Z",
+            updated_at: "2024-01-01T00:00:00Z",
+          },
+        ],
+      };
+      mockGet.mockResolvedValue(mockResponse);
+
+      const result = await listToolTypes();
+
+      expect(result[0].definition_type).toBe("dockerfile");
+      expect(result[0].dockerfile_template).toBe("FROM python:3.11");
+      expect(result[0].readiness_probe).toEqual({
+        command: "python --version",
+        timeout: 30,
+        interval: 2,
+      });
+    });
+
+    it("returns compose tool types", async () => {
+      const mockResponse = {
+        data: [
+          {
+            id: "type-1",
+            name: "code-server",
+            definition_type: "compose",
+            compose_template: "version: '3.8'",
+            dockerfile_template: null,
+            build_context: null,
+            created_at: "2024-01-01T00:00:00Z",
+            updated_at: "2024-01-01T00:00:00Z",
+          },
+        ],
+      };
+      mockGet.mockResolvedValue(mockResponse);
+
+      const result = await listToolTypes();
+
+      expect(result[0].definition_type).toBe("compose");
+      expect(result[0].dockerfile_template).toBeNull();
+    });
+  });
+
+  describe("createToolType", () => {
+    it("creates tool type with dockerfile", async () => {
+      const mockResponse = {
+        data: {
+          id: "new-type",
+          name: "docker-tool",
+          definition_type: "dockerfile",
+          dockerfile_template: "FROM node:18",
+          build_context: null,
+          created_at: "2024-01-01T00:00:00Z",
+          updated_at: "2024-01-01T00:00:00Z",
+        },
+      };
+      mockPost.mockResolvedValue(mockResponse);
+
+      const result = await createToolType({
+        name: "docker-tool",
+        display_name: "Docker Tool",
+        definition_type: "dockerfile",
+        dockerfile_template: "FROM node:18",
+        default_port: 3000,
+        required_variables: [],
+      });
+
+      expect(result.definition_type).toBe("dockerfile");
+      expect(mockPost).toHaveBeenCalledWith(
+        "/tool-types",
+        expect.objectContaining({
+          definition_type: "dockerfile",
+          dockerfile_template: "FROM node:18",
+        })
+      );
+    });
+
+    it("creates tool type with readiness probe", async () => {
+      const mockResponse = {
+        data: {
+          id: "new-type",
+          name: "probed-tool",
+          readiness_probe: {
+            command: "curl -f http://localhost:8080",
+            timeout: 60,
+            interval: 3,
+          },
+          build_context: null,
+          created_at: "2024-01-01T00:00:00Z",
+          updated_at: "2024-01-01T00:00:00Z",
+        },
+      };
+      mockPost.mockResolvedValue(mockResponse);
+
+      const result = await createToolType({
+        name: "probed-tool",
+        display_name: "Probed Tool",
+        compose_template: "version: '3.8'",
+        default_port: 8080,
+        required_variables: [],
+        readiness_probe: {
+          command: "curl -f http://localhost:8080",
+          timeout: 60,
+          interval: 3,
+        },
+      });
+
+      expect(result.readiness_probe).toEqual({
+        command: "curl -f http://localhost:8080",
+        timeout: 60,
+        interval: 3,
+      });
+    });
+  });
+
+  describe("validateToolType", () => {
+    it("validates tool type by id", async () => {
+      const mockResponse = {
+        data: { valid: true, errors: [] },
+      };
+      mockGet.mockResolvedValue(mockResponse);
+
+      const result = await validateToolType("type-1");
+
+      expect(result.valid).toBe(true);
+      expect(mockGet).toHaveBeenCalledWith("/tool-types/type-1/validate");
+    });
+
+    it("returns validation errors", async () => {
+      const mockResponse = {
+        data: { valid: false, errors: ["Invalid YAML"] },
+      };
+      mockGet.mockResolvedValue(mockResponse);
+
+      const result = await validateToolType("type-1");
+
+      expect(result.valid).toBe(false);
+      expect(result.errors).toContain("Invalid YAML");
+    });
+  });
+
+  describe("updateToolType", () => {
+    it("updates tool type with new fields", async () => {
+      const mockResponse = {
+        data: {
+          id: "type-1",
+          name: "updated-tool",
+          definition_type: "dockerfile",
+          dockerfile_template: "FROM python:3.11",
+          build_context: null,
+          created_at: "2024-01-01T00:00:00Z",
+          updated_at: "2024-01-01T00:00:00Z",
+        },
+      };
+      mockPut.mockResolvedValue(mockResponse);
+
+      const result = await updateToolType("type-1", {
+        definition_type: "dockerfile",
+        dockerfile_template: "FROM python:3.11",
+      });
+
+      expect(result.definition_type).toBe("dockerfile");
+      expect(mockPut).toHaveBeenCalledWith(
+        "/tool-types/type-1",
+        expect.objectContaining({
+          definition_type: "dockerfile",
+        })
+      );
+    });
+  });
+
+  describe("deleteToolType", () => {
+    it("deletes tool type", async () => {
+      mockDelete.mockResolvedValue({ data: undefined });
+
+      await deleteToolType("type-1");
+
+      expect(mockDelete).toHaveBeenCalledWith("/tool-types/type-1");
+    });
+  });
+});

apps/web/src/api/tool_types.ts

@@ -1,11 +1,24 @@
 import { apiClient } from "./client";
 
+export interface ReadinessProbe {
+  command: string;
+  timeout: number;
+  interval: number;
+}
+
 export interface ToolType {
   id: string;
   name: string;
   display_name: string;
   description: string | null;
-  compose_template: string;
+  category: string;
+  interfaces: string[];
+  default_port: number | null;
+  definition_type: 'compose' | 'dockerfile';
+  compose_template: string | null;
+  dockerfile_template: string | null;
+  build_context: Record<string, string> | null;
+  readiness_probe: ReadinessProbe | null;
   required_variables: string[];
   is_builtin: boolean;
   created_by_id: string | null;
@@ -17,14 +30,28 @@ export interface CreateToolTypeRequest {
   name: string;
   display_name: string;
   description?: string;
-  compose_template: string;
+  category?: string;
+  interfaces?: string[];
+  default_port: number;
+  definition_type?: 'compose' | 'dockerfile';
+  compose_template?: string;
+  dockerfile_template?: string;
+  build_context?: Record<string, string>;
+  readiness_probe?: ReadinessProbe;
   required_variables: string[];
 }
 
 export interface UpdateToolTypeRequest {
   display_name?: string;
   description?: string;
+  category?: string;
+  interfaces?: string[];
+  default_port?: number;
+  definition_type?: 'compose' | 'dockerfile';
   compose_template?: string;
+  dockerfile_template?: string;
+  build_context?: Record<string, string>;
+  readiness_probe?: ReadinessProbe;
   required_variables?: string[];
 }
 
@@ -51,3 +78,8 @@ export const updateToolType = async (id: string, data: UpdateToolTypeRequest): P
 export const deleteToolType = async (id: string): Promise<void> => {
   await apiClient.delete(`/tool-types/${id}`);
 };
+
+export const validateToolType = async (id: string): Promise<{ valid: boolean; errors?: string[] }> => {
+  const response = await apiClient.get<{ valid: boolean; errors?: string[] }>(`/tool-types/${id}/validate`);
+  return response.data;
+};

apps/web/src/components/app-shell.tsx

@@ -1,19 +1,61 @@
+import { useCallback, useEffect } from "react";
 import { Link, NavLink, Outlet } from "react-router-dom";
 
+import { getUserSessions } from "../api/sessions";
+import type { Session } from "../api/sessions";
 import { useTheme } from "../hooks/use-theme";
 import { useAuth } from "../state/auth";
+import { useSessions } from "../state/sessions";
+import { Icon } from "./icon";
+import type { IconName } from "../utils/icons";
 
-const NAV_ITEMS = [
-  { to: "/", label: "Dashboard" },
-  { to: "/projects", label: "Projects" },
-  { to: "/ssh-keys", label: "SSH Keys" },
-  { to: "/tool-types", label: "Tool Types" },
-  { to: "/settings", label: "Settings" }
+const NAV_ITEMS: { to: string; label: string; icon: IconName }[] = [
+  { to: "/", label: "Home", icon: "dashboard" },
+  { to: "/projects", label: "Projects", icon: "projects" },
+  { to: "/tool-workshop", label: "Tool Workshop", icon: "settings" },
+  { to: "/settings", label: "Settings", icon: "settings" }
 ];
 
+const SessionItem = ({ session }: { session: Session }) => {
+  const isRunning = session.status === "running";
+
+  return (
+    <a
+      href={session.url ?? `/projects/${session.project_id}`}
+      target={session.url ? "_blank" : undefined}
+      rel={session.url ? "noopener noreferrer" : undefined}
+      className="nav-item session-item"
+      title={`${session.display_name} (${session.status})`}
+    >
+      <span className={`session-status ${isRunning ? "running" : ""}`} />
+      <Icon name={session.tool_icon as IconName} size="sm" />
+      <span className="session-name">{session.display_name}</span>
+    </a>
+  );
+};
+
 export const AppShell = () => {
   useTheme();
   const { user, logout } = useAuth();
+  const { sessions, setAllSessions } = useSessions();
+
+  const loadSessions = useCallback(async () => {
+    try {
+      const data = await getUserSessions();
+      setAllSessions(data);
+    } catch {
+      // Silently fail - sessions are optional
+    }
+  }, [setAllSessions]);
+
+  useEffect(() => {
+    void loadSessions();
+    // Poll every 10 seconds
+    const interval = setInterval(() => {
+      void loadSessions();
+    }, 10000);
+    return () => clearInterval(interval);
+  }, [loadSessions]);
 
   return (
     <div className="shell">
@@ -32,6 +74,7 @@ export const AppShell = () => {
             }}
             type="button"
           >
+            <Icon name="logout" size="sm" />
             Logout
           </button>
         </div>
@@ -39,16 +82,34 @@ export const AppShell = () => {
 
       <div className="shell-body">
         <aside className="shell-nav" aria-label="Primary navigation">
-          {NAV_ITEMS.map((item) => (
+          {NAV_ITEMS.map((item) => {
+            const isHome = item.to === "/";
+            const activeCount = sessions.filter((s) => s.status === "running").length;
+            return (
               <NavLink
                 key={item.to}
                 to={item.to}
                 className={({ isActive }) => (isActive ? "nav-item nav-item-active" : "nav-item")}
                 end={item.to === "/"}
               >
+                <Icon name={item.icon} size="sm" />
                 {item.label}
+                {isHome && activeCount > 0 && (
+                  <span className="nav-badge">{activeCount}</span>
+                )}
               </NavLink>
+            );
+          })}
+          
+          {sessions.length > 0 && (
+            <>
+              <div className="nav-divider" />
+              <div className="nav-section-title">Live sessions</div>
+              {sessions.map((session) => (
+                <SessionItem key={session.id} session={session} />
               ))}
+            </>
+          )}
         </aside>
 
         <main className="shell-content">

apps/web/src/components/code-editor.tsx

@@ -0,0 +1,56 @@
+import React, { useEffect } from "react";
+import Editor from "react-simple-code-editor";
+import { highlightCode, loadLanguage } from "../utils/language";
+
+interface CodeEditorProps {
+  value: string;
+  onChange: (value: string) => void;
+  language: string;
+  readOnly?: boolean;
+}
+
+export const CodeEditor: React.FC<CodeEditorProps> = ({
+  value,
+  onChange,
+  language,
+  readOnly = false,
+}) => {
+  useEffect(() => {
+    const highlight = async () => {
+      await loadLanguage(language);
+    };
+    void highlight();
+  }, [language]);
+
+  const hightlightWithLineNumbers = (input: string) =>
+    input
+      .split("\n")
+      .map(
+        (line, i) =>
+          `<div class="editor-line"><span class="editor-line-number">${
+            i + 1
+          }</span><span class="editor-line-content">${highlightCode(
+            line || " ",
+            language
+          )}</span></div>`
+      )
+      .join("");
+
+  return (
+    <div className="code-editor">
+      <Editor
+        value={value}
+        onValueChange={onChange}
+        highlight={hightlightWithLineNumbers}
+        padding={0}
+        className="editor-textarea"
+        textareaClassName="editor-textarea-input"
+        readOnly={readOnly}
+        style={{
+          fontFamily: '"Fira Code", "Monaco", "Courier New", monospace',
+          fontSize: 14,
+        }}
+      />
+    </div>
+  );
+};

apps/web/src/components/commit-dialog.tsx

@@ -0,0 +1,159 @@
+import React, { useState } from "react";
+
+import { Icon } from "./icon";
+
+interface CommitDialogProps {
+  isOpen: boolean;
+  filePath: string;
+  originalContent: string;
+  newContent: string;
+  onCommit: (message: string) => Promise<void>;
+  onCancel: () => void;
+}
+
+export const CommitDialog: React.FC<CommitDialogProps> = ({
+  isOpen,
+  filePath,
+  originalContent,
+  newContent,
+  onCommit,
+  onCancel,
+}) => {
+  const [message, setMessage] = useState("");
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState(">");
+
+  if (!isOpen) return null;
+
+  const generateDiff = () => {
+    const originalLines = originalContent.split("\n");
+    const newLines = newContent.split("\n");
+    const maxLines = Math.max(originalLines.length, newLines.length);
+    const diff: { type: "same" | "added" | "removed"; line: string; lineNum: number }[] = [];
+
+    for (let i = 0; i < maxLines; i++) {
+      const original = originalLines[i] || "";
+      const updated = newLines[i] || "";
+
+      if (original === updated) {
+        diff.push({ type: "same", line: updated, lineNum: i + 1 });
+      } else {
+        if (original) {
+          diff.push({ type: "removed", line: original, lineNum: i + 1 });
+        }
+        if (updated) {
+          diff.push({ type: "added", line: updated, lineNum: i + 1 });
+        }
+      }
+    }
+
+    return diff;
+  };
+
+  const handleCommit = async () => {
+    if (!message.trim()) {
+      setError("Please enter a commit message");
+      return;
+    }
+
+    setLoading(true);
+    setError("");
+    try {
+      await onCommit(message);
+    } catch {
+      setError("Failed to commit changes");
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const diff = generateDiff();
+  const hasChanges = diff.some((d) => d.type !== "same");
+
+  return (
+    <div className="dialog-overlay">
+      <div className="commit-dialog">
+        <div className="dialog-header">
+          <h3>Commit Changes</h3>
+          <button className="dialog-close" onClick={onCancel} type="button">
+            ×
+          </button>
+        </div>
+
+        <div className="dialog-body">
+          <p className="file-info">
+            Editing: <strong>{filePath}</strong>
+          </p>
+
+          {!hasChanges && (
+            <div className="warning-message">No changes to commit</div>
+          )}
+
+          {hasChanges && (
+            <div className="diff-preview">
+              <h4>Changes</h4>
+              <div className="diff-content">
+                {diff.map((line, i) => (
+                  <div
+                    key={i}
+                    className={`diff-line diff-${line.type}`}
+                  >
+                    <span className="diff-line-number">{line.lineNum}</span>
+                    <span className="diff-marker">
+                      {line.type === "added" && "+"}
+                      {line.type === "removed" && "-"}
+                      {line.type === "same" && " "}
+                    </span>
+                    <span className="diff-line-content">{line.line}</span>
+                  </div>
+                ))}
+              </div>
+            </div>
+          )}
+
+          <div className="form-group">
+            <label>Commit Message *</label>
+            <textarea
+              value={message}
+              onChange={(e) => setMessage(e.target.value)}
+              placeholder="Describe your changes..."
+              rows={3}
+              className="form-textarea"
+            />
+          </div>
+
+          {error && <div className="error-message">{error}</div>}
+        </div>
+
+        <div className="dialog-footer">
+          <button
+            className="btn-secondary"
+            onClick={onCancel}
+            type="button"
+          >
+            <Icon name="cancel" size="sm" />
+            Cancel
+          </button>
+          <button
+            className="btn-primary"
+            onClick={handleCommit}
+            disabled={loading || !hasChanges || !message.trim()}
+            type="button"
+          >
+            {loading ? (
+              <>
+                <Icon name="loading" size="sm" />
+                Committing...
+              </>
+            ) : (
+              <>
+                <Icon name="commit" size="sm" />
+                Commit Changes
+              </>
+            )}
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+};

apps/web/src/components/commit-panel.tsx

@@ -0,0 +1,102 @@
+import { useState } from "react";
+
+import { commitChanges } from "../api/git_repositories";
+
+interface CommitPanelProps {
+  projectId: string;
+  repoId: string;
+  modified: string[];
+  added: string[];
+  deleted: string[];
+  untracked: string[];
+  onCommit: () => void;
+}
+
+export const CommitPanel = ({
+  projectId,
+  repoId,
+  modified,
+  added,
+  deleted,
+  untracked,
+  onCommit,
+}: CommitPanelProps) => {
+  const [message, setMessage] = useState("");
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const allFiles = [...modified, ...added, ...deleted, ...untracked];
+  const hasChanges = allFiles.length > 0;
+
+  const handleCommit = async () => {
+    if (!message.trim()) {
+      setError("Please enter a commit message");
+      return;
+    }
+    setLoading(true);
+    setError(null);
+    try {
+      await commitChanges(projectId, repoId, message);
+      setMessage("");
+      onCommit();
+    } catch {
+      setError("Commit failed. Please try again.");
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  if (!hasChanges) return null;
+
+  return (
+    <div className="commit-panel">
+      <h4>Changes</h4>
+      
+      <div className="file-list">
+        {modified.map((file) => (
+          <div key={file} className="file-item modified">
+            <span className="file-status">M</span>
+            <span className="file-name">{file}</span>
+          </div>
+        ))}
+        {added.map((file) => (
+          <div key={file} className="file-item added">
+            <span className="file-status">A</span>
+            <span className="file-name">{file}</span>
+          </div>
+        ))}
+        {deleted.map((file) => (
+          <div key={file} className="file-item deleted">
+            <span className="file-status">D</span>
+            <span className="file-name">{file}</span>
+          </div>
+        ))}
+        {untracked.map((file) => (
+          <div key={file} className="file-item untracked">
+            <span className="file-status">?</span>
+            <span className="file-name">{file}</span>
+          </div>
+        ))}
+      </div>
+
+      <div className="commit-form">
+        <textarea
+          placeholder="Commit message"
+          value={message}
+          onChange={(e) => setMessage(e.target.value)}
+          rows={2}
+          className="commit-message-input"
+        />
+        {error && <div className="commit-error">{error}</div>}
+        <button
+          onClick={handleCommit}
+          disabled={loading || !message.trim()}
+          className="commit-button"
+          type="button"
+        >
+          {loading ? "Committing..." : "Commit"}
+        </button>
+      </div>
+    </div>
+  );
+};

apps/web/src/components/file-editor.tsx

@@ -0,0 +1,241 @@
+import React, { useCallback, useEffect, useState } from "react";
+import { useSearchParams } from "react-router-dom";
+import { apiClient } from "../api/client";
+import { useAuth } from "../state/auth";
+import { CodeEditor } from "../components/code-editor";
+import { CommitDialog } from "../components/commit-dialog";
+import { Icon } from "../components/icon";
+import { SyntaxHighlighter } from "../components/syntax-highlighter";
+import { detectLanguage } from "../utils/language";
+
+interface FileEditorProps {
+  projectId: string;
+  repoId: string;
+}
+
+export const FileEditor: React.FC<FileEditorProps> = ({
+  projectId,
+  repoId,
+}) => {
+  const [searchParams] = useSearchParams();
+  const { user } = useAuth();
+
+  const [mode, setMode] = useState<"view" | "edit">("view");
+  const [content, setContent] = useState(">");
+  const [originalContent, setOriginalContent] = useState(">");
+  const [language, setLanguage] = useState("plaintext");
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [showCommitDialog, setShowCommitDialog] = useState(false);
+  const [isBinary, setIsBinary] = useState(false);
+  const [saving, setSaving] = useState(false);
+
+  const branch = searchParams.get("branch") || "main";
+  const filePath = searchParams.get("file");
+
+  const loadFile = useCallback(async () => {
+    if (!filePath) {
+      setContent("");
+      setOriginalContent("");
+      return;
+    }
+
+    setLoading(true);
+    setError(null);
+    try {
+      const response = await apiClient.get(
+        `/projects/${projectId}/repositories/${repoId}/files/content`,
+        {
+          params: {
+            branch,
+            path: filePath,
+          },
+        }
+      );
+      const data = response.data;
+      if (data.is_binary) {
+        setIsBinary(true);
+        setContent("Binary file - cannot display");
+        setOriginalContent("");
+      } else {
+        setIsBinary(false);
+        setContent(data.content);
+        setOriginalContent(data.content);
+        setLanguage(detectLanguage(filePath));
+      }
+    } catch {
+      setError("Failed to load file");
+    } finally {
+      setLoading(false);
+    }
+  }, [projectId, repoId, branch, filePath]);
+
+  useEffect(() => {
+    void loadFile();
+  }, [loadFile]);
+
+  const handleEdit = () => {
+    if (isBinary) return;
+    setMode("edit");
+  };
+
+  const handleCancel = () => {
+    setContent(originalContent);
+    setMode("view");
+    setShowCommitDialog(false);
+  };
+
+  const handleSave = () => {
+    if (content === originalContent) {
+      setMode("view");
+      return;
+    }
+    setShowCommitDialog(true);
+  };
+
+  const handleCommit = async (message: string) => {
+    if (!filePath || !user) return;
+
+    setSaving(true);
+    try {
+      await apiClient.post(
+        `/projects/${projectId}/repositories/${repoId}/files/content`,
+        {
+          path: filePath,
+          branch,
+          content,
+          commit_message: message,
+          author_name: user.name || "User",
+          author_email: user.email || "user@example.com",
+        }
+      );
+      setOriginalContent(content);
+      setMode("view");
+      setShowCommitDialog(false);
+    } catch {
+      setError("Failed to save changes");
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  // Keyboard shortcuts
+  useEffect(() => {
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if ((e.ctrlKey || e.metaKey) && e.key === "e") {
+        e.preventDefault();
+        if (mode === "view" && !isBinary) {
+          handleEdit();
+        } else if (mode === "edit") {
+          handleCancel();
+        }
+      }
+      if ((e.ctrlKey || e.metaKey) && e.key === "s") {
+        e.preventDefault();
+        if (mode === "edit") {
+          handleSave();
+        }
+      }
+    };
+
+    window.addEventListener("keydown", handleKeyDown);
+    return () => window.removeEventListener("keydown", handleKeyDown);
+  }, [mode, isBinary, content, originalContent]);
+
+  if (!filePath) {
+    return (
+      <div className="file-viewer-empty">
+        <p className="muted">Select a file to view its contents</p>
+      </div>
+    );
+  }
+
+  if (loading) return <p className="muted">Loading file...</p>;
+  if (error) return <p className="error-text">{error}</p>;
+
+  return (
+    <div className="file-editor">
+      <div className="file-editor-toolbar">
+        <div className="file-breadcrumbs">
+          {filePath.split("/").map((part, i, arr) => (
+            <span key={i}>
+              {part}
+              {i < arr.length - 1 && (
+                <span className="breadcrumb-sep">/</span>
+              )}
+            </span>
+          ))}
+        </div>
+        <div className="file-actions">
+          {mode === "view" && !isBinary && (
+            <button
+              className="btn-primary"
+              onClick={handleEdit}
+              type="button"
+            >
+              <Icon name="edit" size="sm" />
+              Edit
+            </button>
+          )}
+          {mode === "edit" && (
+            <>
+          <button
+            className="btn-primary"
+            onClick={handleSave}
+            disabled={content === originalContent || saving}
+            type="button"
+          >
+            {saving ? (
+              <>
+                <Icon name="loading" size="sm" />
+                Saving...
+              </>
+            ) : (
+              <>
+                <Icon name="save" size="sm" />
+                Save
+              </>
+            )}
+          </button>
+              <button
+                className="btn-secondary"
+                onClick={handleCancel}
+                type="button"
+              >
+                <Icon name="cancel" size="sm" />
+                Cancel
+              </button>
+            </>
+          )}
+        </div>
+      </div>
+
+      <div className="file-editor-content">
+        {mode === "view" && (
+          <SyntaxHighlighter
+            code={content}
+            language={language}
+            showLineNumbers={!isBinary}
+          />
+        )}
+
+        {mode === "edit" && (
+          <CodeEditor
+            value={content}
+            onChange={setContent}
+            language={language}
+          />
+        )}
+      </div>
+
+      <CommitDialog
+        isOpen={showCommitDialog}
+        filePath={filePath}
+        originalContent={originalContent}
+        newContent={content}
+        onCommit={handleCommit}
+        onCancel={() => setShowCommitDialog(false)}
+      />
+    </div>
+  );
+};

apps/web/src/components/git-toolbar.tsx

@@ -0,0 +1,268 @@
+import { useCallback, useEffect, useState } from "react";
+
+import {
+  checkoutBranch,
+  createBranch,
+  fetchRepository,
+  getRepositoryStatus,
+  pullRepository,
+  pushRepository,
+  type GitStatus,
+} from "../api/git_repositories";
+import { Icon } from "./icon";
+import { MergeDialog } from "./merge-dialog";
+
+interface GitToolbarProps {
+  projectId: string;
+  repoId: string;
+  currentBranch: string;
+  branches: string[];
+  hasRemote: boolean;
+  onBranchChange: (branch: string) => void;
+  onRefresh: () => void;
+}
+
+export const GitToolbar = ({
+  projectId,
+  repoId,
+  currentBranch,
+  branches,
+  hasRemote,
+  onBranchChange,
+  onRefresh,
+}: GitToolbarProps) => {
+  const [status, setStatus] = useState<GitStatus | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [showNewBranch, setShowNewBranch] = useState(false);
+  const [newBranchName, setNewBranchName] = useState("");
+  const [newBranchBase, setNewBranchBase] = useState("");
+  const [showMergeDialog, setShowMergeDialog] = useState(false);
+
+  const loadStatus = useCallback(async () => {
+    try {
+      const data = await getRepositoryStatus(projectId, repoId);
+      setStatus(data);
+      setError(null);
+    } catch {
+      setError("Failed to load status");
+    }
+  }, [projectId, repoId]);
+
+  useEffect(() => {
+    void loadStatus();
+    // Poll status every 5 seconds
+    const interval = setInterval(() => void loadStatus(), 5000);
+    return () => clearInterval(interval);
+  }, [loadStatus]);
+
+  const handleFetch = async () => {
+    if (!hasRemote) return;
+    setLoading(true);
+    try {
+      await fetchRepository(projectId, repoId);
+      await loadStatus();
+    } catch {
+      setError("Fetch failed");
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const handlePull = async () => {
+    if (!hasRemote) return;
+    setLoading(true);
+    try {
+      await pullRepository(projectId, repoId, currentBranch || undefined);
+      await loadStatus();
+      onRefresh();
+    } catch {
+      setError("Pull failed");
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const handlePush = async () => {
+    setLoading(true);
+    try {
+      await pushRepository(projectId, repoId, currentBranch);
+      await loadStatus();
+    } catch {
+      setError("Push failed");
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const handleCheckout = async (branch: string) => {
+    setLoading(true);
+    try {
+      await checkoutBranch(projectId, repoId, branch);
+      onBranchChange(branch);
+      onRefresh();
+    } catch {
+      setError("Checkout failed");
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const handleCreateBranch = async () => {
+    if (!newBranchName.trim()) return;
+    setLoading(true);
+    try {
+      await createBranch(projectId, repoId, newBranchName, newBranchBase || currentBranch || "HEAD");
+      setShowNewBranch(false);
+      setNewBranchName("");
+      setNewBranchBase("");
+      onRefresh();
+    } catch {
+      setError("Failed to create branch");
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const hasChanges = status && (
+    status.modified.length > 0 ||
+    status.added.length > 0 ||
+    status.deleted.length > 0 ||
+    status.untracked.length > 0
+  );
+
+  const canSync = hasRemote;
+
+  return (
+    <div className="git-toolbar">
+      {error && <div className="toolbar-error">{error}</div>}
+      
+      <div className="toolbar-row">
+        <div className="toolbar-group">
+          <select
+            value={currentBranch}
+            onChange={(e) => handleCheckout(e.target.value)}
+            disabled={loading}
+            className="branch-select"
+          >
+            {branches.map((b) => (
+              <option key={b} value={b}>
+                {b === currentBranch ? (
+                  <>
+                    <Icon name="branch" size="sm" /> {b}
+                  </>
+                ) : (
+                  b
+                )}
+              </option>
+            ))}
+          </select>
+          <button
+            className="toolbar-button"
+            onClick={() => setShowNewBranch(!showNewBranch)}
+            disabled={loading}
+            type="button"
+          >
+            <Icon name="add" size="sm" /> New
+          </button>
+        </div>
+
+        <div className="toolbar-group">
+          <button
+            className="toolbar-button"
+            onClick={handleFetch}
+            disabled={loading || !canSync}
+            type="button"
+          >
+            <Icon name="fetch" size="sm" /> Fetch
+          </button>
+          <button
+            className="toolbar-button"
+            onClick={handlePull}
+            disabled={loading || !canSync}
+            type="button"
+          >
+            <Icon name="pull" size="sm" /> Pull
+            {status?.behind ? <span className="badge">{status.behind}</span> : null}
+          </button>
+          <button
+            className="toolbar-button"
+            onClick={handlePush}
+            disabled={loading || !canSync || !status?.ahead}
+            type="button"
+          >
+            <Icon name="push" size="sm" /> Push
+            {status?.ahead ? <span className="badge">{status.ahead}</span> : null}
+          </button>
+          <button
+            className="toolbar-button"
+            onClick={() => setShowMergeDialog(true)}
+            disabled={loading}
+            type="button"
+          >
+            <Icon name="merge" size="sm" /> Merge
+          </button>
+        </div>
+      </div>
+
+      {showNewBranch && (
+        <div className="toolbar-row new-branch-form">
+          <input
+            type="text"
+            placeholder="Branch name"
+            value={newBranchName}
+            onChange={(e) => setNewBranchName(e.target.value)}
+            className="toolbar-input"
+          />
+          <select
+            value={newBranchBase}
+            onChange={(e) => setNewBranchBase(e.target.value)}
+            className="toolbar-input"
+          >
+            <option value="">Base: HEAD</option>
+            {branches.map((b) => (
+              <option key={b} value={b}>{ b}</option>
+            ))}
+          </select>
+          <button
+            className="toolbar-button primary"
+            onClick={handleCreateBranch}
+            disabled={loading || !newBranchName.trim()}
+            type="button"
+          >
+            <Icon name="add" size="sm" /> Create
+          </button>
+          <button
+            className="toolbar-button"
+            onClick={() => setShowNewBranch(false)}
+            type="button"
+          >
+            <Icon name="cancel" size="sm" /> Cancel
+          </button>
+        </div>
+      )}
+
+      {hasChanges && status && (
+        <div className="toolbar-row status-summary">
+          {status.modified.length > 0 && <span className="status-badge modified"><Icon name="edit" size="sm" /> {status.modified.length} modified</span>}
+          {status.added.length > 0 && <span className="status-badge added"><Icon name="add" size="sm" /> {status.added.length} added</span>}
+          {status.deleted.length > 0 && <span className="status-badge deleted"><Icon name="delete" size="sm" /> {status.deleted.length} deleted</span>}
+          {status.untracked.length > 0 && <span className="status-badge untracked"><Icon name="warning" size="sm" /> {status.untracked.length} untracked</span>}
+        </div>
+      )}
+
+      <MergeDialog
+        projectId={projectId}
+        repoId={repoId}
+        branches={branches}
+        currentBranch={currentBranch}
+        isOpen={showMergeDialog}
+        onClose={() => setShowMergeDialog(false)}
+        onMerge={() => {
+          void loadStatus();
+          onRefresh();
+        }}
+      />
+    </div>
+  );
+};

apps/web/src/components/icon.tsx

@@ -0,0 +1,165 @@
+import React from "react";
+import {
+  House,
+  Folder,
+  GitBranch,
+  Gear,
+  User,
+  SignOut,
+  Plus,
+  PencilSimple,
+  Trash,
+  FloppyDisk,
+  X,
+  ArrowsClockwise,
+  Copy,
+  MagnifyingGlass,
+  List,
+  Check,
+  Warning,
+  Info,
+  Spinner,
+  GitCommit,
+  GitMerge,
+  ClockCounterClockwise,
+  ArrowDown,
+  ArrowUp,
+  File,
+  FileText,
+  Image,
+  Binary,
+  Code,
+  ArrowSquareOut,
+  Play,
+  Stop,
+  Terminal,
+  ArrowLeft,
+} from "@phosphor-icons/react";
+
+export type IconName =
+  | "dashboard"
+  | "projects"
+  | "repositories"
+  | "settings"
+  | "profile"
+  | "logout"
+  | "add"
+  | "edit"
+  | "delete"
+  | "save"
+  | "cancel"
+  | "refresh"
+  | "copy"
+  | "search"
+  | "menu"
+  | "close"
+  | "success"
+  | "error"
+  | "warning"
+  | "info"
+  | "loading"
+  | "branch"
+  | "commit"
+  | "merge"
+  | "history"
+  | "pull"
+  | "push"
+  | "fetch"
+  | "file"
+  | "folder"
+  | "code"
+  | "document"
+  | "image"
+  | "binary"
+  | "external"
+  | "play"
+  | "stop"
+  | "terminal"
+  | "arrow-left";
+
+const iconMap: Record<IconName, React.ComponentType<{ size?: number | string; weight?: "thin" | "light" | "regular" | "bold" | "fill" | "duotone" }>> = {
+  dashboard: House,
+  projects: Folder,
+  repositories: GitBranch,
+  settings: Gear,
+  profile: User,
+  logout: SignOut,
+  add: Plus,
+  edit: PencilSimple,
+  delete: Trash,
+  save: FloppyDisk,
+  cancel: X,
+  refresh: ArrowsClockwise,
+  copy: Copy,
+  search: MagnifyingGlass,
+  menu: List,
+  close: X,
+  success: Check,
+  error: X,
+  warning: Warning,
+  info: Info,
+  loading: Spinner,
+  branch: GitBranch,
+  commit: GitCommit,
+  merge: GitMerge,
+  history: ClockCounterClockwise,
+  pull: ArrowDown,
+  push: ArrowUp,
+  fetch: ArrowsClockwise,
+  file: File,
+  folder: Folder,
+  code: Code,
+  document: FileText,
+  image: Image,
+  binary: Binary,
+  external: ArrowSquareOut,
+  play: Play,
+  stop: Stop,
+  terminal: Terminal,
+  "arrow-left": ArrowLeft,
+};
+
+export interface IconProps {
+  name: IconName;
+  size?: "sm" | "md" | "lg" | "xl";
+  color?: string;
+  weight?: "thin" | "light" | "regular" | "bold" | "fill" | "duotone";
+  className?: string;
+  ariaLabel?: string;
+}
+
+const sizeMap: Record<NonNullable<IconProps["size"]>, number> = {
+  sm: 16,
+  md: 20,
+  lg: 24,
+  xl: 32,
+};
+
+export const Icon: React.FC<IconProps> = ({
+  name,
+  size = "md",
+  color,
+  weight = "regular",
+  className,
+  ariaLabel,
+}) => {
+  const IconComponent = iconMap[name];
+  const sizeValue = sizeMap[size];
+
+  if (!IconComponent) {
+    console.warn(`Icon "${name}" not found`);
+    return null;
+  }
+
+  return (
+    <span
+      className={`icon icon-${size}${className ? ` ${className}` : ""}`}
+      style={{ color }}
+      aria-label={ariaLabel}
+      aria-hidden={!ariaLabel}
+      role="img"
+    >
+      <IconComponent size={sizeValue} weight={weight} />
+    </span>
+  );
+};

apps/web/src/components/instance-list.tsx

@@ -0,0 +1,359 @@
+import { useCallback, useEffect, useState } from "react";
+import { useNavigate } from "react-router-dom";
+import { Icon } from "./icon";
+import type { ToolInstance } from "../api/sessions";
+import {
+  checkInstanceHealth,
+  createInstance,
+  deleteInstance,
+  listInstances,
+  recreateInstanceTunnel,
+  restartInstance,
+  startInstance,
+  stopInstance,
+} from "../api/sessions";
+import type { ToolType } from "../api/tool_types";
+
+const API_BASE_URL = import.meta.env.VITE_API_BASE_URL ?? "http://localhost:8000";
+
+interface InstanceListProps {
+  projectId: string;
+  repoId: string;
+  toolTypes: ToolType[];
+}
+
+export const InstanceList = ({ projectId, repoId, toolTypes }: InstanceListProps) => {
+  const navigate = useNavigate();
+  const [instances, setInstances] = useState<ToolInstance[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [showCreate, setShowCreate] = useState(false);
+  const [selectedToolType, setSelectedToolType] = useState("");
+  const [displayName, setDisplayName] = useState("");
+  const [error, setError] = useState<string | null>(null);
+  
+  // Stop confirmation
+  const [stopConfirmId, setStopConfirmId] = useState<string | null>(null);
+  
+  // Health check state
+  const [healthStatus, setHealthStatus] = useState<Record<string, { healthy: boolean; lastCheck: number }>>({});
+
+  const loadInstances = useCallback(async () => {
+    setLoading(true);
+    try {
+      const data = await listInstances(projectId, repoId);
+      setInstances(data);
+    } catch {
+      setError("Failed to load instances");
+    } finally {
+      setLoading(false);
+    }
+  }, [projectId, repoId]);
+
+  useEffect(() => {
+    void loadInstances();
+  }, [loadInstances]);
+
+  // Health check polling
+  useEffect(() => {
+    const runningInstances = instances.filter(i => i.status === "running" && i.url?.startsWith("http"));
+    if (runningInstances.length === 0) return;
+
+    const checkHealth = async () => {
+      for (const instance of runningInstances) {
+        try {
+          const health = await checkInstanceHealth(projectId, repoId, instance.id);
+          setHealthStatus(prev => ({
+            ...prev,
+            [instance.id]: { healthy: health.healthy, lastCheck: Date.now() }
+          }));
+        } catch {
+          setHealthStatus(prev => ({
+            ...prev,
+            [instance.id]: { healthy: false, lastCheck: Date.now() }
+          }));
+        }
+      }
+    };
+
+    // Check immediately
+    void checkHealth();
+    
+    // Then every 30 seconds
+    const interval = setInterval(() => void checkHealth(), 30000);
+    return () => clearInterval(interval);
+  }, [instances, projectId, repoId]);
+
+  const handleCreate = async () => {
+    if (!selectedToolType) return;
+    setError(null);
+    try {
+      await createInstance(projectId, repoId, selectedToolType, displayName || undefined);
+      setShowCreate(false);
+      setSelectedToolType("");
+      setDisplayName("");
+      await loadInstances();
+    } catch {
+      setError("Failed to create instance");
+    }
+  };
+
+  const handleStart = async (instanceId: string) => {
+    try {
+      await startInstance(projectId, repoId, instanceId);
+      await loadInstances();
+    } catch {
+      setError("Failed to start instance");
+    }
+  };
+
+  const handleStop = async (instanceId: string) => {
+    try {
+      await stopInstance(projectId, repoId, instanceId);
+      setStopConfirmId(null);
+      await loadInstances();
+    } catch {
+      setError("Failed to stop instance");
+    }
+  };
+
+  const handleRestart = async (instanceId: string) => {
+    try {
+      await restartInstance(projectId, repoId, instanceId);
+      await loadInstances();
+    } catch {
+      setError("Failed to restart instance");
+    }
+  };
+
+  const handleDelete = async (instanceId: string) => {
+    if (!confirm("Are you sure you want to delete this instance?")) return;
+    try {
+      await deleteInstance(projectId, repoId, instanceId);
+      // Update state immediately instead of reloading
+      setInstances(prev => prev.filter(i => i.id !== instanceId));
+    } catch {
+      setError("Failed to delete instance");
+    }
+  };
+
+  const handleRecreateTunnel = async (instanceId: string) => {
+    try {
+      await recreateInstanceTunnel(projectId, repoId, instanceId);
+      await loadInstances();
+    } catch {
+      setError("Failed to recreate tunnel");
+    }
+  };
+
+  const getStatusColor = (status: string) => {
+    switch (status) {
+      case "running":
+        return "var(--success)";
+      case "error":
+        return "var(--danger)";
+      case "pending":
+      case "building":
+        return "var(--warning)";
+      default:
+        return "var(--muted)";
+    }
+  };
+
+  const isTunnelUnhealthy = (instance: ToolInstance) => {
+    if (instance.status !== "running") return false;
+    if (!instance.url?.startsWith("http")) return false;
+    const health = healthStatus[instance.id];
+    if (!health) return false;
+    return !health.healthy;
+  };
+
+  return (
+    <div className="instance-list">
+      <div className="instance-list-header">
+        <h3>Tool Instances</h3>
+        <button
+          className="secondary-button small"
+          onClick={() => setShowCreate(true)}
+          type="button"
+        >
+          <Icon name="add" size="sm" />
+          Launch Tool
+        </button>
+      </div>
+
+      {error && (
+        <div className="error-message">{error}</div>
+      )}
+
+      {loading ? (
+        <p className="muted">Loading instances...</p>
+      ) : instances.length === 0 ? (
+        <p className="muted">No instances yet. Launch a tool to get started.</p>
+      ) : (
+        <div className="instance-grid">
+          {instances.map((instance) => (
+            <div key={instance.id} className="instance-card">
+              <div className="instance-info">
+                <div className="instance-name">{instance.display_name}</div>
+                <div className="instance-meta">
+                  <span
+                    className="status-dot"
+                    style={{ backgroundColor: getStatusColor(instance.status) }}
+                  />
+                  {instance.status}
+                  {isTunnelUnhealthy(instance) && (
+                    <span className="error-badge" title="Tunnel unreachable">
+                      <Icon name="warning" size="sm" />
+                      tunnel error
+                    </span>
+                  )}
+                </div>
+              </div>
+              <div className="instance-actions">
+                {instance.status === "running" && instance.url && instance.tool_type_interfaces.includes("web") && (
+                  <>
+                    <a
+                      href={instance.url.startsWith("http") ? instance.url : `${API_BASE_URL}${instance.url}`}
+                      target="_blank"
+                      rel="noopener noreferrer"
+                      className="secondary-button small"
+                    >
+                      <Icon name="external" size="sm" />
+                      Open
+                    </a>
+                    {isTunnelUnhealthy(instance) && (
+                      <button
+                        className="secondary-button small warning"
+                        onClick={() => void handleRecreateTunnel(instance.id)}
+                        type="button"
+                        title="Recreate tunnel"
+                      >
+                        <Icon name="refresh" size="sm" />
+                        Fix Tunnel
+                      </button>
+                    )}
+                  </>
+                )}
+                {instance.status === "running" && instance.tool_type_interfaces.includes("terminal") && (
+                  <button
+                    className="secondary-button small"
+                    onClick={() => navigate(`/instances/${instance.id}/terminal`)}
+                    type="button"
+                  >
+                    <Icon name="terminal" size="sm" />
+                    Terminal
+                  </button>
+                )}
+                {instance.status !== "running" && (
+                  <button
+                    className="secondary-button small"
+                    onClick={() => void handleStart(instance.id)}
+                    type="button"
+                  >
+                    <Icon name="play" size="sm" />
+                    Start
+                  </button>
+                )}
+                {instance.status === "running" && (
+                  <>
+                    {stopConfirmId === instance.id ? (
+                      <div className="inline-confirm">
+                        <span>Stop?</span>
+                        <button
+                          className="ghost-button small danger-text"
+                          onClick={() => void handleStop(instance.id)}
+                          type="button"
+                        >
+                          Yes
+                        </button>
+                        <button
+                          className="ghost-button small"
+                          onClick={() => setStopConfirmId(null)}
+                          type="button"
+                        >
+                          No
+                        </button>
+                      </div>
+                    ) : (
+                      <button
+                        className="ghost-button small"
+                        onClick={() => setStopConfirmId(instance.id)}
+                        type="button"
+                      >
+                        <Icon name="stop" size="sm" />
+                      </button>
+                    )}
+                    <button
+                      className="ghost-button small"
+                      onClick={() => void handleRestart(instance.id)}
+                      type="button"
+                    >
+                      <Icon name="refresh" size="sm" />
+                    </button>
+                  </>
+                )}
+                <button
+                  className="ghost-button small danger-text"
+                  onClick={() => void handleDelete(instance.id)}
+                  type="button"
+                >
+                  <Icon name="delete" size="sm" />
+                </button>
+              </div>
+            </div>
+          ))}
+        </div>
+      )}
+
+      {showCreate && (
+        <div className="dialog-overlay" role="dialog" aria-modal="true">
+          <div className="dialog">
+            <h2>Launch Tool</h2>
+            <div className="stack">
+              <label className="form-field">
+                Tool Type
+                <select
+                  value={selectedToolType}
+                  onChange={(e) => setSelectedToolType(e.target.value)}
+                >
+                  <option value="">Select a tool...</option>
+                  {toolTypes.map((tool) => (
+                    <option key={tool.id} value={tool.id}>
+                      {tool.display_name}
+                    </option>
+                  ))}
+                </select>
+              </label>
+              <label className="form-field">
+                Display Name (optional)
+                <input
+                  type="text"
+                  value={displayName}
+                  onChange={(e) => setDisplayName(e.target.value)}
+                  placeholder="My Development Environment"
+                />
+              </label>
+              <div className="dialog-actions">
+                <button
+                  className="secondary-button"
+                  onClick={() => setShowCreate(false)}
+                  type="button"
+                >
+                  Cancel
+                </button>
+                <button
+                  className="primary-button"
+                  onClick={() => void handleCreate()}
+                  disabled={!selectedToolType}
+                  type="button"
+                >
+                  Launch
+                </button>
+              </div>
+            </div>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+};

apps/web/src/components/merge-dialog.tsx

@@ -0,0 +1,144 @@
+import { useState } from "react";
+
+import { mergeBranches } from "../api/git_repositories";
+import { Icon } from "./icon";
+
+interface MergeDialogProps {
+  projectId: string;
+  repoId: string;
+  branches: string[];
+  currentBranch: string;
+  isOpen: boolean;
+  onClose: () => void;
+  onMerge: () => void;
+}
+
+export const MergeDialog = ({
+  projectId,
+  repoId,
+  branches,
+  currentBranch,
+  isOpen,
+  onClose,
+  onMerge,
+}: MergeDialogProps) => {
+  const [sourceBranch, setSourceBranch] = useState("");
+  const [commitMessage, setCommitMessage] = useState("");
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [success, setSuccess] = useState(false);
+
+  if (!isOpen) return null;
+
+  const availableBranches = branches.filter((b) => b !== currentBranch);
+
+  const handleMerge = async () => {
+    if (!sourceBranch) {
+      setError("Please select a source branch");
+      return;
+    }
+    setLoading(true);
+    setError(null);
+    setSuccess(false);
+    try {
+      await mergeBranches(
+        projectId,
+        repoId,
+        sourceBranch,
+        currentBranch,
+        commitMessage || undefined
+      );
+      setSuccess(true);
+      setTimeout(() => {
+        onMerge();
+        onClose();
+      }, 1500);
+    } catch {
+      setError("Merge failed. There may be conflicts to resolve.");
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <div className="modal-overlay" onClick={onClose}>
+      <div className="modal-content" onClick={(e) => e.stopPropagation()}>
+        <h2>Merge Branch</h2>
+        
+        <div className="merge-form">
+          <div className="form-field">
+            <label>Source Branch (merge from)</label>
+            <select
+              value={sourceBranch}
+              onChange={(e) => setSourceBranch(e.target.value)}
+              disabled={loading}
+            >
+              <option value="">Select branch...</option>
+              {availableBranches.map((branch) => (
+                <option key={branch} value={branch}>
+                  {branch}
+                </option>
+              ))}
+            </select>
+          </div>
+
+          <div className="form-field">
+            <label>Target Branch (merge into)</label>
+            <input
+              type="text"
+              value={currentBranch}
+              disabled
+              className="input-disabled"
+            />
+          </div>
+
+          <div className="form-field">
+            <label>Commit Message (optional)</label>
+            <textarea
+              value={commitMessage}
+              onChange={(e) => setCommitMessage(e.target.value)}
+              placeholder={`Merge ${sourceBranch || "branch"} into ${currentBranch}`}
+              rows={3}
+              disabled={loading}
+            />
+          </div>
+
+          {error && <div className="error-text">{error}</div>}
+          {success && (
+            <div className="success-text">Merge successful!</div>
+          )}
+
+          <div className="modal-actions">
+            <button
+              className="secondary-button"
+              onClick={onClose}
+              disabled={loading}
+              type="button"
+            >
+              <Icon name="cancel" size="sm" />
+              Cancel
+            </button>
+            <button
+              className="primary-button"
+              onClick={handleMerge}
+              disabled={loading || !sourceBranch}
+              type="button"
+            >
+              {loading ? (
+                <>
+                  <Icon name="loading" size="sm" />
+                  Merging...
+                </>
+              ) : (
+                <>
+                  <Icon name="merge" size="sm" />
+                  Merge
+                </>
+              )}
+            </button>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+};

apps/web/src/components/repositories-settings-tab.test.tsx

@@ -0,0 +1,114 @@
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { RepositoriesSettingsTab } from "./repositories-settings-tab";
+import * as gitRepositoriesApi from "../api/git_repositories";
+
+const mockRepositories = [
+  {
+    id: "repo-1",
+    name: "Main Repo",
+    path: "/repos/main",
+    project_id: "proj-1",
+    owner_id: "user-1",
+    is_mirror: false,
+    remote_url: null,
+    last_push: null,
+    created_at: null,
+  },
+];
+
+vi.mock("react-router-dom", async () => {
+  const actual = await vi.importActual<typeof import("react-router-dom")>("react-router-dom");
+  return {
+    ...actual,
+    useParams: () => ({ projectId: "proj-1" }),
+  };
+});
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+describe("RepositoriesSettingsTab", () => {
+  it("opens create dialog and clones an existing repository", async () => {
+    const listMock = vi.spyOn(gitRepositoriesApi, "listRepositories").mockResolvedValue(mockRepositories);
+    const createMock = vi.spyOn(gitRepositoriesApi, "createRepository").mockResolvedValue(mockRepositories[0]);
+
+    render(<RepositoriesSettingsTab />);
+
+    await waitFor(() => {
+      expect(screen.getByText("Main Repo")).toBeInTheDocument();
+    });
+
+    fireEvent.click(screen.getByRole("button", { name: /add repository/i }));
+    fireEvent.change(screen.getByPlaceholderText(/repository-name/i), {
+      target: { value: "New Repo" },
+    });
+    fireEvent.change(screen.getByPlaceholderText(/owner/i), {
+      target: { value: "alice" },
+    });
+    fireEvent.change(screen.getByPlaceholderText(/repo-name/i), {
+      target: { value: "demo" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: /clone repository/i }));
+
+    await waitFor(() => {
+      expect(createMock).toHaveBeenCalledWith("proj-1", {
+        name: "New Repo",
+        remote_url: "git@git.commumedia.org:alice/demo.git",
+      });
+    });
+    expect(listMock).toHaveBeenCalledTimes(2);
+  });
+
+  it("uses advanced url fallback when requested", async () => {
+    const listMock = vi.spyOn(gitRepositoriesApi, "listRepositories").mockResolvedValue(mockRepositories);
+    const createMock = vi.spyOn(gitRepositoriesApi, "createRepository").mockResolvedValue(mockRepositories[0]);
+
+    render(<RepositoriesSettingsTab />);
+
+    await waitFor(() => {
+      expect(screen.getByText("Main Repo")).toBeInTheDocument();
+    });
+
+    fireEvent.click(screen.getByRole("button", { name: /add repository/i }));
+    fireEvent.change(screen.getByPlaceholderText(/repository-name/i), {
+      target: { value: "New Repo" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: /use full url instead/i }));
+    fireEvent.change(screen.getByPlaceholderText(/https:\/\/github.com\/user\/repo.git/i), {
+      target: { value: "https://github.com/user/repo.git" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: /clone repository/i }));
+
+    await waitFor(() => {
+      expect(createMock).toHaveBeenCalledWith("proj-1", {
+        name: "New Repo",
+        remote_url: "https://github.com/user/repo.git",
+      });
+    });
+    expect(listMock).toHaveBeenCalledTimes(2);
+  });
+
+  it("shows validation when cloning without a remote url", async () => {
+    vi.spyOn(gitRepositoriesApi, "listRepositories").mockResolvedValue(mockRepositories);
+    render(<RepositoriesSettingsTab />);
+
+    await waitFor(() => {
+      expect(screen.getByText("Main Repo")).toBeInTheDocument();
+    });
+
+    fireEvent.click(screen.getByRole("button", { name: /add repository/i }));
+    fireEvent.change(screen.getByPlaceholderText(/repository-name/i), {
+      target: { value: "New Repo" },
+    });
+    fireEvent.change(screen.getByPlaceholderText(/owner/i), {
+      target: { value: "" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: /clone repository/i }));
+
+    expect(screen.getByText(/owner and repository name are required/i)).toBeInTheDocument();
+  });
+});

apps/web/src/components/repositories-settings-tab.tsx

@@ -0,0 +1,99 @@
+import React, { useCallback, useEffect, useState } from "react";
+import { useParams } from "react-router-dom";
+
+import { deleteRepository, listRepositories, type GitRepository } from "../api/git_repositories";
+import { RepositoryCreateDialog } from "./repository-create-dialog";
+import { Icon } from "./icon";
+
+export const RepositoriesSettingsTab: React.FC = () => {
+  const { projectId } = useParams<{ projectId: string }>();
+  const [repositories, setRepositories] = useState<GitRepository[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [showCreate, setShowCreate] = useState(false);
+  const [error, setError] = useState("");
+
+  const loadRepositories = useCallback(async () => {
+    if (!projectId) {
+      setLoading(false);
+      return;
+    }
+
+    setLoading(true);
+    try {
+      const data = await listRepositories(projectId);
+      setRepositories(data);
+    } catch {
+      setError("Failed to load repositories");
+    } finally {
+      setLoading(false);
+    }
+  }, [projectId]);
+
+  useEffect(() => {
+    void loadRepositories();
+  }, [loadRepositories]);
+
+  const handleDelete = async (repoId: string) => {
+    if (!projectId) return;
+    if (!window.confirm("Are you sure you want to delete this repository?")) return;
+    try {
+      await deleteRepository(projectId, repoId);
+      setRepositories((current) => current.filter((r) => r.id !== repoId));
+    } catch {
+      setError("Failed to delete repository");
+    }
+  };
+
+  if (loading) return <div>Loading...</div>;
+
+  return (
+    <div className="repositories-settings-tab">
+      <div className="page-header">
+        <h2>Repositories</h2>
+        <button
+          className="primary-button"
+          onClick={() => setShowCreate(true)}
+          type="button"
+        >
+          <Icon name="add" size="sm" />
+          Add Repository
+        </button>
+      </div>
+      {error && <div className="error-message">{error}</div>}
+
+      <div className="repositories-list">
+        {repositories.length === 0 ? (
+          <p>No repositories yet.</p>
+        ) : (
+          repositories.map((repo) => (
+            <div key={repo.id} className="repository-card">
+              <div className="repository-info">
+                <h3>{repo.name}</h3>
+                <p>{repo.remote_url}</p>
+                <span className="repo-type">
+                  {repo.is_mirror ? "Mirror" : "Clone"}
+                </span>
+              </div>
+              <button
+                onClick={() => handleDelete(repo.id)}
+                className="btn-danger"
+              >
+                Delete
+              </button>
+            </div>
+          ))
+        )}
+      </div>
+
+      {showCreate && (
+        <RepositoryCreateDialog
+          projectId={projectId!}
+          open={showCreate}
+          title="Add Repository"
+          onClose={() => setShowCreate(false)}
+          onCreated={loadRepositories}
+        />
+      )}
+    </div>
+  );
+};

apps/web/src/components/repository-create-dialog.tsx

@@ -0,0 +1,293 @@
+import { useEffect, useRef, useState } from "react";
+
+import { createRepository, parseGitUrl, type GitRepositoryCreate, type URLParseResult } from "../api/git_repositories";
+import { Icon } from "./icon";
+
+type CreateMode = "clone" | "blank";
+type UrlValidationStatus = "idle" | "validating" | "valid" | "needs-parsing" | "invalid";
+
+interface RepositoryCreateDialogProps {
+  projectId: string;
+  open: boolean;
+  title: string;
+  onClose: () => void;
+  onCreated: () => Promise<void> | void;
+}
+
+export const RepositoryCreateDialog = ({ projectId, open, title, onClose, onCreated }: RepositoryCreateDialogProps) => {
+  const [createMode, setCreateMode] = useState<CreateMode>("clone");
+  const [formName, setFormName] = useState("");
+  const [owner, setOwner] = useState("");
+  const [repoName, setRepoName] = useState("");
+  const [advancedUrl, setAdvancedUrl] = useState("");
+  const [useAdvancedUrl, setUseAdvancedUrl] = useState(false);
+  const [formError, setFormError] = useState<string | null>(null);
+  const [urlValidation, setUrlValidation] = useState<{
+    status: UrlValidationStatus;
+    result: URLParseResult | null;
+  }>({ status: "idle", result: null });
+  const debounceTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => {
+    if (!open && debounceTimer.current) {
+      clearTimeout(debounceTimer.current);
+      debounceTimer.current = null;
+    }
+  }, [open]);
+
+  useEffect(() => {
+    if (!open) return;
+    if (!useAdvancedUrl) {
+      setUrlValidation({ status: "idle", result: null });
+      return;
+    }
+
+    if (debounceTimer.current) {
+      clearTimeout(debounceTimer.current);
+    }
+
+    if (!advancedUrl.trim()) {
+      setUrlValidation({ status: "idle", result: null });
+      return;
+    }
+
+    setUrlValidation({ status: "validating", result: null });
+
+    debounceTimer.current = setTimeout(async () => {
+      try {
+        const result = await parseGitUrl(advancedUrl.trim());
+        if (result.is_valid_clone_url) {
+          setUrlValidation({ status: "valid", result });
+        } else if (result.needs_parsing) {
+          setUrlValidation({ status: "needs-parsing", result });
+        } else {
+          setUrlValidation({ status: "invalid", result });
+        }
+      } catch {
+        setUrlValidation({ status: "invalid", result: null });
+      }
+    }, 300);
+
+    return () => {
+      if (debounceTimer.current) {
+        clearTimeout(debounceTimer.current);
+      }
+    };
+  }, [advancedUrl, open, useAdvancedUrl]);
+
+  const resetForm = () => {
+    setCreateMode("clone");
+    setFormName("");
+    setOwner("");
+    setRepoName("");
+    setAdvancedUrl("");
+    setUseAdvancedUrl(false);
+    setFormError(null);
+    setUrlValidation({ status: "idle", result: null });
+  };
+
+  const handleClose = () => {
+    resetForm();
+    onClose();
+  };
+
+  const handleSubmit = async (event: React.FormEvent) => {
+    event.preventDefault();
+    setFormError(null);
+
+    if (!formName.trim()) {
+      setFormError("Repository name is required");
+      return;
+    }
+
+    try {
+      const input: GitRepositoryCreate = {
+        name: formName.trim(),
+        remote_url: undefined,
+      };
+
+      if (createMode === "clone") {
+        if (useAdvancedUrl) {
+          if (!advancedUrl.trim()) {
+            setFormError("Remote URL is required for advanced cloning");
+            return;
+          }
+          input.remote_url = advancedUrl.trim();
+        } else {
+          if (!owner.trim() || !repoName.trim()) {
+            setFormError("Owner and repository name are required");
+            return;
+          }
+          input.remote_url = `git@git.commumedia.org:${owner.trim()}/${repoName.trim()}.git`;
+        }
+      }
+
+      await createRepository(projectId, input);
+      handleClose();
+      await onCreated();
+    } catch (error: unknown) {
+      const response = error as { response?: { data?: { detail?: string } } };
+      const detail = response.response?.data?.detail;
+      setFormError(typeof detail === "string" ? detail : "Failed to create repository");
+    }
+  };
+
+  const handleUseSuggestedUrl = () => {
+    if (urlValidation.result?.base_url) {
+      setAdvancedUrl(urlValidation.result.base_url);
+      setUrlValidation({ status: "idle", result: null });
+      setFormError(null);
+    }
+  };
+
+  const getUrlInputClass = () => {
+    switch (urlValidation.status) {
+      case "valid":
+        return "valid-url";
+      case "needs-parsing":
+        return "needs-parsing-url";
+      case "invalid":
+        return "invalid-url";
+      default:
+        return "";
+    }
+  };
+
+  if (!open) return null;
+
+  return (
+    <div className="dialog-overlay" role="dialog" aria-modal="true">
+      <div className="dialog">
+        <h3>{title}</h3>
+        <p className="muted">
+          Clone an existing repository from git.commumedia.org, or create a blank bare repo here.
+        </p>
+        <form onSubmit={handleSubmit} className="stack">
+          <div className="form-field">
+            <label>
+              <input
+                type="radio"
+                name="repository-mode"
+                checked={createMode === "clone"}
+                onChange={() => setCreateMode("clone")}
+              />
+              Clone existing repository
+            </label>
+            <label>
+              <input
+                type="radio"
+                name="repository-mode"
+                checked={createMode === "blank"}
+                onChange={() => setCreateMode("blank")}
+              />
+              Create blank repository
+            </label>
+          </div>
+          <label className="form-field">
+            Repository name
+            <input
+              type="text"
+              value={formName}
+              onChange={(event) => setFormName(event.target.value)}
+              placeholder="repository-name"
+            />
+          </label>
+          {createMode === "clone" && !useAdvancedUrl && (
+            <>
+              <label className="form-field">
+                Owner
+                <input
+                  type="text"
+                  value={owner}
+                  onChange={(event) => setOwner(event.target.value)}
+                  placeholder="owner"
+                />
+              </label>
+              <label className="form-field">
+                Repository
+                <input
+                  type="text"
+                  value={repoName}
+                  onChange={(event) => setRepoName(event.target.value)}
+                  placeholder="repo-name"
+                />
+              </label>
+              <p className="muted">SSH target: git@git.commumedia.org:{owner || "owner"}/{repoName || "repo"}.git</p>
+              <button
+                type="button"
+                className="secondary-button small"
+                onClick={() => setUseAdvancedUrl(true)}
+              >
+                Use full URL instead
+              </button>
+            </>
+          )}
+          {createMode === "clone" && useAdvancedUrl && (
+            <label className="form-field">
+              Remote URL
+              <input
+                type="text"
+                value={advancedUrl}
+                onChange={(event) => setAdvancedUrl(event.target.value)}
+                placeholder="https://github.com/user/repo.git"
+                className={getUrlInputClass()}
+              />
+              {urlValidation.status === "validating" && (
+                <span className="validation-status validating">Validating...</span>
+              )}
+              {urlValidation.status === "valid" && (
+                <span className="validation-status valid">
+                  <Icon name="success" size="sm" /> Valid git URL
+                </span>
+              )}
+              {urlValidation.status === "needs-parsing" && urlValidation.result && (
+                <div className="url-suggestion">
+                  <span className="validation-status warning">
+                    <Icon name="warning" size="sm" /> This looks like a browser URL
+                  </span>
+                  <div className="suggestion-actions">
+                    <span className="suggested-url">Suggested: {urlValidation.result.base_url}</span>
+                    <button
+                      type="button"
+                      className="secondary-button small"
+                      onClick={handleUseSuggestedUrl}
+                    >
+                      Use Suggested
+                    </button>
+                  </div>
+                </div>
+              )}
+              {urlValidation.status === "invalid" && (
+                <span className="validation-status invalid">
+                  <Icon name="error" size="sm" /> Invalid URL
+                </span>
+              )}
+              <button
+                type="button"
+                className="secondary-button small"
+                onClick={() => setUseAdvancedUrl(false)}
+              >
+                Use owner/repo instead
+              </button>
+            </label>
+          )}
+          {formError && (
+            <div className="error-message">
+              <p className="error-text">{formError}</p>
+            </div>
+          )}
+          <div className="dialog-actions">
+            <button className="secondary-button" onClick={handleClose} type="button">
+              <Icon name="cancel" size="sm" />
+              Cancel
+            </button>
+            <button className="primary-button" type="submit">
+              <Icon name="add" size="sm" />
+              {createMode === "clone" ? "Clone Repository" : "Create Blank Repository"}
+            </button>
+          </div>
+        </form>
+      </div>
+    </div>
+  );
+};

apps/web/src/components/settings-tab-layout.tsx

@@ -0,0 +1,43 @@
+import React from "react";
+import { Link, useLocation } from "react-router-dom";
+
+interface Tab {
+  id: string;
+  label: string;
+  path: string;
+}
+
+interface SettingsTabLayoutProps {
+  tabs: Tab[];
+  children: React.ReactNode;
+  basePath: string;
+}
+
+export const SettingsTabLayout: React.FC<SettingsTabLayoutProps> = ({
+  tabs,
+  children,
+  basePath,
+}) => {
+  const location = useLocation();
+
+  return (
+    <div className="settings-layout">
+      <aside className="settings-sidebar">
+        <nav className="settings-nav">
+          {tabs.map((tab) => (
+            <Link
+              key={tab.id}
+              to={`${basePath}/${tab.path}`}
+              className={`settings-nav-link ${
+                location.pathname.includes(tab.path) ? "active" : ""
+              }`}
+            >
+              {tab.label}
+            </Link>
+          ))}
+        </nav>
+      </aside>
+      <main className="settings-content">{children}</main>
+    </div>
+  );
+};

apps/web/src/components/syntax-highlighter.tsx

@@ -0,0 +1,77 @@
+import React, { useEffect, useState } from "react";
+
+import { Icon } from "./icon";
+import { highlightCode, loadLanguage } from "../utils/language";
+
+interface SyntaxHighlighterProps {
+  code: string;
+  language: string;
+  showLineNumbers?: boolean;
+}
+
+export const SyntaxHighlighter: React.FC<SyntaxHighlighterProps> = ({
+  code,
+  language,
+  showLineNumbers = true,
+}) => {
+  const [highlighted, setHighlighted] = useState(">");
+  const [copied, setCopied] = useState(false);
+
+  useEffect(() => {
+    const highlight = async () => {
+      await loadLanguage(language);
+      setHighlighted(highlightCode(code, language));
+    };
+    void highlight();
+  }, [code, language]);
+
+  const handleCopy = async () => {
+    await navigator.clipboard.writeText(code);
+    setCopied(true);
+    setTimeout(() => setCopied(false), 2000);
+  };
+
+  const lines = code.split("\n");
+
+  return (
+    <div className="syntax-highlighter">
+      <div className="highlighter-toolbar">
+        <span className="language-badge">{language}</span>
+        <button
+          className="copy-button"
+          onClick={handleCopy}
+          type="button"
+        >
+          {copied ? (
+            <>
+              <Icon name="success" size="sm" />
+              Copied!
+            </>
+          ) : (
+            <>
+              <Icon name="copy" size="sm" />
+              Copy
+            </>
+          )}
+        </button>
+      </div>
+      <div className="code-container">
+        {showLineNumbers && (
+          <div className="line-numbers">
+            {lines.map((_, i) => (
+              <div key={i} className="line-number">
+                {i + 1}
+              </div>
+            ))}
+          </div>
+        )}
+        <pre className="code-block">
+          <code
+            className={`language-${language}`}
+            dangerouslySetInnerHTML={{ __html: highlighted }}
+          />
+        </pre>
+      </div>
+    </div>
+  );
+};

apps/web/src/components/terminal.tsx

@@ -0,0 +1,158 @@
+import React, { useEffect, useRef, useState } from "react";
+import { Terminal } from "xterm";
+import { FitAddon } from "xterm-addon-fit";
+import { WebLinksAddon } from "xterm-addon-web-links";
+import "xterm/css/xterm.css";
+
+interface TerminalProps {
+  instanceId: string;
+  onClose?: () => void;
+}
+
+export const TerminalComponent: React.FC<TerminalProps> = ({ instanceId, onClose }) => {
+  const terminalRef = useRef<HTMLDivElement>(null);
+  const wsRef = useRef<WebSocket | null>(null);
+  const [status, setStatus] = useState<"connecting" | "connected" | "disconnected" | "error">(
+    "connecting",
+  );
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!terminalRef.current) return;
+
+    // Initialize terminal
+    const term = new Terminal({
+      cursorBlink: true,
+      fontSize: 14,
+      fontFamily: 'Menlo, Monaco, "Courier New", monospace',
+      theme: {
+        background: "#1e1e1e",
+        foreground: "#d4d4d4",
+        cursor: "#d4d4d4",
+        selectionBackground: "#264f78",
+        black: "#000000",
+        red: "#cd3131",
+        green: "#0dbc79",
+        yellow: "#e5e510",
+        blue: "#2472c8",
+        magenta: "#bc3fbc",
+        cyan: "#11a8cd",
+        white: "#e5e5e5",
+        brightBlack: "#666666",
+        brightRed: "#f14c4c",
+        brightGreen: "#23d18b",
+        brightYellow: "#f5f543",
+        brightBlue: "#3b8eea",
+        brightMagenta: "#d670d6",
+        brightCyan: "#29b8db",
+        brightWhite: "#e5e5e5",
+      },
+    });
+
+    const fitAddon = new FitAddon();
+    term.loadAddon(fitAddon);
+    term.loadAddon(new WebLinksAddon());
+
+    term.open(terminalRef.current);
+    fitAddon.fit();
+
+    // Build WebSocket URL
+    const apiUrl = import.meta.env.VITE_API_BASE_URL || "";
+    const wsProtocol = window.location.protocol === "https:" ? "wss:" : "ws:";
+    const wsHost = apiUrl.replace(/^https?:\/\//, "").replace(/\/+$/, "");
+    const wsUrl = `${wsProtocol}//${wsHost}/ws/tool-instances/${instanceId}/terminal`;
+
+    // Connect WebSocket
+    const ws = new WebSocket(wsUrl);
+    wsRef.current = ws;
+
+    ws.onopen = () => {
+      setStatus("connected");
+      setError(null);
+    };
+
+    ws.onmessage = (event) => {
+      if (event.data instanceof Blob) {
+        event.data.arrayBuffer().then((buffer) => {
+          const data = new Uint8Array(buffer);
+          term.write(data);
+        });
+      } else if (typeof event.data === "string") {
+        try {
+          const msg = JSON.parse(event.data);
+          if (msg.type === "status" && msg.status === "connected") {
+            setStatus("connected");
+          }
+        } catch {
+          term.write(event.data);
+        }
+      }
+    };
+
+    ws.onclose = (event) => {
+      setStatus("disconnected");
+      if (event.code !== 1000) {
+        setError(`Connection closed (code: ${event.code})`);
+      }
+    };
+
+    ws.onerror = () => {
+      setStatus("error");
+      setError("WebSocket error");
+    };
+
+    // Handle terminal input
+    term.onData((data) => {
+      if (ws.readyState === WebSocket.OPEN) {
+        ws.send(data);
+      }
+    });
+
+    // Handle resize
+    const handleResize = () => {
+      fitAddon.fit();
+      const { cols, rows } = term;
+      if (ws.readyState === WebSocket.OPEN) {
+        ws.send(
+          JSON.stringify({
+            type: "resize",
+            cols,
+            rows,
+          }),
+        );
+      }
+    };
+
+    window.addEventListener("resize", handleResize);
+
+    // Initial resize
+    setTimeout(handleResize, 100);
+
+    return () => {
+      window.removeEventListener("resize", handleResize);
+      ws.close();
+      term.dispose();
+    };
+  }, [instanceId]);
+
+  return (
+    <div className="terminal-wrapper">
+      <div className="terminal-header">
+        <div className="terminal-status">
+          <span
+            className={`status-dot ${status}`}
+            aria-label={`Terminal status: ${status}`}
+          />
+          <span className="status-text">{status}</span>
+        </div>
+        {onClose && (
+          <button className="terminal-close" onClick={onClose} type="button">
+            Close
+          </button>
+        )}
+      </div>
+      {error && <div className="terminal-error">{error}</div>}
+      <div ref={terminalRef} className="terminal-container" />
+    </div>
+  );
+};

apps/web/src/components/workspace-header.tsx

@@ -0,0 +1,48 @@
+import { Link } from "react-router-dom";
+import { Icon } from "./icon";
+
+interface WorkspaceHeaderProps {
+  project: {
+    id: string;
+    name: string;
+    description?: string | null;
+  };
+  currentRepo?: {
+    id: string;
+    name: string;
+  } | null;
+}
+
+export const WorkspaceHeader = ({ project, currentRepo }: WorkspaceHeaderProps) => {
+  return (
+    <div className="workspace-header">
+      <div className="workspace-header-left">
+        <div className="workspace-header-icon">
+          <Icon name="folder" size="lg" />
+        </div>
+        <div className="workspace-header-info">
+          <h1 className="workspace-header-title">{project.name}</h1>
+          {currentRepo && (
+            <span className="workspace-header-subtitle">{currentRepo.name}</span>
+          )}
+        </div>
+      </div>
+      <div className="workspace-header-actions">
+        <Link
+          className="workspace-header-action-btn"
+          to={`/projects/${project.id}/repositories/${currentRepo?.id || ""}/history`}
+        >
+          <Icon name="history" size="sm" />
+          History
+        </Link>
+        <Link
+          className="workspace-header-action-btn"
+          to={`/projects/${project.id}/settings`}
+        >
+          <Icon name="settings" size="sm" />
+          Settings
+        </Link>
+      </div>
+    </div>
+  );
+};

apps/web/src/main.tsx

@@ -4,13 +4,16 @@ import { BrowserRouter } from "react-router-dom";
 
 import { AppRouter } from "./router";
 import { AuthProvider } from "./state/auth";
+import { SessionsProvider } from "./state/sessions";
 import "./styles.css";
 
 ReactDOM.createRoot(document.getElementById("root")!).render(
   <React.StrictMode>
     <BrowserRouter>
       <AuthProvider>
+        <SessionsProvider>
           <AppRouter />
+        </SessionsProvider>
       </AuthProvider>
     </BrowserRouter>
   </React.StrictMode>

apps/web/src/pages/dashboard.test.tsx

@@ -1,54 +1,81 @@
 import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { MemoryRouter } from "react-router-dom";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
-import { DashboardPage } from "./dashboard";
+import { HomePage } from "./dashboard";
 
-const mockGet = vi.fn();
+const mockDashboard = vi.fn();
+const mockSessions = vi.fn();
+const mockProjects = vi.fn();
+const mockRepos = vi.fn();
 
 vi.mock("../api/dashboard", () => ({
-  getDashboardSummary: (...args: unknown[]) => mockGet(...args)
+  getDashboardSummary: (...args: unknown[]) => mockDashboard(...args)
 }));
 
-describe("DashboardPage", () => {
+vi.mock("../api/sessions", () => ({
+  getUserSessions: (...args: unknown[]) => mockSessions(...args),
+  createInstance: vi.fn(),
+  startInstance: vi.fn(),
+  stopInstance: vi.fn(),
+  deleteInstance: vi.fn(),
+  recreateInstanceTunnel: vi.fn()
+}));
+
+vi.mock("../api/projects", () => ({
+  listProjects: (...args: unknown[]) => mockProjects(...args)
+}));
+
+vi.mock("../api/git_repositories", () => ({
+  listRepositories: (...args: unknown[]) => mockRepos(...args)
+}));
+
+vi.mock("../api/tool_types", () => ({
+  listToolTypes: vi.fn().mockResolvedValue([])
+}));
+
+describe("HomePage", () => {
   beforeEach(() => {
-    mockGet.mockReset();
+    mockDashboard.mockReset();
+    mockSessions.mockReset();
+    mockProjects.mockReset();
+    mockRepos.mockReset();
   });
 
-  it("shows loading then empty state when summary has no data", async () => {
-    mockGet.mockResolvedValue({
-      projects: 0,
-      repositories: 0,
-      sshKeys: 0,
-      recentActivity: []
-    });
+  it("shows overview sections", async () => {
+    mockDashboard.mockResolvedValue({ projects: 1, repositories: 2, sshKeys: 3, recentActivity: [] });
+    mockSessions.mockResolvedValue([]);
+    mockProjects.mockResolvedValue([]);
+    mockRepos.mockResolvedValue([]);
 
-    render(<DashboardPage />);
+    render(
+      <MemoryRouter>
+        <HomePage />
+      </MemoryRouter>
+    );
 
-    expect(screen.getByText("Loading dashboard...")).toBeInTheDocument();
+    expect(screen.getByText("Loading overview...")).toBeInTheDocument();
     await waitFor(() => {
-      expect(screen.getByText("No activity yet")).toBeInTheDocument();
+      expect(screen.getAllByText("Open sessions").length).toBeGreaterThan(0);
+      expect(screen.getByText("Available projects")).toBeInTheDocument();
     });
   });
 
-  it("shows retry action when summary request fails", async () => {
-    mockGet.mockRejectedValueOnce(new Error("failed"));
-    mockGet.mockResolvedValueOnce({
-      projects: 2,
-      repositories: 5,
-      sshKeys: 1,
-      recentActivity: ["Created repo"]
-    });
+  it("shows retry action when home load fails", async () => {
+    mockDashboard.mockRejectedValueOnce(new Error("failed"));
+    mockSessions.mockRejectedValueOnce(new Error("failed"));
+    mockProjects.mockRejectedValueOnce(new Error("failed"));
 
-    render(<DashboardPage />);
+    render(
+      <MemoryRouter>
+        <HomePage />
+      </MemoryRouter>
+    );
 
     await waitFor(() => {
-      expect(screen.getByText("Dashboard is unavailable")).toBeInTheDocument();
+      expect(screen.getByText("Unable to load your workspace overview.")).toBeInTheDocument();
     });
 
-    fireEvent.click(screen.getByRole("button", { name: "Retry" }));
-
-    await waitFor(() => {
-      expect(screen.getByText("2")).toBeInTheDocument();
-    });
+    fireEvent.click(screen.getAllByRole("button", { name: "Retry" })[0]);
   });
 });

apps/web/src/pages/dashboard.tsx

@@ -1,79 +1,338 @@
 import { useCallback, useEffect, useMemo, useState } from "react";
+import { useNavigate } from "react-router-dom";
 
 import { getDashboardSummary, type DashboardSummary } from "../api/dashboard";
+import { createInstance, getUserSessions, startInstance, stopInstance, deleteInstance, recreateInstanceTunnel, type Session as SessionApi } from "../api/sessions";
+import { listProjects } from "../api/projects";
+import { listRepositories, type GitRepository } from "../api/git_repositories";
+import { listToolTypes, type ToolType } from "../api/tool_types";
+import { updateUserConfig } from "../api/settings";
+import type { Project } from "../types";
+import { Icon } from "../components/icon";
 
-const CARDS = [
+type HomeStatus = "loading" | "ready" | "error";
+
+const summaryCards = [
+  { label: "Open sessions", key: "openSessions" },
   { label: "Projects", key: "projects" },
   { label: "Repositories", key: "repositories" },
-  { label: "SSH Keys", key: "sshKeys" }
 ] as const;
 
-type DashboardStatus = "loading" | "ready" | "error";
+type SessionView = SessionApi;
 
-export const DashboardPage = () => {
-  const [status, setStatus] = useState<DashboardStatus>("loading");
+export const HomePage = () => {
+  const navigate = useNavigate();
+  const [status, setStatus] = useState<HomeStatus>("loading");
   const [summary, setSummary] = useState<DashboardSummary | null>(null);
+  const [sessions, setSessions] = useState<SessionView[]>([]);
+  const [projects, setProjects] = useState<Project[]>([]);
+  const [repositories, setRepositories] = useState<GitRepository[]>([]);
+  const [toolTypes, setToolTypes] = useState<ToolType[]>([]);
+  const [selectedProject, setSelectedProject] = useState("");
+  const [selectedRepo, setSelectedRepo] = useState("");
+  const [selectedToolType, setSelectedToolType] = useState("");
+  const [displayName, setDisplayName] = useState("");
+  const [saveState, setSaveState] = useState<"idle" | "saving" | "error">("idle");
+  const [actionBusy, setActionBusy] = useState<string | null>(null);
+  const safeSessions = Array.isArray(sessions) ? sessions : [];
 
-  const loadSummary = useCallback(async () => {
+  const loadHome = useCallback(async () => {
     setStatus("loading");
     try {
-      const data = await getDashboardSummary();
-      setSummary(data);
+      const [dashboard, sessionData, projectData, toolTypeData] = await Promise.all([
+        getDashboardSummary(),
+        getUserSessions(),
+        listProjects(),
+        listToolTypes(),
+      ]);
+      setSummary(dashboard);
+      setSessions(sessionData as SessionView[]);
+      setProjects(projectData);
+      setToolTypes(toolTypeData);
       setStatus("ready");
     } catch {
-      setSummary(null);
       setStatus("error");
     }
   }, []);
 
   useEffect(() => {
-    void loadSummary();
-  }, [loadSummary]);
+    void loadHome();
+  }, [loadHome]);
 
-  const cards = useMemo(() => CARDS, []);
-  const isEmpty =
-    status === "ready" &&
-    summary !== null &&
-    summary.projects === 0 &&
-    summary.repositories === 0 &&
-    summary.sshKeys === 0 &&
-    summary.recentActivity.length === 0;
+  useEffect(() => {
+    if (!selectedProject) {
+      setRepositories([]);
+      return;
+    }
+
+    const loadRepos = async () => {
+      try {
+        const data = await listRepositories(selectedProject);
+        setRepositories(data);
+      } catch {
+        setRepositories([]);
+      }
+    };
+
+    void loadRepos();
+  }, [selectedProject]);
+
+  const activeSessions = useMemo(
+    () => safeSessions.filter((session) => ["running", "building", "pending"].includes(session.status)),
+    [safeSessions]
+  );
+
+  const recentSessions = useMemo(
+    () => safeSessions.filter((session) => ["stopped", "error"].includes(session.status)).slice(0, 5),
+    [safeSessions]
+  );
+
+  const handleCreate = async (event: React.FormEvent) => {
+    event.preventDefault();
+    if (!selectedProject || !selectedRepo || !selectedToolType) return;
+
+    setSaveState("saving");
+    try {
+      const instance = await createInstance(selectedProject, selectedRepo, selectedToolType, displayName || undefined);
+      await startInstance(selectedProject, selectedRepo, instance.id);
+      await updateUserConfig({ last_session_id: instance.id });
+      setDisplayName("");
+      setSelectedProject("");
+      setSelectedRepo("");
+      setSelectedToolType("");
+      setSaveState("idle");
+      await loadHome();
+    } catch {
+      setSaveState("error");
+    }
+  };
+
+  const handleOpen = (session: SessionView) => {
+    if (session.url) {
+      window.open(session.url, "_blank", "noopener,noreferrer");
+      return;
+    }
+    if (session.tool_type_interfaces.includes("terminal")) {
+      navigate(`/instances/${session.id}/terminal`);
+      return;
+    }
+    navigate(`/projects/${session.project_id}`);
+  };
+
+  const handleStop = async (session: SessionView) => {
+    setActionBusy(session.id);
+    try {
+      await stopInstance(session.project_id, session.repository_id, session.id);
+      await loadHome();
+    } finally {
+      setActionBusy(null);
+    }
+  };
+
+  const handleDelete = async (session: SessionView) => {
+    setActionBusy(session.id);
+    try {
+      await deleteInstance(session.project_id, session.repository_id, session.id);
+      await loadHome();
+    } finally {
+      setActionBusy(null);
+    }
+  };
+
+  const handleRecreateTunnel = async (session: SessionView) => {
+    setActionBusy(session.id);
+    try {
+      await recreateInstanceTunnel(session.project_id, session.repository_id, session.id);
+      await loadHome();
+    } finally {
+      setActionBusy(null);
+    }
+  };
 
   return (
-    <section className="stack">
-      <h1>Dashboard</h1>
-      <p className="muted">Your workspace overview will appear here.</p>
+    <section className="stack home-page">
+      <header className="home-hero card">
+        <div className="stack-sm">
+          <p className="eyebrow">Workspace overview</p>
+          <h1>Home</h1>
+          <p className="muted">Open sessions, available projects, and the fastest path back into work.</p>
+        </div>
+        <div className="home-hero-actions">
+          <button className="primary-button" type="button" onClick={() => navigate("/projects")}>New Project</button>
+          <button className="secondary-button" type="button" onClick={() => navigate("/settings")}>Settings</button>
+        </div>
+      </header>
 
-      {status === "loading" && <p className="muted">Loading dashboard...</p>}
+      {status === "loading" && <p className="muted">Loading overview...</p>}
 
       {status === "error" && (
         <div className="card stack">
-          <p>Dashboard is unavailable</p>
-          <button className="secondary-button" onClick={() => void loadSummary()} type="button">
+          <p>Unable to load your workspace overview.</p>
+          <button className="secondary-button" type="button" onClick={() => void loadHome()}>
+            <Icon name="refresh" size="sm" />
             Retry
           </button>
         </div>
       )}
 
-      <div className="card-grid">
-        {cards.map((card) => (
-          <article className="card" key={card.label}>
+      {status === "ready" && summary && (
+        <>
+          <div className="home-summary-grid">
+            {summaryCards.map((card) => (
+              <article className="card home-summary-card" key={card.label}>
                 <p className="card-label">{card.label}</p>
-            <p className="card-value">{summary ? String(summary[card.key]) : "-"}</p>
+                <p className="card-value">
+                  {card.key === "openSessions"
+                    ? activeSessions.length
+                    : card.key === "projects"
+                      ? summary.projects
+                      : summary.repositories}
+                </p>
               </article>
             ))}
           </div>
 
-      {isEmpty && <p className="muted">No activity yet</p>}
-
-      <div className="quick-actions">
-        <button className="primary-button" type="button">
-          New Project
+          <section className="card stack home-section">
+            <div className="page-header">
+              <div>
+                <p className="eyebrow">Open sessions</p>
+                <h2>{activeSessions.length}</h2>
+              </div>
+            </div>
+            {activeSessions.length === 0 ? (
+              <p className="muted">No active sessions right now.</p>
+            ) : (
+              <div className="home-session-grid">
+                {activeSessions.map((session) => (
+                  <article className="card session-card" key={session.id}>
+                    <div className="stack-sm">
+                      <div className="row row-tight">
+                        <h3>{session.display_name}</h3>
+                        <span className={`status-badge ${session.status}`}>{session.status}</span>
+                      </div>
+                      <p className="muted">{session.project_name} · {session.repository_name}</p>
+                      <p className="muted">{session.tool_type_name}</p>
+                    </div>
+                    <div className="session-actions">
+                      <button className="secondary-button small" type="button" onClick={() => handleOpen(session)}>
+                        <Icon name="external" size="sm" />
+                        Open
                       </button>
-        <button className="secondary-button" type="button">
-          Add Repository
+                      <button className="ghost-button small" type="button" onClick={() => void handleRecreateTunnel(session)} disabled={actionBusy === session.id}>
+                        <Icon name="refresh" size="sm" />
+                        Tunnel
+                      </button>
+                      <button className="ghost-button small" type="button" onClick={() => void handleStop(session)} disabled={actionBusy === session.id}>
+                        <Icon name="stop" size="sm" />
+                        Stop
+                      </button>
+                      <button className="ghost-button small danger-text" type="button" onClick={() => void handleDelete(session)} disabled={actionBusy === session.id}>
+                        <Icon name="delete" size="sm" />
+                        Delete
                       </button>
                     </div>
+                  </article>
+                ))}
+              </div>
+            )}
+          </section>
+
+          <section className="card stack home-section">
+            <div className="page-header">
+              <div>
+                <p className="eyebrow">Available projects</p>
+                <h2>{projects.length}</h2>
+              </div>
+              <button className="secondary-button" type="button" onClick={() => navigate("/projects")}>View all</button>
+            </div>
+            {projects.length === 0 ? (
+              <p className="muted">No projects yet.</p>
+            ) : (
+              <div className="home-project-grid">
+                {projects.map((project) => (
+                  <article className="card project-card home-project-card" key={project.id}>
+                    <div className="stack-sm">
+                      <h3>{project.name}</h3>
+                      {project.description && <p className="muted">{project.description}</p>}
+                    </div>
+                    <button className="ghost-button small" type="button" onClick={() => navigate(`/projects/${project.id}`)}>
+                      Open Workspace
+                    </button>
+                  </article>
+                ))}
+              </div>
+            )}
+          </section>
+
+          <section className="card stack home-section">
+            <div className="page-header">
+              <div>
+                <p className="eyebrow">Quick create</p>
+                <h2>Start a session</h2>
+              </div>
+            </div>
+            <form className="stack create-session-form" onSubmit={handleCreate}>
+              <div className="form-row">
+                <label className="form-field">
+                  Project
+                  <select value={selectedProject} onChange={(event) => { setSelectedProject(event.target.value); setSelectedRepo(""); }}>
+                    <option value="">Select project...</option>
+                    {projects.map((project) => <option key={project.id} value={project.id}>{project.name}</option>)}
+                  </select>
+                </label>
+                <label className="form-field">
+                  Repository
+                  <select value={selectedRepo} onChange={(event) => setSelectedRepo(event.target.value)} disabled={!selectedProject}>
+                    <option value="">Select repository...</option>
+                    {repositories.map((repo) => <option key={repo.id} value={repo.id}>{repo.name}</option>)}
+                  </select>
+                </label>
+                <label className="form-field">
+                  Tool type
+                  <select value={selectedToolType} onChange={(event) => setSelectedToolType(event.target.value)}>
+                    <option value="">Select tool...</option>
+                  {toolTypes.map((tool) => <option key={tool.id} value={tool.id}>{tool.display_name}</option>)}
+                </select>
+              </label>
+              </div>
+              <label className="form-field">
+                Display name
+                <input type="text" value={displayName} onChange={(event) => setDisplayName(event.target.value)} placeholder="My Development Environment" />
+              </label>
+              <div className="form-actions">
+                <button className="primary-button" type="submit" disabled={saveState === "saving"}>
+                  {saveState === "saving" ? <><Icon name="loading" size="sm" /> Creating...</> : <><Icon name="add" size="sm" /> Create Session</>}
+                </button>
+                {saveState === "error" && <span className="error-text">Failed to create session</span>}
+              </div>
+            </form>
+          </section>
+
+          {recentSessions.length > 0 && (
+            <section className="card stack home-section">
+              <div className="page-header">
+                <div>
+                  <p className="eyebrow">Recent sessions</p>
+                  <h2>{recentSessions.length}</h2>
+                </div>
+              </div>
+              <div className="recent-sessions-list">
+                {recentSessions.map((session) => (
+                  <article className="recent-session-item" key={session.id}>
+                    <div className="recent-session-info">
+                      <span className="recent-session-name">{session.display_name}</span>
+                      <span className="muted">{session.project_name} · {session.tool_type_name}</span>
+                    </div>
+                    <button className="ghost-button small" type="button" onClick={() => handleOpen(session)}>Open</button>
+                  </article>
+                ))}
+              </div>
+            </section>
+          )}
+        </>
+      )}
     </section>
   );
 };
+
+export { HomePage as DashboardPage };

apps/web/src/pages/git-history.tsx

@@ -2,6 +2,7 @@ import { useCallback, useEffect, useState } from "react";
 import { useNavigate, useParams } from "react-router-dom";
 
 import { getCommitDetail, getRepositoryHistory, type CommitDetail, type CommitHistoryEntry } from "../api/git_repositories";
+import { Icon } from "../components/icon";
 
 export const GitHistoryPage = () => {
   const { projectId, repoId } = useParams<{ projectId: string; repoId: string }>();
@@ -70,6 +71,7 @@ export const GitHistoryPage = () => {
       <section className="stack">
         <p>Failed to load commit history</p>
         <button className="secondary-button" onClick={() => void loadHistory()} type="button">
+          <Icon name="refresh" size="sm" />
           Retry
         </button>
       </section>
@@ -155,7 +157,7 @@ export const GitHistoryPage = () => {
             <div className="detail-header">
               <h3>Commit Details</h3>
               <button className="ghost-button" onClick={handleCloseDetail} type="button">
-                ×
+                <Icon name="close" size="sm" />
               </button>
             </div>
 

apps/web/src/pages/git-repositories.tsx

@@ -1,18 +1,15 @@
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useState } from "react";
 import { useNavigate, useParams } from "react-router-dom";
 
 import {
-  createRepository,
   deleteRepository,
   listRepositories,
-  parseGitUrl,
-  type GitRepositoryCreate,
-  type URLParseResult,
 } from "../api/git_repositories";
 import type { GitRepository } from "../api/git_repositories";
+import { Icon } from "../components/icon";
+import { RepositoryCreateDialog } from "../components/repository-create-dialog";
 
 type RepoStatus = "loading" | "ready" | "error";
-type UrlValidationStatus = "idle" | "validating" | "valid" | "needs-parsing" | "invalid";
 
 export const GitRepositoriesPage = () => {
   const { projectId } = useParams<{ projectId: string }>();
@@ -20,19 +17,8 @@ export const GitRepositoriesPage = () => {
   const [status, setStatus] = useState<RepoStatus>("loading");
   const [repositories, setRepositories] = useState<GitRepository[]>([]);
   const [showCreate, setShowCreate] = useState(false);
-  const [formName, setFormName] = useState("");
-  const [formRemoteUrl, setFormRemoteUrl] = useState("");
-  const [formError, setFormError] = useState<string | null>(null);
   const [deleteConfirmId, setDeleteConfirmId] = useState<string | null>(null);
 
-  // URL validation state
-  const [urlValidation, setUrlValidation] = useState<{
-    status: UrlValidationStatus;
-    result: URLParseResult | null;
-  }>({ status: "idle", result: null });
-
-  const debounceTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
-
   const loadRepositories = useCallback(async () => {
     if (!projectId) return;
     setStatus("loading");
@@ -50,98 +36,6 @@ export const GitRepositoriesPage = () => {
     void loadRepositories();
   }, [loadRepositories]);
 
-  // Validate URL with debounce
-  useEffect(() => {
-    if (debounceTimer.current) {
-      clearTimeout(debounceTimer.current);
-    }
-
-    if (!formRemoteUrl.trim()) {
-      setUrlValidation({ status: "idle", result: null });
-      return;
-    }
-
-    setUrlValidation({ status: "validating", result: null });
-
-    debounceTimer.current = setTimeout(async () => {
-      try {
-        const result = await parseGitUrl(formRemoteUrl.trim());
-        if (result.is_valid_clone_url) {
-          setUrlValidation({ status: "valid", result });
-        } else if (result.needs_parsing) {
-          setUrlValidation({ status: "needs-parsing", result });
-        } else {
-          setUrlValidation({ status: "invalid", result });
-        }
-      } catch {
-        setUrlValidation({ status: "invalid", result: null });
-      }
-    }, 300);
-
-    return () => {
-      if (debounceTimer.current) {
-        clearTimeout(debounceTimer.current);
-      }
-    };
-  }, [formRemoteUrl]);
-
-  const getUrlInputClass = () => {
-    switch (urlValidation.status) {
-      case "valid":
-        return "valid-url";
-      case "needs-parsing":
-        return "needs-parsing-url";
-      case "invalid":
-        return "invalid-url";
-      default:
-        return "";
-    }
-  };
-
-  const handleSubmit = async (e: React.FormEvent) => {
-    e.preventDefault();
-    setFormError(null);
-
-    if (!formName.trim()) {
-      setFormError("Repository name is required");
-      return;
-    }
-
-    if (!projectId) return;
-
-    try {
-      const input: GitRepositoryCreate = {
-        name: formName.trim(),
-        remote_url: formRemoteUrl.trim() || undefined,
-      };
-      await createRepository(projectId, input);
-      setShowCreate(false);
-      setFormName("");
-      setFormRemoteUrl("");
-      setUrlValidation({ status: "idle", result: null });
-      await loadRepositories();
-    } catch (err: unknown) {
-      const axiosError = err as { response?: { status: number; data: { detail: { suggested_url: string; message: string } } } };
-      if (axiosError.response?.status === 422 && axiosError.response?.data?.detail?.suggested_url) {
-        // Show URL correction suggestion
-        const detail = axiosError.response.data.detail;
-        setFormError(
-          `${detail.message}\nSuggested: ${detail.suggested_url}`
-        );
-      } else {
-        setFormError("Failed to create repository");
-      }
-    }
-  };
-
-  const handleUseSuggestedUrl = () => {
-    if (urlValidation.result?.base_url) {
-      setFormRemoteUrl(urlValidation.result.base_url);
-      setUrlValidation({ status: "idle", result: null });
-      setFormError(null);
-    }
-  };
-
   const handleDelete = async (repoId: string) => {
     if (!projectId) return;
     try {
@@ -160,6 +54,7 @@ export const GitRepositoriesPage = () => {
       <div className="page-header">
         <h1>Repositories</h1>
         <button className="primary-button" onClick={() => setShowCreate(true)} type="button">
+          <Icon name="add" size="sm" />
           New Repository
         </button>
       </div>
@@ -170,6 +65,7 @@ export const GitRepositoriesPage = () => {
         <div className="card stack">
           <p>Failed to load repositories</p>
           <button className="secondary-button" onClick={() => void loadRepositories()} type="button">
+            <Icon name="refresh" size="sm" />
             Retry
           </button>
         </div>
@@ -230,77 +126,13 @@ export const GitRepositoriesPage = () => {
       )}
 
       {showCreate && (
-        <div className="dialog-overlay" role="dialog" aria-modal="true">
-          <div className="dialog">
-            <h2>Create Repository</h2>
-            <form onSubmit={handleSubmit} className="stack">
-              <label className="form-field">
-                Name
-                <input
-                  type="text"
-                  value={formName}
-                  onChange={(e) => setFormName(e.target.value)}
-                  placeholder="repository-name"
+        <RepositoryCreateDialog
+          projectId={projectId!}
+          open={showCreate}
+          title="Create Repository"
+          onClose={() => setShowCreate(false)}
+          onCreated={loadRepositories}
         />
-              </label>
-              <label className="form-field">
-                Remote URL (optional)
-                <input
-                  type="text"
-                  value={formRemoteUrl}
-                  onChange={(e) => setFormRemoteUrl(e.target.value)}
-                  placeholder="https://github.com/user/repo.git"
-                  className={getUrlInputClass()}
-                />
-                {urlValidation.status === "validating" && (
-                  <span className="validation-status validating">Validating...</span>
-                )}
-                {urlValidation.status === "valid" && (
-                  <span className="validation-status valid">✓ Valid git URL</span>
-                )}
-                {urlValidation.status === "needs-parsing" && urlValidation.result && (
-                  <div className="url-suggestion">
-                    <span className="validation-status warning">
-                      ⚠ This looks like a browser URL
-                    </span>
-                    <div className="suggestion-actions">
-                      <span className="suggested-url">
-                        Suggested: {urlValidation.result.base_url}
-                      </span>
-                      <button
-                        type="button"
-                        className="secondary-button small"
-                        onClick={handleUseSuggestedUrl}
-                      >
-                        Use Suggested
-                      </button>
-                    </div>
-                  </div>
-                )}
-                {urlValidation.status === "invalid" && (
-                  <span className="validation-status invalid">
-                    ✗ Invalid URL
-                  </span>
-                )}
-              </label>
-              {formError && (
-                <div className="error-message">
-                  {formError.split("\n").map((line, i) => (
-                    <p key={i} className="error-text">{line}</p>
-                  ))}
-                </div>
-              )}
-              <div className="dialog-actions">
-                <button className="secondary-button" onClick={() => setShowCreate(false)} type="button">
-                  Cancel
-                </button>
-                <button className="primary-button" type="submit">
-                  Create
-                </button>
-              </div>
-            </form>
-          </div>
-        </div>
       )}
     </section>
   );

apps/web/src/pages/placeholder.tsx

@@ -18,6 +18,8 @@ export const NotFoundPage = () => {
 
 const API_BASE_URL = import.meta.env.VITE_API_BASE_URL ?? "http://localhost:8000";
 
+import { Icon } from "../components/icon";
+
 export const LoginRedirectPage = () => {
   const nextPath = new URLSearchParams(window.location.search).get("next") ?? "/";
   const encodedNext = encodeURIComponent(nextPath);
@@ -27,6 +29,7 @@ export const LoginRedirectPage = () => {
       <h1>Sign in required</h1>
       <p className="muted">You need to authenticate to access this section.</p>
       <a className="primary-button" href={`${API_BASE_URL}/auth/login?next=${encodedNext}`}>
+        <Icon name="profile" size="sm" />
         Continue to login
       </a>
     </section>

apps/web/src/pages/profile.tsx

@@ -1,6 +1,7 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 
 import { getProfile, updateProfile, uploadAvatar } from "../api/profile";
+import { Icon } from "../components/icon";
 import { useAuth } from "../state/auth";
 import type { UserProfile } from "../api/profile";
 
@@ -99,6 +100,7 @@ export const ProfilePage = () => {
         <div className="card stack">
           <p>Failed to load profile</p>
           <button className="secondary-button" onClick={() => void loadProfile()} type="button">
+            <Icon name="refresh" size="sm" />
             Retry
           </button>
         </div>
@@ -120,7 +122,17 @@ export const ProfilePage = () => {
               onClick={() => fileInputRef.current?.click()}
               type="button"
             >
-              {status === "saving" ? "Uploading..." : "Change Avatar"}
+              {status === "saving" ? (
+                <>
+                  <Icon name="loading" size="sm" />
+                  Uploading...
+                </>
+              ) : (
+                <>
+                  <Icon name="edit" size="sm" />
+                  Change Avatar
+                </>
+              )}
             </button>
             <input
               accept="image/png,image/jpeg"
@@ -162,7 +174,17 @@ export const ProfilePage = () => {
               onClick={() => void handleSave()}
               type="button"
             >
-              {status === "saving" ? "Saving..." : "Save Changes"}
+              {status === "saving" ? (
+                <>
+                  <Icon name="loading" size="sm" />
+                  Saving...
+                </>
+              ) : (
+                <>
+                  <Icon name="save" size="sm" />
+                  Save Changes
+                </>
+              )}
             </button>
           </div>
         </div>

apps/web/src/pages/project-settings.tsx

@@ -0,0 +1,148 @@
+import React, { useState, useEffect } from "react";
+import { useParams, Link, useNavigate, Routes, Route } from "react-router-dom";
+import { SettingsTabLayout } from "../components/settings-tab-layout";
+import { RepositoriesSettingsTab } from "../components/repositories-settings-tab";
+import { apiClient } from "../api/client";
+import { Project } from "../types";
+
+const tabs = [
+  { id: "general", label: "General", path: "general" },
+  { id: "repositories", label: "Repositories", path: "repositories" },
+  { id: "members", label: "Members", path: "members" },
+];
+
+const GeneralSettings: React.FC<{
+  project: Project;
+  projectId: string;
+}> = ({ project, projectId }) => {
+  const navigate = useNavigate();
+  const [name, setName] = useState(project.name);
+  const [description, setDescription] = useState(project.description || "");
+  const [saving, setSaving] = useState(false);
+  const [error, setError] = useState("");
+
+  const handleSave = async () => {
+    setSaving(true);
+    try {
+      await apiClient.patch(`/projects/${projectId}`, {
+        name,
+        description,
+      });
+    } catch (err) {
+      setError("Failed to save changes");
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  const handleDelete = async () => {
+    if (!window.confirm("Are you sure you want to delete this project?")) return;
+    try {
+      await apiClient.delete(`/projects/${projectId}`);
+      navigate("/projects");
+    } catch (err) {
+      setError("Failed to delete project");
+    }
+  };
+
+  return (
+    <div className="settings-panel">
+      <h2>General Settings</h2>
+      {error && <div className="error-message">{error}</div>}
+
+      <div className="form-group">
+        <label>Project Name</label>
+        <input
+          type="text"
+          value={name}
+          onChange={(e) => setName(e.target.value)}
+          className="form-input"
+        />
+      </div>
+
+      <div className="form-group">
+        <label>Description</label>
+        <textarea
+          value={description}
+          onChange={(e) => setDescription(e.target.value)}
+          className="form-textarea"
+          rows={4}
+        />
+      </div>
+
+      <div className="form-actions">
+        <button
+          onClick={handleSave}
+          disabled={saving}
+          className="btn-primary"
+        >
+          {saving ? "Saving..." : "Save Changes"}
+        </button>
+      </div>
+
+      <div className="danger-zone">
+        <h3>Danger Zone</h3>
+        <button onClick={handleDelete} className="btn-danger">
+          Delete Project
+        </button>
+      </div>
+    </div>
+  );
+};
+
+const MembersSettingsTab: React.FC = () => (
+  <div className="settings-panel">
+    <h2>Members</h2>
+    <p>Team members management coming soon.</p>
+  </div>
+);
+
+export const ProjectSettingsPage: React.FC = () => {
+  const { projectId } = useParams<{ projectId: string }>();
+  const [project, setProject] = useState<Project | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState("");
+
+  useEffect(() => {
+    const fetchProject = async () => {
+      try {
+        const response = await apiClient.get(`/projects/${projectId}`);
+        setProject(response.data);
+      } catch (err) {
+        setError("Failed to load project");
+      } finally {
+        setLoading(false);
+      }
+    };
+
+    fetchProject();
+  }, [projectId]);
+
+  if (loading) return <div>Loading...</div>;
+  if (error) return <div className="error-message">{error}</div>;
+  if (!project) return <div>Project not found</div>;
+
+  return (
+    <div className="project-settings-page">
+      <div className="settings-breadcrumb">
+        <Link to="/projects">Projects</Link>
+        <span> &gt; </span>
+        <Link to={`/projects/${projectId}`}>{project.name}</Link>
+        <span> &gt; </span>
+        <span>Settings</span>
+      </div>
+
+      <SettingsTabLayout tabs={tabs} basePath={`/projects/${projectId}/settings`}>
+        <Routes>
+          <Route
+            path="general"
+            element={<GeneralSettings project={project} projectId={projectId!} />}
+          />
+          <Route path="repositories" element={<RepositoriesSettingsTab />} />
+          <Route path="members" element={<MembersSettingsTab />} />
+          <Route path="*" element={<GeneralSettings project={project} projectId={projectId!} />} />
+        </Routes>
+      </SettingsTabLayout>
+    </div>
+  );
+};

apps/web/src/pages/projects.test.tsx

@@ -1,4 +1,5 @@
 import { cleanup, fireEvent, render, screen, waitFor, within } from "@testing-library/react";
+import { MemoryRouter } from "react-router-dom";
 import { afterEach, describe, expect, it, vi } from "vitest";
 
 import { ProjectsPage } from "./projects";
@@ -29,13 +30,21 @@ afterEach(() => {
 describe("ProjectsPage", () => {
   it("renders loading state initially", () => {
     vi.spyOn(projectsApi, "listProjects").mockImplementation(() => new Promise(() => {}));
-    render(<ProjectsPage />);
+    render(
+      <MemoryRouter>
+        <ProjectsPage />
+      </MemoryRouter>
+    );
     expect(screen.getByText(/loading projects/i)).toBeInTheDocument();
   });
 
   it("renders project list after loading", async () => {
     vi.spyOn(projectsApi, "listProjects").mockResolvedValue(mockProjects);
-    render(<ProjectsPage />);
+    render(
+      <MemoryRouter>
+        <ProjectsPage />
+      </MemoryRouter>
+    );
 
     await waitFor(() => {
       expect(screen.getByText("Alpha Project")).toBeInTheDocument();
@@ -46,7 +55,11 @@ describe("ProjectsPage", () => {
 
   it("renders empty state when no projects", async () => {
     vi.spyOn(projectsApi, "listProjects").mockResolvedValue([]);
-    render(<ProjectsPage />);
+    render(
+      <MemoryRouter>
+        <ProjectsPage />
+      </MemoryRouter>
+    );
 
     await waitFor(() => {
       expect(screen.getByText(/no projects yet/i)).toBeInTheDocument();
@@ -55,7 +68,11 @@ describe("ProjectsPage", () => {
 
   it("renders error state with retry button", async () => {
     vi.spyOn(projectsApi, "listProjects").mockRejectedValue(new Error("fail"));
-    render(<ProjectsPage />);
+    render(
+      <MemoryRouter>
+        <ProjectsPage />
+      </MemoryRouter>
+    );
 
     await waitFor(() => {
       expect(screen.getByText(/failed to load projects/i)).toBeInTheDocument();
@@ -67,7 +84,11 @@ describe("ProjectsPage", () => {
     const listMock = vi.spyOn(projectsApi, "listProjects").mockResolvedValue([]);
     const createMock = vi.spyOn(projectsApi, "createProject").mockResolvedValue(mockProjects[0]);
 
-    render(<ProjectsPage />);
+    render(
+      <MemoryRouter>
+        <ProjectsPage />
+      </MemoryRouter>
+    );
 
     await waitFor(() => {
       expect(screen.getByText(/no projects yet/i)).toBeInTheDocument();
@@ -96,7 +117,11 @@ describe("ProjectsPage", () => {
   it("shows validation error when name is empty", async () => {
     vi.spyOn(projectsApi, "listProjects").mockResolvedValue([]);
 
-    render(<ProjectsPage />);
+    render(
+      <MemoryRouter>
+        <ProjectsPage />
+      </MemoryRouter>
+    );
 
     await waitFor(() => {
       expect(screen.getByText(/no projects yet/i)).toBeInTheDocument();
@@ -112,7 +137,11 @@ describe("ProjectsPage", () => {
     const listMock = vi.spyOn(projectsApi, "listProjects").mockResolvedValue(mockProjects);
     const updateMock = vi.spyOn(projectsApi, "updateProject").mockResolvedValue(mockProjects[0]);
 
-    render(<ProjectsPage />);
+    render(
+      <MemoryRouter>
+        <ProjectsPage />
+      </MemoryRouter>
+    );
 
     await waitFor(() => {
       expect(screen.getByText("Alpha Project")).toBeInTheDocument();
@@ -141,7 +170,11 @@ describe("ProjectsPage", () => {
     const listMock = vi.spyOn(projectsApi, "listProjects").mockResolvedValue(mockProjects);
     const deleteMock = vi.spyOn(projectsApi, "deleteProject").mockResolvedValue(undefined);
 
-    render(<ProjectsPage />);
+    render(
+      <MemoryRouter>
+        <ProjectsPage />
+      </MemoryRouter>
+    );
 
     await waitFor(() => {
       expect(screen.getByText("Alpha Project")).toBeInTheDocument();

apps/web/src/pages/projects.tsx

@@ -10,6 +10,7 @@ import {
   type ProjectCreateInput,
   type ProjectUpdateInput,
 } from "../api/projects";
+import { Icon } from "../components/icon";
 import type { Project } from "../types";
 
 type ProjectsStatus = "loading" | "ready" | "error";
@@ -110,6 +111,7 @@ export const ProjectsPage = () => {
       <div className="page-header">
         <h1>Projects</h1>
         <button className="primary-button" onClick={openCreate} type="button">
+          <Icon name="add" size="sm" />
           New Project
         </button>
       </div>
@@ -120,6 +122,7 @@ export const ProjectsPage = () => {
         <div className="card stack">
           <p>Failed to load projects</p>
           <button className="secondary-button" onClick={() => void loadProjects()} type="button">
+            <Icon name="refresh" size="sm" />
             Retry
           </button>
         </div>
@@ -144,6 +147,7 @@ export const ProjectsPage = () => {
                   onClick={() => openEdit(project)}
                   type="button"
                 >
+                  <Icon name="edit" size="sm" />
                   Edit
                 </button>
                 {deleteConfirmId === project.id ? (
@@ -154,6 +158,7 @@ export const ProjectsPage = () => {
                       onClick={() => void handleDelete(project.id)}
                       type="button"
                     >
+                      <Icon name="delete" size="sm" />
                       Delete
                     </button>
                     <button
@@ -161,6 +166,7 @@ export const ProjectsPage = () => {
                       onClick={() => setDeleteConfirmId(null)}
                       type="button"
                     >
+                      <Icon name="cancel" size="sm" />
                       Cancel
                     </button>
                   </div>
@@ -170,6 +176,7 @@ export const ProjectsPage = () => {
                     onClick={() => setDeleteConfirmId(project.id)}
                     type="button"
                   >
+                    <Icon name="delete" size="sm" />
                     Delete
                   </button>
                 )}
@@ -205,10 +212,21 @@ export const ProjectsPage = () => {
               {formError && <p className="error-text">{formError}</p>}
               <div className="dialog-actions">
                 <button className="secondary-button" onClick={closeDialog} type="button">
+                  <Icon name="cancel" size="sm" />
                   Cancel
                 </button>
                 <button className="primary-button" type="submit">
-                  {dialogMode === "create" ? "Create" : "Save"}
+                  {dialogMode === "create" ? (
+                    <>
+                      <Icon name="add" size="sm" />
+                      Create
+                    </>
+                  ) : (
+                    <>
+                      <Icon name="save" size="sm" />
+                      Save
+                    </>
+                  )}
                 </button>
               </div>
             </form>

apps/web/src/pages/repo-workspace.tsx

@@ -1,9 +1,22 @@
 import { useCallback, useEffect, useState } from "react";
+import { Icon } from "../components/icon";
 
 import { Link, useParams, useSearchParams } from "react-router-dom";
 
 import { apiClient } from "../api/client";
-import { listRepositories, type GitRepository } from "../api/git_repositories";
+import {
+  getRepositoryStatus,
+  listRepositories,
+  type GitRepository,
+  type GitStatus,
+} from "../api/git_repositories";
+import { CommitPanel } from "../components/commit-panel";
+import { FileEditor } from "../components/file-editor";
+import { GitToolbar } from "../components/git-toolbar";
+import { InstanceList } from "../components/instance-list";
+import { WorkspaceHeader } from "../components/workspace-header";
+import { listToolTypes } from "../api/tool_types";
+import type { ToolType } from "../api/tool_types";
 
 type WorkspaceStatus = "loading" | "ready" | "error" | "empty";
 
@@ -21,15 +34,36 @@ interface FileTreeEntry {
   } | null;
 }
 
+interface Project {
+  id: string;
+  name: string;
+  description?: string | null;
+}
+
 export const RepoWorkspace = () => {
   const { projectId } = useParams<{ projectId: string }>();
   const [searchParams, setSearchParams] = useSearchParams();
 
   const [status, setStatus] = useState<WorkspaceStatus>("loading");
+  const [project, setProject] = useState<Project | null>(null);
   const [repositories, setRepositories] = useState<GitRepository[]>([]);
   const [selectedRepoId, setSelectedRepoId] = useState<string | null>(
     searchParams.get("repo")
   );
+  const [branches, setBranches] = useState<string[]>([]);
+  const [currentBranch, setCurrentBranch] = useState<string>("main");
+  const [gitStatus, setGitStatus] = useState<GitStatus | null>(null);
+  const [toolTypes, setToolTypes] = useState<ToolType[]>([]);
+
+  const loadProject = useCallback(async () => {
+    if (!projectId) return;
+    try {
+      const response = await apiClient.get(`/projects/${projectId}`);
+      setProject(response.data);
+    } catch {
+      setProject(null);
+    }
+  }, [projectId]);
 
   const loadRepositories = useCallback(async () => {
     if (!projectId) return;
@@ -57,9 +91,52 @@ export const RepoWorkspace = () => {
     }
   }, [projectId, selectedRepoId, searchParams, setSearchParams]);
 
+  const loadBranches = useCallback(async () => {
+    if (!projectId || !selectedRepoId) return;
+    try {
+      const response = await apiClient.get(
+        `/projects/${projectId}/repositories/${selectedRepoId}/branches`
+      );
+      const branchList = response.data.branches.map((b: { name: string }) => b.name);
+      setBranches(branchList);
+      const defaultBranch = response.data.default_branch;
+      if (defaultBranch) {
+        setCurrentBranch(defaultBranch);
+      }
+    } catch {
+      setBranches([]);
+    }
+  }, [projectId, selectedRepoId]);
+
+  const loadGitStatus = useCallback(async () => {
+    if (!projectId || !selectedRepoId) return;
+    try {
+      const data = await getRepositoryStatus(projectId, selectedRepoId);
+      setGitStatus(data);
+    } catch {
+      setGitStatus(null);
+    }
+  }, [projectId, selectedRepoId]);
+
+  const loadToolTypes = useCallback(async () => {
+    try {
+      const data = await listToolTypes();
+      setToolTypes(data);
+    } catch {
+      setToolTypes([]);
+    }
+  }, []);
+
   useEffect(() => {
+    void loadProject();
     void loadRepositories();
-  }, [loadRepositories]);
+    void loadToolTypes();
+  }, [loadProject, loadRepositories, loadToolTypes]);
+
+  useEffect(() => {
+    void loadBranches();
+    void loadGitStatus();
+  }, [loadBranches, loadGitStatus]);
 
   const handleRepoChange = (repoId: string) => {
     setSelectedRepoId(repoId);
@@ -74,20 +151,12 @@ export const RepoWorkspace = () => {
 
   return (
     <section className="repo-workspace">
-      <div className="workspace-header">
-        <div className="workspace-title">
-          <h1>Repository Workspace</h1>
-          {selectedRepo && <span className="repo-name">{selectedRepo.name}</span>}
-        </div>
-        <div className="workspace-actions">
-          <Link
-            className="secondary-button"
-            to={`/projects/${projectId}/repositories`}
-          >
-            Manage Repositories
-          </Link>
-        </div>
-      </div>
+      {project && (
+        <WorkspaceHeader
+          project={project}
+          currentRepo={selectedRepo || null}
+        />
+      )}
 
       {status === "loading" && (
         <p className="muted">Loading repositories...</p>
@@ -101,6 +170,7 @@ export const RepoWorkspace = () => {
             onClick={() => void loadRepositories()}
             type="button"
           >
+            <Icon name="refresh" size="sm" />
             Retry
           </button>
         </div>
@@ -111,14 +181,35 @@ export const RepoWorkspace = () => {
           <p>No repositories in this project yet.</p>
           <Link
             className="primary-button"
-            to={`/projects/${projectId}/repositories`}
+            to={`/projects/${projectId}/settings/repositories`}
           >
-            Add Repository
+            Manage Repositories
           </Link>
         </div>
       )}
 
       {status === "ready" && repositories.length > 0 && (
+        <>
+          {selectedRepoId && (
+            <GitToolbar
+              projectId={projectId!}
+              repoId={selectedRepoId}
+              currentBranch={currentBranch}
+              branches={branches}
+              hasRemote={Boolean(selectedRepo?.remote_url)}
+              onBranchChange={(branch) => {
+                setCurrentBranch(branch);
+                const newParams = new URLSearchParams(searchParams);
+                newParams.set("branch", branch);
+                setSearchParams(newParams);
+              }}
+              onRefresh={() => {
+                void loadBranches();
+                void loadGitStatus();
+                window.dispatchEvent(new CustomEvent("refresh-file-tree"));
+              }}
+            />
+          )}
           <div className="workspace-layout">
             <aside className="workspace-sidebar">
               <div className="sidebar-section">
@@ -138,19 +229,44 @@ export const RepoWorkspace = () => {
               </div>
 
               {selectedRepoId && (
+                <>
                   <FileBrowser
                     projectId={projectId!}
                     repoId={selectedRepoId}
+                    gitStatus={gitStatus}
                   />
+                {gitStatus && (
+                  <CommitPanel
+                    projectId={projectId!}
+                    repoId={selectedRepoId}
+                    modified={gitStatus.modified}
+                    added={gitStatus.added}
+                    deleted={gitStatus.deleted}
+                    untracked={gitStatus.untracked}
+                    onCommit={() => {
+                      void loadGitStatus();
+                      window.dispatchEvent(new CustomEvent("refresh-file-tree"));
+                    }}
+                  />
+                )}
+                {selectedRepoId && (
+                  <InstanceList
+                    projectId={projectId!}
+                    repoId={selectedRepoId}
+                    toolTypes={toolTypes}
+                  />
+                )}
+              </>
             )}
           </aside>
 
           <main className="workspace-main">
             {selectedRepoId && (
-              <FileViewer projectId={projectId!} repoId={selectedRepoId} />
+              <FileEditor projectId={projectId!} repoId={selectedRepoId} />
             )}
           </main>
         </div>
+      </>
       )}
     </section>
   );
@@ -160,9 +276,11 @@ export const RepoWorkspace = () => {
 const FileBrowser = ({
   projectId,
   repoId,
+  gitStatus,
 }: {
   projectId: string;
   repoId: string;
+  gitStatus: GitStatus | null;
 }) => {
   const [searchParams, setSearchParams] = useSearchParams();
   const [entries, setEntries] = useState<FileTreeEntry[]>([]);
@@ -197,6 +315,13 @@ const FileBrowser = ({
     void loadFiles();
   }, [loadFiles]);
 
+  // Listen for refresh events
+  useEffect(() => {
+    const handleRefresh = () => void loadFiles();
+    window.addEventListener("refresh-file-tree", handleRefresh);
+    return () => window.removeEventListener("refresh-file-tree", handleRefresh);
+  }, [loadFiles]);
+
   const handleEntryClick = (entry: FileTreeEntry) => {
     if (entry.type === "directory") {
       const newParams = new URLSearchParams(searchParams);
@@ -221,6 +346,15 @@ const FileBrowser = ({
     setSearchParams(newParams);
   };
 
+  const getFileStatus = (filePath: string): string | null => {
+    if (!gitStatus) return null;
+    if (gitStatus.modified.includes(filePath)) return "modified";
+    if (gitStatus.added.includes(filePath)) return "added";
+    if (gitStatus.deleted.includes(filePath)) return "deleted";
+    if (gitStatus.untracked.includes(filePath)) return "untracked";
+    return null;
+  };
+
   if (loading) return <p className="muted">Loading files...</p>;
   if (error) return <p className="error-text">{error}</p>;
 
@@ -228,109 +362,33 @@ const FileBrowser = ({
     <div className="file-tree">
       {path && (
         <button className="tree-entry tree-up" onClick={navigateUp} type="button">
-          📁 ..
+          <Icon name="folder" size="sm" /> ..
         </button>
       )}
-      {entries.map((entry) => (
+      {entries.length === 0 && (
+        <p className="muted">No files in this repository yet.</p>
+      )}
+      {entries.map((entry) => {
+        const fileStatus = entry.type === "file" ? getFileStatus(entry.path) : null;
+        return (
           <button
             key={entry.path}
-          className={`tree-entry ${entry.type === "directory" ? "tree-directory" : "tree-file"}`}
+            className={`tree-entry ${entry.type === "directory" ? "tree-directory" : "tree-file"} ${fileStatus || ""}`}
             onClick={() => handleEntryClick(entry)}
             type="button"
           >
-          {entry.type === "directory" ? "📁" : "📄"} {entry.name}
-        </button>
-      ))}
-    </div>
-  );
-};
-
-// File Viewer Component
-const FileViewer = ({
-  projectId,
-  repoId,
-}: {
-  projectId: string;
-  repoId: string;
-}) => {
-  const [searchParams] = useSearchParams();
-  const [content, setContent] = useState<string | null>(null);
-  const [loading, setLoading] = useState(false);
-  const [error, setError] = useState<string | null>(null);
-  const [isBinary, setIsBinary] = useState(false);
-
-  const branch = searchParams.get("branch") || "main";
-  const filePath = searchParams.get("file");
-
-  const loadFile = useCallback(async () => {
-    if (!filePath) {
-      setContent(null);
-      return;
-    }
-
-    setLoading(true);
-    setError(null);
-    try {
-      const response = await apiClient.get(
-        `/projects/${projectId}/repositories/${repoId}/files/content`,
-        {
-          params: {
-            branch,
-            path: filePath,
-          },
-        }
-      );
-      const data = response.data;
-      if (data.is_binary) {
-        setIsBinary(true);
-        setContent("Binary file - cannot display");
-      } else {
-        setIsBinary(false);
-        setContent(data.content);
-      }
-    } catch {
-      setError("Failed to load file");
-    } finally {
-      setLoading(false);
-    }
-  }, [projectId, repoId, branch, filePath]);
-
-  useEffect(() => {
-    void loadFile();
-  }, [loadFile]);
-
-  if (!filePath) {
-    return (
-      <div className="file-viewer-empty">
-        <p className="muted">Select a file to view its contents</p>
-      </div>
-    );
-  }
-
-  if (loading) return <p className="muted">Loading file...</p>;
-  if (error) return <p className="error-text">{error}</p>;
-
-  return (
-    <div className="file-viewer">
-      <div className="file-viewer-header">
-        <div className="file-breadcrumbs">
-          {filePath.split("/").map((part, i, arr) => (
-            <span key={i}>
-              {part}
-              {i < arr.length - 1 && <span className="breadcrumb-sep">/</span>}
+            <Icon name={entry.type === "directory" ? "folder" : "file"} size="sm" /> {entry.name}
+            {fileStatus && (
+              <span className={`file-status-indicator ${fileStatus}`}>
+                {fileStatus === "modified" && "M"}
+                {fileStatus === "added" && "A"}
+                {fileStatus === "deleted" && "D"}
+                {fileStatus === "untracked" && "?"}
               </span>
-          ))}
-        </div>
-      </div>
-      <div className="file-content">
-        {isBinary ? (
-          <p className="muted">{content}</p>
-        ) : (
-          <pre>
-            <code>{content}</code>
-          </pre>
             )}
-      </div>
+          </button>
+        );
+      })}
     </div>
   );
 };

apps/web/src/pages/sessions.tsx

@@ -0,0 +1,648 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { useNavigate } from "react-router-dom";
+
+import { listProjects } from "../api/projects";
+import type { Project } from "../types";
+import { listRepositories, type GitRepository } from "../api/git_repositories";
+import {
+  getUserSessions,
+  type Session,
+  deleteInstance,
+  stopInstance,
+  startInstance,
+  checkInstanceHealth,
+  recreateInstanceTunnel,
+} from "../api/sessions";
+import { listToolTypes, type ToolType } from "../api/tool_types";
+import { createInstance } from "../api/sessions";
+import { getUserConfig, updateUserConfig } from "../api/settings";
+import { Icon } from "../components/icon";
+
+type SessionsStatus = "loading" | "ready" | "error";
+type CreateStatus = "idle" | "creating" | "error";
+
+export const SessionsPage = () => {
+  const navigate = useNavigate();
+  const [status, setStatus] = useState<SessionsStatus>("loading");
+  const [sessions, setSessions] = useState<Session[]>([]);
+  const [lastSessionId, setLastSessionId] = useState<string | null>(null);
+
+  const [projects, setProjects] = useState<Project[]>([]);
+  const [repositories, setRepositories] = useState<GitRepository[]>([]);
+  const [toolTypes, setToolTypes] = useState<ToolType[]>([]);
+
+  const [selectedProject, setSelectedProject] = useState<string>("");
+  const [selectedRepo, setSelectedRepo] = useState<string>("");
+  const [selectedToolType, setSelectedToolType] = useState<string>("");
+  const [displayName, setDisplayName] = useState("");
+  const [createStatus, setCreateStatus] = useState<CreateStatus>("idle");
+  const [createError, setCreateError] = useState<string | null>(null);
+
+  const [deleteConfirmId, setDeleteConfirmId] = useState<string | null>(null);
+  const [stopConfirmId, setStopConfirmId] = useState<string | null>(null);
+  const [tunnelHealth, setTunnelHealth] = useState<Record<string, {
+    healthy: boolean;
+    container_status: string;
+    container_health: string | null;
+    tunnel_status: string;
+    tunnel_status_code: number | null;
+    probe_status: string;
+    last_probe_output: string | null;
+    error: string | null;
+  }>>({});
+  const [recreatingId, setRecreatingId] = useState<string | null>(null);
+  const [expandedProbeId, setExpandedProbeId] = useState<string | null>(null);
+
+  const loadSessions = useCallback(async () => {
+    setStatus("loading");
+    try {
+      const [sessionsData, config] = await Promise.all([
+        getUserSessions(),
+        getUserConfig(),
+      ]);
+      setSessions(sessionsData);
+      setLastSessionId(config.last_session_id ?? null);
+      setStatus("ready");
+    } catch {
+      setStatus("error");
+    }
+  }, []);
+
+  useEffect(() => {
+    void loadSessions();
+  }, [loadSessions]);
+
+  useEffect(() => {
+    const loadProjects = async () => {
+      try {
+        const data = await listProjects();
+        setProjects(data);
+      } catch {
+        // ignore
+      }
+    };
+    void loadProjects();
+  }, []);
+
+  useEffect(() => {
+    const loadToolTypes = async () => {
+      try {
+        const data = await listToolTypes();
+        setToolTypes(data);
+      } catch {
+        // ignore
+      }
+    };
+    void loadToolTypes();
+  }, []);
+
+  // Poll health every 30 seconds for active instances
+  useEffect(() => {
+    const checkHealth = async () => {
+      const activeSessions = sessions.filter(
+        (s) => ["running", "starting", "unhealthy", "probing"].includes(s.status)
+      );
+      for (const session of activeSessions) {
+        try {
+          const health = await checkInstanceHealth(
+            session.project_id,
+            session.repository_id,
+            session.id
+          );
+          setTunnelHealth((prev) => ({
+            ...prev,
+            [session.id]: health,
+          }));
+        } catch {
+          setTunnelHealth((prev) => ({
+            ...prev,
+            [session.id]: {
+              healthy: false,
+              container_status: "unknown",
+              container_health: null,
+              tunnel_status: "unreachable",
+              tunnel_status_code: null,
+              probe_status: "unknown",
+              last_probe_output: null,
+              error: "check failed",
+            },
+          }));
+        }
+      }
+    };
+
+    // Check immediately and then every 30 seconds
+    void checkHealth();
+    const interval = setInterval(() => void checkHealth(), 30000);
+    return () => clearInterval(interval);
+  }, [sessions]);
+
+  useEffect(() => {
+    if (!selectedProject) {
+      setRepositories([]);
+      return;
+    }
+    const loadRepos = async () => {
+      try {
+        const data = await listRepositories(selectedProject);
+        setRepositories(data);
+      } catch {
+        setRepositories([]);
+      }
+    };
+    void loadRepos();
+  }, [selectedProject]);
+
+  const activeSessions = useMemo(
+    () => sessions.filter((s) => ["running", "building", "pending", "starting", "probing", "unhealthy"].includes(s.status)),
+    [sessions]
+  );
+
+  const recentSessions = useMemo(
+    () => sessions.filter((s) => ["stopped", "error"].includes(s.status)).slice(0, 5),
+    [sessions]
+  );
+
+  const lastSession = useMemo(
+    () => sessions.find((s) => s.id === lastSessionId) ?? null,
+    [sessions, lastSessionId]
+  );
+
+  const handleCreate = async (e: React.FormEvent) => {
+    e.preventDefault();
+    setCreateError(null);
+
+    if (!selectedProject || !selectedRepo || !selectedToolType) {
+      setCreateError("Project, repository, and tool type are required");
+      return;
+    }
+
+    setCreateStatus("creating");
+    try {
+      const instance = await createInstance(
+        selectedProject,
+        selectedRepo,
+        selectedToolType,
+        displayName || undefined
+      );
+      
+      // Auto-start the instance
+      await startInstance(selectedProject, selectedRepo, instance.id);
+      
+      await updateUserConfig({ last_session_id: instance.id });
+      setCreateStatus("idle");
+      setSelectedProject("");
+      setSelectedRepo("");
+      setSelectedToolType("");
+      setDisplayName("");
+      await loadSessions();
+    } catch {
+      setCreateStatus("error");
+      setCreateError("Failed to create session");
+    }
+  };
+
+  const handleStop = async (sessionId: string, projectId: string, repoId: string) => {
+    try {
+      await stopInstance(projectId, repoId, sessionId);
+      setStopConfirmId(null);
+      await loadSessions();
+    } catch {
+      setStopConfirmId(null);
+    }
+  };
+
+  const handleDelete = async (sessionId: string, projectId: string, repoId: string) => {
+    try {
+      await deleteInstance(projectId, repoId, sessionId);
+      setDeleteConfirmId(null);
+      // Remove from local state immediately
+      setSessions((prev) => prev.filter((s) => s.id !== sessionId));
+    } catch {
+      setDeleteConfirmId(null);
+    }
+  };
+
+  const handleRecreateTunnel = async (session: Session) => {
+    setRecreatingId(session.id);
+    try {
+      await recreateInstanceTunnel(
+        session.project_id,
+        session.repository_id,
+        session.id
+      );
+      // Refresh sessions to get new URL
+      await loadSessions();
+    } catch {
+      // ignore
+    } finally {
+      setRecreatingId(null);
+    }
+  };
+
+  const handleOpen = (session: Session) => {
+    if (session.url) {
+      window.open(session.url, '_blank', 'noopener,noreferrer');
+    } else if (session.tool_type_interfaces?.includes("terminal")) {
+      navigate(`/instances/${session.id}/terminal`);
+    } else {
+      navigate(`/projects/${session.project_id}`);
+    }
+  };
+
+  const handleResumeLast = async () => {
+    if (!lastSession) return;
+    // Find the project and repo IDs
+    const project = projects.find((p) => p.name === lastSession.project_name);
+    if (project) {
+      navigate(`/projects/${project.id}`);
+    }
+  };
+
+  return (
+    <section className="stack sessions-page">
+      <div className="page-header">
+        <h1>Sessions</h1>
+      </div>
+
+      {status === "loading" && <p className="muted">Loading sessions...</p>}
+
+      {status === "error" && (
+        <div className="card stack">
+          <p>Failed to load sessions</p>
+          <button className="secondary-button" onClick={() => void loadSessions()} type="button">
+            <Icon name="refresh" size="sm" />
+            Retry
+          </button>
+        </div>
+      )}
+
+      {status === "ready" && (
+        <>
+          {/* Last Session */}
+          {lastSession && (
+            <div className="last-session-section">
+              <h2>Last Session</h2>
+              <div className="card last-session-card">
+                <div className="last-session-info">
+                  <h3>{lastSession.display_name}</h3>
+                  <p className="muted">
+                    {lastSession.tool_type_name} · {lastSession.project_name} · {lastSession.repository_name}
+                  </p>
+                  {lastSession.url && (
+                    <p className="session-url">
+                      <a href={lastSession.url} target="_blank" rel="noopener noreferrer">
+                        {lastSession.url}
+                      </a>
+                    </p>
+                  )}
+                  <span className={`status-badge ${lastSession.status}`}>{lastSession.status}</span>
+                </div>
+                <div className="last-session-actions">
+                  {lastSession.url ? (
+                    <a
+                      href={lastSession.url}
+                      target="_blank"
+                      rel="noopener noreferrer"
+                      className="primary-button"
+                    >
+                      <Icon name="external" size="sm" />
+                      Open
+                    </a>
+                  ) : (
+                    <button className="primary-button" onClick={handleResumeLast} type="button">
+                      <Icon name="play" size="sm" />
+                      Resume
+                    </button>
+                  )}
+                </div>
+              </div>
+            </div>
+          )}
+
+          {/* Active Sessions */}
+          <div className="active-sessions-section">
+            <h2>
+              Active Sessions
+              {activeSessions.length > 0 && (
+                <span className="badge">{activeSessions.length}</span>
+              )}
+            </h2>
+            {activeSessions.length === 0 ? (
+              <p className="muted">No active sessions</p>
+            ) : (
+              <div className="sessions-grid">
+                {activeSessions.map((session) => (
+                  <div className="card session-card" key={session.id}>
+                    <div className="session-info">
+                      <h4>{session.display_name}</h4>
+                      <p className="muted">
+                        {session.tool_type_name} · {session.project_name}
+                      </p>
+                      {session.url && (
+                        <p className="session-url">
+                          <a href={session.url} target="_blank" rel="noopener noreferrer">
+                            {session.url}
+                          </a>
+                        </p>
+                      )}
+                      <span className={`status-badge ${session.status}`}>{session.status}</span>
+                      {session.status === "starting" && (
+                        <span className="status-badge starting">starting...</span>
+                      )}
+                      {session.status === "probing" && (
+                        <span className="status-badge probing">checking...</span>
+                      )}
+                      {tunnelHealth[session.id] && tunnelHealth[session.id].tunnel_status === "unreachable" && (
+                        <span className="status-badge error">tunnel error</span>
+                      )}
+                      {tunnelHealth[session.id] && tunnelHealth[session.id].tunnel_status === "error_response" && (
+                        <span className="status-badge warning">app error ({tunnelHealth[session.id].tunnel_status_code})</span>
+                      )}
+                      {tunnelHealth[session.id]?.last_probe_output && (
+                        <div className="probe-output-section">
+                          <button
+                            className="probe-toggle"
+                            onClick={() => setExpandedProbeId(expandedProbeId === session.id ? null : session.id)}
+                            type="button"
+                          >
+                            <Icon name="info" size="sm" />
+                            {expandedProbeId === session.id ? "Hide probe output" : "Show probe output"}
+                          </button>
+                          {expandedProbeId === session.id && (
+                            <pre className="probe-output">
+                              {tunnelHealth[session.id].last_probe_output}
+                            </pre>
+                          )}
+                        </div>
+                      )}
+                    </div>
+                    <div className="session-actions">
+                      {session.url ? (
+                        <a
+                          href={session.url}
+                          target="_blank"
+                          rel="noopener noreferrer"
+                          className="secondary-button small"
+                        >
+                          <Icon name="external" size="sm" />
+                          Open
+                        </a>
+                      ) : (
+                        <button
+                          className="secondary-button small"
+                          onClick={() => handleOpen(session)}
+                          type="button"
+                        >
+                          <Icon name="external" size="sm" />
+                          Open
+                        </button>
+                      )}
+                      {tunnelHealth[session.id] && tunnelHealth[session.id].tunnel_status === "unreachable" && (
+                        <button
+                          className="secondary-button small"
+                          onClick={() => void handleRecreateTunnel(session)}
+                          type="button"
+                          disabled={recreatingId === session.id}
+                        >
+                          <Icon name="refresh" size="sm" />
+                          {recreatingId === session.id ? "Recreating..." : "Recreate Tunnel"}
+                        </button>
+                      )}
+                      {stopConfirmId === session.id ? (
+                        <div className="stop-confirm-inline">
+                          <span className="confirm-text">Stop?</span>
+                          <button
+                            className="danger-button small"
+                            onClick={() =>
+                              void handleStop(
+                                session.id,
+                                session.project_id,
+                                session.repository_id
+                              )
+                            }
+                            type="button"
+                          >
+                            Stop
+                          </button>
+                          <button
+                            className="ghost-button small"
+                            onClick={() => setStopConfirmId(null)}
+                            type="button"
+                          >
+                            Cancel
+                          </button>
+                        </div>
+                      ) : (
+                        <button
+                          className="secondary-button small"
+                          onClick={() => setStopConfirmId(session.id)}
+                          type="button"
+                        >
+                          <Icon name="stop" size="sm" />
+                          Stop
+                        </button>
+                      )}
+                      {deleteConfirmId === session.id ? (
+                        <div className="delete-confirm-inline">
+                          <button
+                            className="danger-button small"
+                            onClick={() =>
+                              void handleDelete(
+                                session.id,
+                                session.project_id,
+                                session.repository_id
+                              )
+                            }
+                            type="button"
+                          >
+                            Delete
+                          </button>
+                          <button
+                            className="ghost-button small"
+                            onClick={() => setDeleteConfirmId(null)}
+                            type="button"
+                          >
+                            Cancel
+                          </button>
+                        </div>
+                      ) : (
+                        <button
+                          className="ghost-button small danger-text"
+                          onClick={() => setDeleteConfirmId(session.id)}
+                          type="button"
+                        >
+                          <Icon name="delete" size="sm" />
+                        </button>
+                      )}
+                    </div>
+                  </div>
+                ))}
+              </div>
+            )}
+          </div>
+
+          {/* Recent Sessions */}
+          {recentSessions.length > 0 && (
+            <div className="recent-sessions-section">
+              <h2>Recent Sessions</h2>
+              <div className="recent-sessions-list">
+                {recentSessions.map((session) => (
+                  <div className="recent-session-item" key={session.id}>
+                    <div className="recent-session-info">
+                      <span className="recent-session-name">{session.display_name}</span>
+                      <span className="muted">
+                        {session.tool_type_name} · {session.project_name}
+                      </span>
+                    </div>
+                    <div className="recent-session-actions">
+                      {session.url ? (
+                        <a
+                          href={session.url}
+                          target="_blank"
+                          rel="noopener noreferrer"
+                          className="ghost-button small"
+                        >
+                          Open
+                        </a>
+                      ) : (
+                        <button
+                          className="ghost-button small"
+                          onClick={() => handleOpen(session)}
+                          type="button"
+                        >
+                          Open
+                        </button>
+                      )}
+                      {deleteConfirmId === session.id ? (
+                        <div className="delete-confirm-inline">
+                          <button
+                            className="danger-button small"
+                            onClick={() =>
+                              void handleDelete(
+                                session.id,
+                                session.project_id,
+                                session.repository_id
+                              )
+                            }
+                            type="button"
+                          >
+                            Delete
+                          </button>
+                          <button
+                            className="ghost-button small"
+                            onClick={() => setDeleteConfirmId(null)}
+                            type="button"
+                          >
+                            Cancel
+                          </button>
+                        </div>
+                      ) : (
+                        <button
+                          className="ghost-button small danger-text"
+                          onClick={() => setDeleteConfirmId(session.id)}
+                          type="button"
+                        >
+                          <Icon name="delete" size="sm" />
+                        </button>
+                      )}
+                    </div>
+                  </div>
+                ))}
+              </div>
+            </div>
+          )}
+
+          {/* Create Session */}
+          <div className="create-session-section">
+            <h2>Create New Session</h2>
+            <form onSubmit={handleCreate} className="card stack create-session-form">
+              <div className="form-row">
+                <label className="form-field">
+                  Project
+                  <select
+                    value={selectedProject}
+                    onChange={(e) => {
+                      setSelectedProject(e.target.value);
+                      setSelectedRepo("");
+                    }}
+                  >
+                    <option value="">Select project...</option>
+                    {projects.map((p) => (
+                      <option key={p.id} value={p.id}>
+                        {p.name}
+                      </option>
+                    ))}
+                  </select>
+                </label>
+
+                <label className="form-field">
+                  Repository
+                  <select
+                    value={selectedRepo}
+                    onChange={(e) => setSelectedRepo(e.target.value)}
+                    disabled={!selectedProject}
+                  >
+                    <option value="">Select repository...</option>
+                    {repositories.map((r) => (
+                      <option key={r.id} value={r.id}>
+                        {r.name}
+                      </option>
+                    ))}
+                  </select>
+                </label>
+
+                <label className="form-field">
+                  Tool Type
+                  <select
+                    value={selectedToolType}
+                    onChange={(e) => setSelectedToolType(e.target.value)}
+                  >
+                    <option value="">Select tool...</option>
+                    {toolTypes.map((t) => (
+                      <option key={t.id} value={t.id}>
+                        {t.display_name}
+                      </option>
+                    ))}
+                  </select>
+                </label>
+              </div>
+
+              <label className="form-field">
+                Display Name (optional)
+                <input
+                  type="text"
+                  value={displayName}
+                  onChange={(e) => setDisplayName(e.target.value)}
+                  placeholder="My Development Environment"
+                />
+              </label>
+
+              {createError && <p className="error-text">{createError}</p>}
+
+              <div className="form-actions">
+                <button
+                  className="primary-button"
+                  type="submit"
+                  disabled={createStatus === "creating"}
+                >
+                  {createStatus === "creating" ? (
+                    <>
+                      <Icon name="loading" size="sm" />
+                      Creating...
+                    </>
+                  ) : (
+                    <>
+                      <Icon name="add" size="sm" />
+                      Create Session
+                    </>
+                  )}
+                </button>
+              </div>
+            </form>
+          </div>
+        </>
+      )}
+    </section>
+  );
+};

apps/web/src/pages/settings.tsx

@@ -1,22 +1,40 @@
 import { useCallback, useEffect, useState } from "react";
+import { Link, Outlet, useLocation, useOutletContext } from "react-router-dom";
 
 import { getUserConfig, updateUserConfig, type UserConfig, type UserConfigUpdate } from "../api/settings";
+import { Icon } from "../components/icon";
 
 type SettingsStatus = "loading" | "ready" | "error";
 
+const TABS = [
+  { label: "General", path: "general" },
+  { label: "SSH Keys", path: "ssh-keys" },
+  { label: "Tool Types", path: "tool-types" },
+  { label: "Tool Configs", path: "tool-configs" },
+] as const;
+
 const THEME_OPTIONS = [
   { value: "system", label: "System" },
   { value: "light", label: "Light" },
   { value: "dark", label: "Dark" },
 ];
 
+type SettingsOutletContext = {
+  config: UserConfig;
+  handleChange: (key: keyof UserConfigUpdate, value: string | null) => void;
+  handleSave: () => Promise<void>;
+  saveStatus: "idle" | "saving" | "saved" | "error";
+};
+
 export const SettingsPage = () => {
+  const location = useLocation();
   const [status, setStatus] = useState<SettingsStatus>("loading");
   const [config, setConfig] = useState<UserConfig>({
     theme: "system",
     default_editor: null,
     git_user_name: null,
     git_user_email: null,
+    last_session_id: null,
   });
   const [saveStatus, setSaveStatus] = useState<"idle" | "saving" | "saved" | "error">("idle");
 
@@ -44,14 +62,19 @@ export const SettingsPage = () => {
     try {
       const update: UserConfigUpdate = {
         theme: config.theme,
-        default_editor: config.default_editor ?? undefined,
-        git_user_name: config.git_user_name ?? undefined,
-        git_user_email: config.git_user_email ?? undefined,
+        default_editor: config.default_editor,
+        git_user_name: config.git_user_name,
+        git_user_email: config.git_user_email,
       };
       const updated = await updateUserConfig(update);
       setConfig(updated);
       setSaveStatus("saved");
-      setTimeout(() => setSaveStatus("idle"), 2000);
+      if (updated.theme === "system") {
+        document.documentElement.removeAttribute("data-theme");
+      } else {
+        document.documentElement.setAttribute("data-theme", updated.theme);
+      }
+      window.setTimeout(() => setSaveStatus("idle"), 2000);
     } catch {
       setSaveStatus("error");
     }
@@ -66,77 +89,78 @@ export const SettingsPage = () => {
       <section className="stack">
         <p>Failed to load settings</p>
         <button className="secondary-button" onClick={() => void loadConfig()} type="button">
+          <Icon name="refresh" size="sm" />
           Retry
         </button>
       </section>
     );
   }
 
+  const parts = location.pathname.split("/").filter(Boolean);
+  const activePath = location.pathname.endsWith("/settings") ? "general" : (parts[parts.length - 1] ?? "general");
+
   return (
-    <section className="stack">
-      <div className="page-header">
+    <section className="stack settings-page">
+      <header className="settings-header card stack-sm">
+        <div>
+          <p className="eyebrow">Configuration</p>
           <h1>Settings</h1>
         </div>
+        <p className="muted">General preferences, SSH keys, tool types, and tool configs live here.</p>
+      </header>
 
-      <div className="card stack">
-        <h2>Appearance</h2>
-        <label className="form-field">
-          Theme
-          <select
-            value={config.theme}
-            onChange={(e) => handleChange("theme", e.target.value)}
+      <nav className="settings-tabs" aria-label="Settings sections">
+        {TABS.map((tab) => (
+          <Link
+            key={tab.path}
+            className={`settings-tab ${activePath === tab.path ? "active" : ""}`}
+            to={tab.path === "general" ? "/settings" : `/settings/${tab.path}`}
           >
-            {THEME_OPTIONS.map((opt) => (
-              <option key={opt.value} value={opt.value}>
-                {opt.label}
-              </option>
+            {tab.label}
+          </Link>
         ))}
-          </select>
-        </label>
-      </div>
+      </nav>
 
-      <div className="card stack">
-        <h2>Git Identity</h2>
-        <label className="form-field">
-          User Name
-          <input
-            type="text"
-            value={config.git_user_name ?? ""}
-            onChange={(e) => handleChange("git_user_name", e.target.value || null)}
-            placeholder="Your git commit name"
-          />
-        </label>
-        <label className="form-field">
-          User Email
-          <input
-            type="email"
-            value={config.git_user_email ?? ""}
-            onChange={(e) => handleChange("git_user_email", e.target.value || null)}
-            placeholder="your.email@example.com"
-          />
-        </label>
-      </div>
-
-      <div className="card stack">
-        <h2>Editor</h2>
-        <label className="form-field">
-          Default Editor
-          <input
-            type="text"
-            value={config.default_editor ?? ""}
-            onChange={(e) => handleChange("default_editor", e.target.value || null)}
-            placeholder="e.g., vscode, vim, cursor"
-          />
-        </label>
-      </div>
-
-      <div className="settings-actions">
-        <button className="primary-button" onClick={() => void handleSave()} type="button">
-          {saveStatus === "saving" ? "Saving..." : "Save Settings"}
-        </button>
-        {saveStatus === "saved" && <span className="success-text">Settings saved!</span>}
-        {saveStatus === "error" && <span className="error-text">Failed to save</span>}
+      <div className="settings-panel card">
+        <Outlet context={{ config, handleChange, handleSave, saveStatus }} />
       </div>
     </section>
   );
 };
+
+export const GeneralSettingsTab = () => {
+  const { config, handleChange, handleSave, saveStatus } = useOutletContext<SettingsOutletContext>();
+
+  return (
+    <div className="stack">
+      <h2>General</h2>
+      <label className="form-field">
+        Theme
+        <select value={config.theme} onChange={(e) => handleChange("theme", e.target.value)}>
+          {THEME_OPTIONS.map((opt) => (
+            <option key={opt.value} value={opt.value}>{opt.label}</option>
+          ))}
+        </select>
+      </label>
+      <label className="form-field">
+        Git user name
+        <input type="text" value={config.git_user_name ?? ""} onChange={(e) => handleChange("git_user_name", e.target.value || null)} placeholder="Your git commit name" />
+      </label>
+      <label className="form-field">
+        Git user email
+        <input type="email" value={config.git_user_email ?? ""} onChange={(e) => handleChange("git_user_email", e.target.value || null)} placeholder="your.email@example.com" />
+      </label>
+      <label className="form-field">
+        Default editor
+        <input type="text" value={config.default_editor ?? ""} onChange={(e) => handleChange("default_editor", e.target.value || null)} placeholder="e.g., vscode, vim, cursor" />
+      </label>
+      <div className="settings-actions">
+        <button className="primary-button" onClick={() => void handleSave()} type="button">
+          {saveStatus === "saving" ? <><Icon name="loading" size="sm" /> Saving...</> : <><Icon name="save" size="sm" /> Save Settings</>}
+        </button>
+        {saveStatus === "saved" && <span className="success-text">Settings saved!</span>}
+        {saveStatus === "error" && <span className="error-text">Failed to save</span>}
+      </div>
+    </div>
+  );
+};

apps/web/src/pages/ssh-keys.tsx

@@ -1,7 +1,10 @@
 import { useEffect, useState } from "react";
+import { useNavigate } from "react-router-dom";
 import { createSSHKey, deleteSSHKey, listSSHKeys, type SSHKey } from "../api/ssh_keys";
+import { Icon } from "../components/icon";
 
 export const SSHKeysPage = () => {
+  const navigate = useNavigate();
   const [keys, setKeys] = useState<SSHKey[]>([]);
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
@@ -60,7 +63,15 @@ export const SSHKeysPage = () => {
 
   return (
     <section className="stack">
+      <div className="page-header">
+        <div>
+          <p className="eyebrow">Settings</p>
           <h1>SSH Keys</h1>
+        </div>
+        <button className="secondary-button" type="button" onClick={() => navigate("/settings")}>
+          Back to settings
+        </button>
+      </div>
 
       {error && <div className="error">{error}</div>}
 
@@ -77,7 +88,17 @@ export const SSHKeysPage = () => {
           />
         </div>
         <button type="submit" className="primary-button" disabled={generating}>
-          {generating ? "Generating..." : "Generate SSH Key"}
+          {generating ? (
+            <>
+              <Icon name="loading" size="sm" />
+              Generating...
+            </>
+          ) : (
+            <>
+              <Icon name="add" size="sm" />
+              Generate SSH Key
+            </>
+          )}
         </button>
       </form>
 
@@ -93,6 +114,7 @@ export const SSHKeysPage = () => {
                   onClick={() => handleDelete(key.id)}
                   className="danger-button"
                 >
+                  <Icon name="delete" size="sm" />
                   Delete
                 </button>
               </div>
@@ -107,6 +129,7 @@ export const SSHKeysPage = () => {
                   onClick={() => copyToClipboard(key.public_key)}
                   className="secondary-button"
                 >
+                  <Icon name="copy" size="sm" />
                   Copy Full Key
                 </button>
               </div>

apps/web/src/pages/terminal.tsx

@@ -0,0 +1,38 @@
+import React from "react";
+import { useNavigate, useParams } from "react-router-dom";
+import { TerminalComponent } from "../components/terminal";
+import { Icon } from "../components/icon";
+
+export const TerminalPage: React.FC = () => {
+  const { instanceId } = useParams<{ instanceId: string }>();
+  const navigate = useNavigate();
+
+  if (!instanceId) {
+    return (
+      <section className="stack">
+        <h1>Terminal</h1>
+        <p className="muted">No instance ID provided.</p>
+      </section>
+    );
+  }
+
+  return (
+    <section className="terminal-page">
+      <div className="terminal-page-header">
+        <button
+          className="secondary-button"
+          onClick={() => navigate(-1)}
+          type="button"
+        >
+          <Icon name="arrow-left" size="sm" />
+          Back
+        </button>
+        <h1>Terminal</h1>
+      </div>
+      <TerminalComponent
+        instanceId={instanceId}
+        onClose={() => navigate(-1)}
+      />
+    </section>
+  );
+};