uv-venv-manager

Standalone environment provisioning service built on uv. Exposes both a REST API (FastAPI) and a gRPC interface for creating, managing, and cleaning up Python virtual environments.

---

Architecture

uv-venv-manager is a pure environment provisioning service. It does not depend on Ray or any execution engine. The WTB SDK orchestrates both Ray (for distributed execution) and uv-venv-manager (for environment provisioning) -- the two services never talk to each other directly.

                          +-----------------------+
                          |       WTB SDK         |
                          |  (orchestrator)       |
                          +---+---------------+---+
                              |               |
                  gRPC :50051 |               | Ray API
                              v               v
                  +-----------------+   +------------+
                  | uv-venv-manager |   | Ray Cluster|
                  |  (this service) |   +------+-----+
                  +--------+--------+          |
                           |           py_executable
                           v                   |
                  +--------+--------+          |
                  |  Shared Storage  |<--------+
                  |  (NAS / local)   |
                  +-----------------+

uv-venv-manager provisions .venv paths. WTB tells Ray to use them.

---

Quick Start

Option A: Docker (recommended)

# Build
cd uv_venv_manager
docker build -t uv-venv-manager .

# Run
docker run -d \
  -p 10900:10900 \
  -p 50051:50051 \
  -v ./data:/data \
  --name uv-venv-manager \
  uv-venv-manager

Or with docker compose:

docker compose up -d

Option B: pip install

pip install uv-venv-manager
# or from source:
pip install -e ".[all]"

# Start the server
uv-venv-server

The server starts on port 10900 (REST) with a gRPC sidecar on port 50051.

---

Configuration

All settings are read from environment variables (or a .env file).

Variable	Default	Description
DATA_ROOT	./data	Base directory for all persistent data
ENVS_BASE_PATH	$DATA_ROOT/envs	Where virtual environments are created
UV_CACHE_DIR	$DATA_ROOT/uv_cache	uv package cache (must be sibling of ENVS_BASE_PATH for hardlinks)
DEFAULT_PYTHON	3.11	Python version for new environments
PORT	10900	REST API listen port
GRPC_PORT	50051	gRPC listen port
DATABASE_URL	sqlite:///data/env_audit.db	Audit database (SQLite default, PostgreSQL supported)
EXECUTION_TIMEOUT	30	UV command timeout in seconds
CLEANUP_IDLE_HOURS	72	Auto-cleanup threshold for idle environments

---

WTB Integration

WTB connects to uv-venv-manager through its GrpcEnvironmentProvider. No extra setup is needed on the uv-venv-manager side.

# Run the install checker with venv service validation
python install_checker.py --grpc-url localhost:50051

In code:

from wtb.infrastructure.environment.providers import GrpcEnvironmentProvider

provider = GrpcEnvironmentProvider(grpc_address="localhost:50051")
env = provider.create_environment("variant-1", {
    "workflow_id": "ml_pipeline",
    "node_id": "rag_node",
    "packages": ["langchain", "chromadb"],
})
# env contains env_path, python_path for Ray to use via WTB

---

REST API

Base URL: http://localhost:10900

Method	Endpoint	Description
POST	/envs	Create a new environment
GET	/envs/{workflow_id}/{node_id}	Get environment info
DELETE	/envs/{workflow_id}/{node_id}	Delete an environment
POST	/envs/{workflow_id}/{node_id}/deps	Add packages
DELETE	/envs/{workflow_id}/{node_id}/deps	Remove packages
POST	/envs/{workflow_id}/{node_id}/sync	Sync from lock file
POST	/envs/{workflow_id}/{node_id}/export	Export environment
POST	/cleanup	Clean up stale environments

Interactive docs available at http://localhost:10900/docs (Swagger UI).

---

gRPC API

Port: 50051 (configurable via GRPC_PORT)

The gRPC service mirrors the REST API. Proto definition is at uv_venv_manager/protos/env_manager.proto. Enable reflection for debugging with GRPC_REFLECTION=true.

---

Storage Layout

$DATA_ROOT/
  envs/                          # ENVS_BASE_PATH
    workflow123_node123/         # One UV project per environment
      .venv/                    # Virtual environment
        bin/python              # py_executable target
      pyproject.toml            # Dependency declaration
      uv.lock                   # Byte-level version lock
      metadata.json             # Environment metadata
  uv_cache/                      # UV_CACHE_DIR (shared cache)
    wheels/                     # Hardlinked into .venv/lib/
    archives/
  env_audit.db                   # SQLite audit log (default)

UV_CACHE_DIR and ENVS_BASE_PATH must share the same parent filesystem for uv's hardlink deduplication to work.

---

Development

cd uv_venv_manager
uv sync
uv run pytest
uv run ruff check .