feat(satellite): add runtime validation for Node.js and Python dependencies

Author: Lasim

services/satellite/.env.example

@@ -125,3 +125,10 @@ NSJAIL_TMPFS_SIZE=100M
 # Set to 0 to disable idle timeout (processes never sleep)
 # Default: 180 seconds (3 minutes)
 MCP_PROCESS_IDLE_TIMEOUT_SECONDS=180
+
+# Runtime Validation (optional)
+# Set to 'true' to skip system runtime checks at startup (Node.js, Python)
+# By default, satellite validates that required runtimes are installed before starting
+# Useful for CI/CD pipelines or Docker builds where runtimes are guaranteed
+# Default: false (validates Node.js and Python 3 availability)
+DEPLOYSTACK_SKIP_RUNTIME_CHECKS=false

services/satellite/Dockerfile

@@ -6,12 +6,24 @@ FROM node:24-bookworm-slim
 RUN useradd -m -d /opt/deploystack -s /bin/bash deploystack
 
 # Install essential runtime dependencies including gosu for privilege dropping
+# Python 3 and UV are required for Python-based MCP servers
 RUN apt-get update && \
     apt-get install -y --no-install-recommends \
     ca-certificates \
     gosu \
+    python3 \
+    python3-pip \
+    python3-venv \
     && rm -rf /var/lib/apt/lists/*
 
+# Install UV (Python package manager for MCP servers)
+# Using pip installation for reliable system-wide access
+# This installs both 'uv' and 'uvx' commands to /usr/local/bin
+RUN pip3 install --break-system-packages uv && \
+    which uv && \
+    which uvx && \
+    uv --version
+
 # Create mcp-cache base directory with proper ownership
 RUN mkdir -p /opt/deploystack/mcp-cache && \
     chown -R deploystack:deploystack /opt/deploystack

services/satellite/README.md

@@ -51,6 +51,37 @@ npm start
 
 The satellite service uses environment variables for configuration and automatically manages persistent storage:
 
+## System Requirements
+
+The satellite service requires the following runtimes to be installed on the system:
+
+### Required Runtimes
+
+- **Node.js 18+** - Requires both `node` (to build) and `npm` (to execute/install packages) for spawning MCP servers
+- **Python 3.8+** - Requires `python3` (to build) for Python-based MCP servers
+- **UV Package Manager** - Requires `uvx` (to start/execute) for Python async MCP servers
+
+### Optional Runtimes
+
+- **python** - Legacy Python symlink (warns if missing, not required)
+
+### Runtime Validation
+
+The satellite automatically validates that required runtimes are installed during startup:
+
+- **PATH-based detection**: Checks if commands are available in your system PATH (same as shell command lookup)
+- **Works everywhere**: Finds commands regardless of installation location (Homebrew, custom paths, etc.)
+- **Fail-fast**: If required runtimes are missing, satellite exits with a clear error message
+- **All commands required**: For Node.js, both `node` AND `npm` must be present. For Python, both `python3` AND `uvx` must be present.
+
+To skip runtime validation (e.g., for CI/CD or Docker builds):
+
+```bash
+DEPLOYSTACK_SKIP_RUNTIME_CHECKS=true npm start
+```
+
+**Note**: Skipping runtime checks is not recommended. MCP servers will fail at spawn time if runtimes are actually missing.
+
 ### Persistent Storage
 
 Satellites maintain registration state across restarts using local file storage:

services/satellite/src/server.ts

@@ -23,6 +23,7 @@ import { McpActivityTracker } from './services/mcp-activity-tracker';
 import { ToolSearchService } from './services/tool-search-service';
 import { OAuthTokenService } from './services/oauth-token-service';
 import { SsePingService } from './services/sse-ping-service';
+import { validateSystemRuntimes } from './utils/runtime-validator.js';
 
 /**
  * Validate registration token format and availability
@@ -154,6 +155,17 @@ export async function createServer() {
   validateSatelliteName(satelliteName, tempLogger);
   validateRegistrationToken(registrationToken, tempLogger);
 
+  // STEP 1.5: Validate system runtimes (Node.js, Python)
+  tempLogger.info({ operation: 'runtime_validation_start' }, 'Validating system runtimes...');
+  const skipRuntimeChecks = process.env.DEPLOYSTACK_SKIP_RUNTIME_CHECKS === 'true';
+
+  if (skipRuntimeChecks) {
+    tempLogger.info({ operation: 'runtime_validation_skipped' }, 'Runtime validation skipped (DEPLOYSTACK_SKIP_RUNTIME_CHECKS=true)');
+  } else {
+    validateSystemRuntimes(tempLogger);
+    tempLogger.info({ operation: 'runtime_validation_complete' }, 'System runtime validation passed');
+  }
+
   const server = fastify({
     logger: loggerConfig,
     disableRequestLogging: true,