cooperage 0.1.0__tar.gz

cooperage-0.1.0/.env.example

@@ -0,0 +1,58 @@
+# Copy to .env and fill in values as needed.
+# All variables use the COOPERAGE_ prefix.
+
+# ── Orchestrator ─────────────────────────────────────────────────────────────
+# "docker" (default) or "kubernetes"
+COOPERAGE_ORCHESTRATOR=docker
+
+# ── Docker ───────────────────────────────────────────────────────────────────
+COOPERAGE_DOCKER_SOCKET=unix:///var/run/docker.sock
+COOPERAGE_CONTAINER_PORT_RANGE_START=9000
+COOPERAGE_CONTAINER_PORT_RANGE_END=9999
+
+# ── Kubernetes ───────────────────────────────────────────────────────────────
+COOPERAGE_K8S_NAMESPACE=cooperage
+COOPERAGE_K8S_NODE_PORT_RANGE_START=30000
+COOPERAGE_K8S_NODE_PORT_RANGE_END=32767
+COOPERAGE_K8S_HOST_PATH_PREFIX=/run/cooperage
+
+# ── Sessions ─────────────────────────────────────────────────────────────────
+# Session auto-expiry in seconds (default: 30 min)
+COOPERAGE_SESSION_TTL_SECONDS=1800
+# How often to scan for expired sessions (seconds)
+COOPERAGE_SESSION_CLEANUP_INTERVAL=60
+# Stop idle containers after N seconds of no tool calls
+COOPERAGE_CONTAINER_IDLE_TIMEOUT=600
+# Reset session TTL on each tool call
+COOPERAGE_SESSION_EXTEND_ON_ACTIVITY=true
+# How long to wait for a container to become ready (seconds)
+COOPERAGE_CONTAINER_STARTUP_TIMEOUT=120
+
+# ── Persistence ──────────────────────────────────────────────────────────────
+# Where to store registry and session state (defaults to ~/.cooperage/)
+# COOPERAGE_REGISTRY_PATH=/data/cooperage/registry.json
+# COOPERAGE_SESSIONS_PATH=/data/cooperage/sessions.json
+
+# ── Gateway ──────────────────────────────────────────────────────────────────
+COOPERAGE_GATEWAY_HOST=0.0.0.0
+COOPERAGE_GATEWAY_PORT=8080
+# URL shown to users after session creation (e.g. your hosted UI)
+# COOPERAGE_UI_URL=http://localhost:8501
+
+# ── Resource limits ──────────────────────────────────────────────────────────
+COOPERAGE_DEFAULT_CPU_LIMIT=1.0
+COOPERAGE_DEFAULT_MEMORY_LIMIT=512m
+
+# ── Network isolation ────────────────────────────────────────────────────────
+COOPERAGE_NETWORK_ISOLATION=true
+
+# ── Image registry ───────────────────────────────────────────────────────────
+# Prepend a registry mirror to all image pulls (air-gapped / internal mirror)
+# COOPERAGE_IMAGE_REGISTRY_PREFIX=registry.corp.internal/
+# Path to registry credentials JSON (for private registries)
+# COOPERAGE_REGISTRY_AUTH_PATH=/etc/cooperage/registry-auth.json
+
+# ── Enterprise auth & audit ──────────────────────────────────────────────────
+# Authentication, OIDC/SSO, per-tenant RBAC, session quotas, and audit logging
+# are provided by the cooperage-enterprise package. See:
+# https://github.com/cooperage-io/cooperage-enterprise

cooperage-0.1.0/.github/workflows/publish-images.yml

@@ -0,0 +1,70 @@
+name: Publish container images
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+
+env:
+  REGISTRY: ghcr.io
+  ORG: cooperage-io
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    strategy:
+      matrix:
+        include:
+          - image: cooperage
+            context: .
+            dockerfile: Dockerfile
+          - image: cooperage-workspace
+            context: ./servers/workspace
+            dockerfile: ./servers/workspace/Dockerfile
+          - image: cooperage-compute
+            context: ./servers/compute
+            dockerfile: ./servers/compute/Dockerfile
+          - image: cooperage-ui
+            context: .
+            dockerfile: Dockerfile.ui
+          - image: cooperage-synthetic-image-generator
+            context: ./example-servers/synthetic-image-generator
+            dockerfile: ./example-servers/synthetic-image-generator/Dockerfile
+          - image: cooperage-image-analyzer
+            context: ./example-servers/image-analyzer
+            dockerfile: ./example-servers/image-analyzer/Dockerfile
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: docker/metadata-action@v5
+        id: meta
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.ORG }}/${{ matrix.image }}
+          tags: |
+            type=raw,value=latest,enable={{is_default_branch}}
+            type=sha,prefix=
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+
+      - uses: docker/setup-buildx-action@v3
+
+      - uses: docker/build-push-action@v6
+        with:
+          context: ${{ matrix.context }}
+          file: ${{ matrix.dockerfile }}
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

