surfaces/.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/04-03-PLAN.md

phase	plan	type	wave	depends_on	files_modified	autonomous	requirements	must_haves
04-matrix-mvp-shared-agent-context-and-context-management-comma	03	execute	2	04-01-PLAN.md	Dockerfile docker-compose.yml .env.example	true	Dockerfile for Matrix bot docker-compose.yml with matrix-bot service .env.example updated with AGENT_BASE_URL and MATRIX_PLATFORM_BACKEND	truths artifacts key_links Dockerfile builds successfully with python:3.11-slim base lambda_agent_api installed in container despite Python version constraint PYTHONPATH=/app set so adapter/matrix/bot.py is runnable as module docker-compose.yml defines matrix-bot service with env_file: .env .env.example contains AGENT_BASE_URL and MATRIX_PLATFORM_BACKEND=real CMD runs python -m adapter.matrix.bot path provides contains Dockerfile Matrix bot container image python:3.11-slim path provides contains docker-compose.yml Service definition for matrix-bot matrix-bot path provides contains .env.example Updated env template AGENT_BASE_URL from to via pattern Dockerfile external/platform-agent_api COPY + pip install with --ignore-requires-python ignore-requires-python

Package the Matrix bot in a Docker container. Create Dockerfile using python:3.11-slim, install lambda_agent_api from the local external/ directory (bypassing the Python 3.14 version constraint), and define a docker-compose.yml for running the matrix-bot service. Update .env.example with new variables.

Purpose: Enable reproducible MVP deployment of the Matrix bot in a container alongside the separately-run platform-agent.

Output: Dockerfile, docker-compose.yml, updated .env.example.

<execution_context> @$HOME/.claude/get-shit-done/workflows/execute-plan.md @$HOME/.claude/get-shit-done/templates/summary.md </execution_context>

@.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/04-CONTEXT.md @.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/04-RESEARCH.md Task 1: Create Dockerfile and docker-compose.yml

<read_first> - .env.example (full file — adding new vars) - external/platform-agent_api/lambda_agent_api/ (ls — verify files to copy) - pyproject.toml (verify uv is the package manager used) </read_first>

Dockerfile, docker-compose.yml, .env.example

1. Check if pyproject.toml uses uv or pip. The project uses `uv sync` per CLAUDE.md. However, in the Docker container we can use pip for simplicity since uv's lockfile-based install may need the lockfile present. Use pip for the base install of surfaces-bot deps, and install lambda_agent_api separately.

Actually: the project uses uv. Use uv in Docker to be consistent:

• Install uv via pip (pip install uv)
• Run uv sync to install project deps
• Install lambda_agent_api with pip --ignore-requires-python

2. Create Dockerfile:

FROM python:3.11-slim

WORKDIR /app

# Install uv
RUN pip install --no-cache-dir uv

# Copy dependency manifests first for layer caching
COPY pyproject.toml uv.lock* ./

# Install project dependencies via uv (no project install yet, just deps)
RUN uv sync --no-install-project --frozen 2>/dev/null || uv sync --no-install-project

# Copy project source
COPY . .

# Install the project itself
RUN uv sync --frozen 2>/dev/null || uv sync

# Install lambda_agent_api, bypassing Python version constraint
RUN pip install --no-cache-dir --ignore-requires-python /app/external/platform-agent_api

ENV PYTHONPATH=/app
ENV PYTHONUNBUFFERED=1

CMD ["python", "-m", "adapter.matrix.bot"]

3. Create docker-compose.yml:

services:
  matrix-bot:
    build: .
    env_file: .env
    restart: unless-stopped
    # platform-agent runs separately — not included in this compose file

4. Read current .env.example, then append new variables. Current file likely has MATRIX_* vars. Add:

   • AGENT_WS_URL=ws://127.0.0.1:8000/agent_ws/
   • AGENT_BASE_URL=http://127.0.0.1:8000
   • MATRIX_PLATFORM_BACKEND=real

   Read .env.example first to see what's there, then write the full updated file.

- `grep "python:3.11-slim" Dockerfile` returns a match - `grep "ignore-requires-python" Dockerfile` returns a match (lambda_agent_api install) - `grep "PYTHONPATH=/app" Dockerfile` returns a match - `grep "adapter.matrix.bot" Dockerfile` returns a match (CMD) - `grep "matrix-bot" docker-compose.yml` returns a match - `grep "env_file" docker-compose.yml` returns a match - `grep "AGENT_BASE_URL" .env.example` returns a match - `grep "MATRIX_PLATFORM_BACKEND" .env.example` returns a match - Dockerfile exists with python:3.11-slim, uv install, lambda_agent_api pip install --ignore-requires-python, PYTHONPATH=/app, CMD python -m adapter.matrix.bot - docker-compose.yml exists with matrix-bot service, env_file: .env, restart: unless-stopped - .env.example contains AGENT_WS_URL, AGENT_BASE_URL, MATRIX_PLATFORM_BACKEND=real grep "python:3.11-slim" /Users/a/MAI/sem2/lambda/surfaces-bot/Dockerfile && grep "ignore-requires-python" /Users/a/MAI/sem2/lambda/surfaces-bot/Dockerfile && grep "AGENT_BASE_URL" /Users/a/MAI/sem2/lambda/surfaces-bot/.env.example && echo "All checks passed"

<threat_model>

Trust Boundaries

Boundary	Description
container → host env	.env file mounts secrets into container
container → platform-agent	Network call to AGENT_WS_URL / AGENT_BASE_URL

STRIDE Threat Register

Threat ID	Category	Component	Disposition	Mitigation Plan
T-04-03-01	Information Disclosure	.env file with secrets mounted in container	mitigate	.env in .gitignore; .env.example committed with placeholder values only, never real secrets
T-04-03-02	Tampering	lambda_agent_api installed from local path via --ignore-requires-python	accept	Local package under version control; no external supply chain risk
T-04-03-03	Denial of Service	restart: unless-stopped could loop on crash	accept	Expected behavior; operator can docker compose stop
</threat_model>

```bash # Verify files exist and contain expected content grep "python:3.11-slim" /Users/a/MAI/sem2/lambda/surfaces-bot/Dockerfile grep "ignore-requires-python" /Users/a/MAI/sem2/lambda/surfaces-bot/Dockerfile grep "AGENT_BASE_URL" /Users/a/MAI/sem2/lambda/surfaces-bot/.env.example grep "matrix-bot" /Users/a/MAI/sem2/lambda/surfaces-bot/docker-compose.yml ```

<success_criteria>

• Dockerfile, docker-compose.yml, .env.example all exist in project root
• Dockerfile builds without errors when platform-agent_api dir is present (docker build . exits 0)
• .env.example contains AGENT_BASE_URL, AGENT_WS_URL, MATRIX_PLATFORM_BACKEND
• docker-compose.yml service named matrix-bot uses env_file: .env </success_criteria>

After completion, create `.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/04-03-SUMMARY.md`