cooperage-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,29 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv sync --dev
+      - run: uv run ruff check .
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - uses: astral-sh/setup-uv@v4
+
+      - run: uv sync --dev
+      - run: uv run pytest tests/ -q --ignore=tests/test_cloud_integration.py

cooperage-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+.env
+*.egg-info/
+dist/
+build/
+.DS_Store
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+*.log
+git_logs.txt
+.claude/settings.local.json
+donot-commit/
+cooperage-enterprise/
+.vscode/

cooperage-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,89 @@
+# Contributing to Cooperage
+
+## Setup
+
+```bash
+git clone https://github.com/cooperage-io/cooperage
+cd cooperage
+uv sync
+```
+
+## Running tests
+
+```bash
+uv run pytest
+```
+
+All tests are mocked — no Docker daemon or Kubernetes cluster required.
+
+## Linting
+
+```bash
+uv run ruff check cooperage/
+uv run ruff check --fix cooperage/  # auto-fix
+```
+
+## Project structure
+
+```
+cooperage/          # core package
+  cli/              # cooperage CLI (typer)
+  core/             # models, config
+  gateway/          # MCP gateway server
+  orchestrator/     # docker.py, kubernetes.py
+  registry/         # server registration
+  session/          # session + container lifecycle
+servers/
+  workspace/        # built-in workspace server (auto-registered by gateway)
+example-servers/
+  image-analyzer/            # example: analyze images with numpy/PIL
+  synthetic-image-generator/ # example: generate synthetic satellite imagery
+tests/
+```
+
+## Adding an example server
+
+1. Create `example-servers/<name>/server.py` using FastMCP:
+    ```python
+    from mcp.server.fastmcp import FastMCP
+    mcp = FastMCP("my-server", json_response=True, stateless_http=True)
+
+    @mcp.tool()
+    def my_tool(arg: str) -> str:
+        """Tool description."""
+        ...
+
+    if __name__ == "__main__":
+        import os, uvicorn
+        uvicorn.run(mcp.streamable_http_app(), host="0.0.0.0", port=int(os.environ.get("PORT", "8000")))
+    ```
+2. Add a `Dockerfile` and `requirements.txt`
+3. Build: `docker build -t my-server:latest example-servers/<name>`
+4. Register: `cooperage register --name <name> --image my-server:latest`
+
+## Versioning
+
+Cooperage follows [Semantic Versioning](https://semver.org/). The version appears in two places that must stay in sync:
+
+- `pyproject.toml` → `project.version`
+- `chart/Chart.yaml` → `version` and `appVersion`
+
+### Cutting a release
+
+1. Run the bump script from main:
+   ```bash
+   ./scripts/bump-version.sh 0.2.0
+   ```
+   This updates both files, commits, and tags in one step.
+2. Push:
+   ```bash
+   git push origin main --tags
+   ```
+
+Tags trigger CI to publish versioned images to `ghcr.io/cooperage-io/` (e.g. `cooperage:0.2.0` alongside `cooperage:latest`).
+
+## Submitting changes
+
+- Keep PRs focused — one thing at a time
+- Tests required for gateway or orchestrator changes
+- Run ruff before pushing

cooperage-0.1.0/Dockerfile

@@ -0,0 +1,13 @@
+FROM python:3.11-slim
+
+# Install uv
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+WORKDIR /app
+
+COPY pyproject.toml .
+COPY cooperage/ cooperage/
+
+RUN uv pip install --system --no-cache .
+
+CMD ["cooperage", "start", "--sse"]

cooperage-0.1.0/Dockerfile.ui

@@ -0,0 +1,15 @@
+FROM python:3.11-slim
+
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+WORKDIR /app
+
+RUN uv pip install --system --no-cache streamlit httpx
+
+COPY ui/app.py app.py
+COPY assets/logo.png logo.png
+COPY assets/favicon.png favicon.png
+
+EXPOSE 8501
+
+CMD ["streamlit", "run", "app.py", "--server.address=0.0.0.0", "--server.port=8501", "--browser.gatherUsageStats=false"]

cooperage-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Evan Lavizadeh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cooperage-0.1.0/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.4
+Name: cooperage
+Version: 0.1.0
+Summary: Ephemeral container orchestration for MCP servers
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: anyio>=4.0.0
+Requires-Dist: docker>=7.0.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: httpx-sse>=0.4.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: kubernetes>=28.0.0
+Requires-Dist: mcp[cli]>=1.0.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.12.0
+Requires-Dist: uvicorn[standard]>=0.30.0

cooperage-0.1.0/README.md

@@ -0,0 +1,231 @@
+<p align="center">
+  <img src="assets/logo.png" alt="Cooperage" width="420">
+</p>
+
+---
+
+MCP makes it easy to give LLMs tools. Cooperage makes those tools *scalable* — each tool call runs in an isolated container with dedicated compute and a shared workspace volume. No infra to manage. Just register a Docker image and let your LLM orchestrate it.
+
+## Why this exists
+
+Writing an MCP server is easy. Deploying it somewhere an LLM can actually *use* it — for stateful runs, large datasets, multi-step pipelines — is not. Cooperage is the missing layer between "I have tools" and "my LLM can run them at scale on my own infrastructure."
+
+The key thing that makes Cooperage different: **multiple containers per session, one shared `/workspace` volume.** A generator writes a file, an analyzer reads it, a report writer summarizes it — all orchestrated by the LLM, all passing data through the same volume. No other platform does this.
+
+## Architecture
+
+```
+LLM (Claude Desktop / API)
+       │  MCP (stdio or HTTP)
+       ▼
+┌─────────────────────────┐
+│    Cooperage Gateway    │  ← single MCP server the LLM talks to
+└────────────┬────────────┘
+             │  HTTP JSON-RPC
+     ┌───────┴───────┐
+     ▼               ▼
+[Container A]   [Container B]     ephemeral containers,
+ your MCP server  your MCP server   spun up per session
+     └───────┬───────┘
+      shared /workspace volume    data persists across calls
+```
+
+## Quick start
+
+**Prerequisites:** Python 3.11+, [uv](https://docs.astral.sh/uv/getting-started/installation/), Docker Desktop running.
+
+```bash
+# Install
+git clone https://github.com/cooperage-io/cooperage.git && cd cooperage
+uv sync
+
+# Build the example server
+docker buildx build --load -t cooperage-image-analyzer:latest example-servers/image-analyzer/
+
+# Register it
+uv run cooperage register \
+  --name image-analyzer \
+  --image cooperage-image-analyzer:latest \
+  --description "Analyze images and data in /workspace using numpy/PIL"
+```
+
+### Connect to Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "cooperage": {
+      "command": "/Users/YOUR_USERNAME/.local/bin/uv",
+      "args": ["--directory", "/path/to/cooperage", "run", "--no-active", "cooperage", "start"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. You should see the hammer icon — Cooperage is connected.
+
+### HTTP mode (for programmatic access)
+
+```bash
+uv run cooperage start --sse
+```
+
+This starts the gateway on `http://localhost:8080/mcp` as a Streamable HTTP MCP server.
+
+## What the LLM sees
+
+These are the tools exposed to the LLM via MCP:
+
+| Tool | What it does |
+|------|-------------|
+| `cooperage_list_servers` | List available servers and whether their images are cached. |
+| `cooperage_pull_server` | Pre-pull a server image to avoid cold-start latency. |
+| `cooperage_create_session` | Create a workspace session. Returns a `session_id`. |
+| `cooperage_list_tools` | List tools on a server. Starts the container if needed. |
+| `cooperage_call_tool` | Call a tool on a server. Starts the container if needed. |
+| `cooperage_workspace_read` | Read a file from `/workspace`. Handles binary + base64. |
+| `cooperage_workspace_write` | Write a file to `/workspace`. |
+| `cooperage_workspace_list` | List files in `/workspace`. |
+| `cooperage_run_script` | Run a Python script in the compute container. |
+| `cooperage_run_bash` | Run a bash script in the compute container. |
+| `cooperage_end_session` | Tear down containers and delete the workspace volume. |
+
+The gateway also exposes [MCP Resources](https://modelcontextprotocol.io/docs/concepts/resources) for reading registry and session state programmatically.
+
+## Multi-container pipelines
+
+This is the core use case. Containers in the same session share `/workspace`:
+
+```
+cooperage_call_tool(session, "scene-generator", "generate", {type: "urban"})
+  → container A starts, writes /workspace/scene.png
+
+cooperage_call_tool(session, "image-analyzer", "analyze", {path: "scene.png"})
+  → container B starts, reads /workspace/scene.png
+
+cooperage_workspace_read(session, "analysis.json")
+  → LLM reads the result directly
+```
+
+Two containers. One session. One shared volume. Your proprietary tools stay in your Docker images, on your infrastructure.
+
+## Writing your own server
+
+Package any MCP server as a Docker image:
+
+1. Expose MCP on port `8000` (configurable at registration)
+2. Use `FastMCP` with `json_response=True, stateless_http=True`
+3. Read/write `/workspace` for cross-container data sharing
+
+See the full guide: **[Writing Servers for Cooperage](docs/writing-servers.md)**
+
+For working examples, see [example-servers/image-analyzer/](example-servers/image-analyzer/) and [example-servers/synthetic-image-generator/](example-servers/synthetic-image-generator/).
+
+```bash
+uv run cooperage register \
+  --name my-server \
+  --image my-org/my-server:latest \
+  --description "Does the thing" \
+  --repo-url https://github.com/my-org/my-server  # optional — lets the LLM clone and debug
+```
+
+## Kubernetes backend
+
+Cooperage has a drop-in Kubernetes backend. Containers run as Pods with NodePort Services; the shared workspace uses `hostPath` volumes (or a ReadWriteMany PVC on multi-node clusters).
+
+```bash
+# Bootstrap the namespace
+COOPERAGE_ORCHESTRATOR=kubernetes uv run cooperage init-k8s
+
+# Start the gateway
+COOPERAGE_ORCHESTRATOR=kubernetes uv run cooperage start
+```
+
+The tools and LLM config are identical — only the backend changes.
+
+## Web UI
+
+Cooperage ships with a Streamlit-based dashboard for monitoring sessions, viewing container status, and browsing workspace files.
+
+```bash
+uv run cooperage ui
+```
+
+Supports file preview (images, HTML, CSV, PDF) and file upload.
+
+## Enterprise
+
+For multi-tenant deployments with authentication (API keys, JWT, OIDC/SSO), per-tenant RBAC, session quotas, and audit logging, see [cooperage-enterprise](https://github.com/cooperage-io/cooperage-enterprise).
+
+**Other features included in the open-source core:**
+- Per-container CPU and memory limits (default: 1 CPU, 512 MB)
+- Per-session network isolation (Docker bridge networks / K8s NetworkPolicy)
+- Private image registry authentication
+- Container idle timeout with automatic cleanup
+- Session TTL extension on activity
+
+## Configuration
+
+All settings use the `COOPERAGE_` prefix and can go in a `.env` file. See [`.env.example`](.env.example).
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `COOPERAGE_ORCHESTRATOR` | `docker` | `docker` or `kubernetes` |
+| `COOPERAGE_SESSION_TTL_SECONDS` | `1800` | Session auto-expiry |
+| `COOPERAGE_CONTAINER_IDLE_TIMEOUT` | `600` | Stop idle containers after N seconds |
+| `COOPERAGE_CONTAINER_STARTUP_TIMEOUT` | `120` | Seconds to wait for container readiness |
+| `COOPERAGE_DEFAULT_CPU_LIMIT` | `1.0` | CPU limit per container |
+| `COOPERAGE_DEFAULT_MEMORY_LIMIT` | `512m` | Memory limit per container |
+| `COOPERAGE_NETWORK_ISOLATION` | `true` | Per-session network isolation |
+| `COOPERAGE_UI_URL` | — | UI base URL (shown to users after session creation) |
+| `COOPERAGE_K8S_NAMESPACE` | `cooperage` | Kubernetes namespace |
+
+## CLI
+
+```
+cooperage register      Register a Docker image as an MCP server
+cooperage deregister    Remove a server from the registry
+cooperage list-servers  List registered servers
+cooperage sessions      List active sessions
+cooperage start         Start the gateway (stdio default, --sse for HTTP)
+cooperage init-k8s      Bootstrap the Cooperage K8s namespace
+cooperage ui            Launch the web dashboard
+```
+
+## Comparison
+
+| | Containers per session | Shared workspace | Infrastructure | Image source |
+|-|------------------------|-----------------|----------------|--------------|
+| **Cooperage** | Multiple (one per server) | Shared `/workspace` volume | Docker or Kubernetes | Any registry |
+| **Manus** | Single VM | `/home/ubuntu` in one sandbox | Manus cloud only | Pre-installed runtimes |
+| **Docker MCP Toolkit** | Multiple | Each container isolated | Docker Desktop only | Docker catalog |
+| **AWS Bedrock AgentCore** | One (tools colocated) | Partial — 1 GB, preview | AWS only | ECR |
+| **Google ADK + Vertex** | No container orchestration | Memory state only | GCP only | — |
+| **Azure AI Foundry** | No container orchestration | Thread state only | Azure only | — |
+
+### Cooperage vs Manus
+
+Manus gives every agent a single pre-built Ubuntu VM with Python, Node.js, and Chromium. MCP servers are external API bridges — the agent calls out to them via `manus-mcp-cli`. It's a managed, general-purpose sandbox that works well for everyday tasks with zero setup.
+
+Cooperage takes a different approach: there is no pre-built VM. The LLM dynamically spins up purpose-built containers, each running its own MCP server, all sharing a `/workspace` volume. MCP isn't a bridge to external services — it's the native interface between the LLM and the compute.
+
+**Choose Manus** if you want a turnkey managed environment and don't need to control the infrastructure.
+
+**Choose Cooperage** if you need:
+- **Self-hosted / on-prem deployment** — your cluster, your network, your data
+- **Custom runtimes** — CUDA, GDAL, proprietary SDKs, anything you can put in a Docker image
+- **Multi-tool pipelines** — containers with different dependencies composing through `/workspace`
+- **Enterprise auth and isolation** — OIDC, JWT, per-tenant RBAC, network policies, resource limits
+
+
+## Tests
+
+```bash
+uv run pytest -v
+```
+
+## License
+
+[MIT](LICENSE)

cooperage-0.1.0/ROADMAP.md

@@ -0,0 +1,77 @@
+# Cooperage Roadmap
+
+## Done
+
+### Core
+- [x] MCP gateway with core tools — `list_servers`, `create_session`, `end_session`, `list_sessions`, `call_tool`, `list_tools`, `pull_server`
+- [x] Docker orchestrator — ephemeral containers, shared `/workspace` volume per session, TTL + idle cleanup
+- [x] Kubernetes orchestrator — drop-in backend, Pods + NodePort Services + hostPath workspace, `cooperage init-k8s`, pod affinity for multi-node
+- [x] Built-in workspace server — `workspace_write/read/list/delete`, auto-registered, pre-warmed on session create
+- [x] Built-in compute server — `run_script` (Python) and `run_bash`, numpy/pandas/scipy/matplotlib/sklearn pre-installed, `uv` for live package installs
+- [x] File-based session persistence — stdio and SSE gateway share state via configurable path
+- [x] Container idle timeout + session activity TTL extension
+- [x] Network isolation — per-session bridge networks
+- [x] Resource limits — CPU/memory configurable at registration and via config
+- [x] `repo_url` on `ServerDef` — LLM can inspect server source when debugging
+
+### Auth (extracted to [cooperage-enterprise](https://github.com/cooperage-io/cooperage-enterprise))
+- [x] API key auth
+- [x] HS256 JWT auth
+- [x] OIDC / RS256 JWT auth (Azure AD, Okta, Auth0)
+- [x] Per-tenant session isolation and RBAC (`allowed_servers`, `max_sessions`)
+- [x] Audit logging (JSON-lines event log)
+- [x] Plugin interface — open core ships with `AuthProvider` and `AuditSink` protocols
+
+### Deployment
+- [x] DigitalOcean droplet — gateway + UI running in production at `137.184.119.104`
+- [x] All images published to `ghcr.io/cooperage-io/` via GitHub Actions CI
+- [x] Hosted Streamlit UI — live session/container/workspace viewer at port 8501
+- [x] `cooperage start --proxy <url>` — Claude Desktop (stdio) → remote cloud gateway bridge
+- [x] `COOPERAGE_UI_URL` — gateway returns session-scoped UI link in `create_session` response
+
+### Developer Experience
+- [x] `cooperage ui` — local Streamlit viewer with session selector, container panel, file preview, upload
+- [x] Image preview — binary files base64-encoded, rendered in browser
+- [x] `simulator` + `analysis` example servers
+- [x] 161 unit tests (mocked) + cloud integration test suite against live droplet
+- [x] MIT license, cooperage-io GitHub org
+- [x] Helm chart — gateway Deployment + ServiceAccount + Role + ConfigMap + Ingress + UI sidecar
+- [x] `/health` endpoint — K8s liveness/readiness probes
+- [x] Persistent gateway state — PVC for sessions.json + registry.json
+- [x] Image registry prefix — `COOPERAGE_IMAGE_REGISTRY_PREFIX` for air-gapped clusters
+- [x] CI — GitHub Actions for tests + image publishing
+
+---
+
+## Up Next
+
+- **GPU support for K8s workloads** — allow MCP tool servers to request GPU resources on enterprise Kubernetes clusters.
+  - Extend `ResourceLimits` model with `gpu: int | None` and `gpu_type: str | None` (default `nvidia.com/gpu`) fields.
+  - Wire GPU limits into the Pod spec in `KubernetesOrchestrator.start_container` as extended resource requests/limits (e.g. `nvidia.com/gpu: "1"`).
+  - Add configurable `tolerations` and `nodeSelector` to `ServerDef` so pods land on tainted GPU nodes.
+  - Add `default_gpu_tolerations` to `Settings` / Helm `values.yaml` for cluster-wide defaults.
+  - GPU-enabled tool server images use `nvidia/cuda` base images with CUDA libraries pre-installed; Cooperage handles scheduling.
+  - Docker orchestrator: pass `--gpus` flag via `device_requests` in the Docker SDK for local dev parity.
+  - Example server: `gpu-compute` — CUDA-aware compute server with PyTorch/JAX pre-installed, registered with `"resources": {"gpu": 1}`.
+  - Enterprise considerations: quota enforcement per tenant (max GPUs), audit log entries for GPU allocation, idle timeout tuning for expensive GPU pods.
+
+---
+
+## Backlog
+
+- **Fly.io / Railway backend** — simpler cloud alternative to K8s or bare Docker VM
+- **Dynamic resource sizing** — today resource limits are static (global defaults or per-server overrides at registration). Add support for: resource usage telemetry (CPU/memory per container, exposed as a gateway tool or resource), right-sizing recommendations based on historical usage, and optional Kubernetes VPA (Vertical Pod Autoscaler) integration for containers that consistently over- or under-request.
+- **Workspace storage limits** — workspace volume is currently unbounded (hostPath on K8s, Docker volume locally). Add configurable per-session storage quotas and surface usage in the UI and `cooperage_list_sessions` output.
+- **`cooperage deploy` CLI** — thin wrapper to provision cloud infra (droplet or K8s) and deploy the stack
+- **K8s: RWX PVC workspace** — optional alternative to hostPath + pod affinity for clusters with RWX StorageClass
+- **K8s: Ingress support** — replace NodePort with Ingress/ClusterIP for production on-prem routing
+- **Session sharing** — read-only `session_id` tokens so a user can watch a session without write access
+- **Webhook / event stream** — push session/container lifecycle events to an external URL
+- **Server search / lazy listing** — `cooperage_search_servers` tool that accepts a query and returns matching servers by name/description, so large registries don't flood the context window. `cooperage_list_servers` would return names only (no descriptions) by default, with descriptions opt-in via a flag.
+- **Configurable output paths in example servers** — simulator should accept an `output_path` parameter instead of always overwriting `scene.png`. Prevents the copy-after-generate footgun in multi-step pipelines.
+- **Structured error handling** — tools should return structured error responses (error code, message, partial results) instead of null/silent failures. Critical for enterprise use where tools may run for minutes before failing.
+- **Provenance / artifact lineage** — extend audit log to record which tool wrote which workspace file, enabling full artifact traceability across multi-container pipelines.
+- **Multi-agent demo** — orchestrator agent creates a session and passes `session_id` to parallel subagents, each calling a different server. Validates concurrent tool calls. Target framework: Claude Agent SDK.
+- **`cooperage.io` domain + public landing page** — set up domain, simple landing page with live demo link and install instructions.
+- **Audit log rotation** — cap audit log file size and keep N compressed backups (Python `RotatingFileHandler` or logrotate config). Currently grows unbounded.
+- **Interactive terminal in UI** — web-based terminal (xterm.js) in the Streamlit dashboard that connects to a session's compute container. Enables users to run bash interactively without CLI access to the host. Requires a websocket endpoint on the gateway. `cooperage exec` CLI command as a simpler alternative for local Docker deployments.

cooperage-0.1.0/chart/Chart.yaml

@@ -0,0 +1,6 @@
+apiVersion: v2
+name: cooperage
+description: MCP gateway that orchestrates ephemeral container-based tool servers
+type: application
+version: 0.1.0
+appVersion: "0.1.0"