Skip to main content

​
DeployStack Satellite Development

DeployStack Satellites are edge workers (similar to GitHub Actions runners) that manage MCP servers with enterprise-grade team isolation and security. This service represents DeployStack’s strategic pivot from local CLI gateway to cloud-native MCP-as-a-Service platform.

​
Current Implementation Status

:The satellite service has completed
  • ✅ Fastify HTTP Server with Swagger API documentation
  • ✅ Pino Logging System identical to backend configuration
  • ✅ MCP Transport Protocols - SSE, SSE Messaging, Streamable HTTP
  • ✅ Session Management with cryptographically secure session IDs
  • ✅ JSON-RPC 2.0 Protocol compliance for MCP communication
  • ✅ TypeScript + Webpack build system with full type safety
  • ✅ Development Workflow with hot reload and linting
  • ✅ Backend Communication (polling, commands, heartbeat with team-grouped processes)
  • ✅ Real-Time Event System (immediate event emission with 3s batching, 10 event types)
  • ✅ OAuth 2.1 Authentication (token introspection, team context)
  • ✅ stdio MCP Server Process Management (spawn, monitor, auto-restart, terminate)
  • ✅ Team Isolation (environment-based: nsjail in production, plain spawn in dev)
  • ✅ Auto-Restart Protection (max 3 attempts, permanently_failed status)
  • ✅ Tool Discovery (HTTP and stdio MCP servers)
  • ✅ Background Jobs System (cron-like recurring tasks with automatic error handling)

​
Architecture Vision

Satellites implement a hybrid edge worker pattern with five core internal components:
  • HTTP Proxy Router: Team-aware request routing with OAuth 2.1 authentication
  • Dual MCP Server Manager: Manages both external HTTP endpoints and stdio subprocess MCP servers
  • Team Resource Manager: Linux namespaces, cgroups, and resource jailing (0.1 CPU, 100MB RAM per process)
  • Communication Manager: Handles stdio JSON-RPC and HTTP proxy communication
  • Backend Communicator: Integration with DeployStack Backend for configuration and monitoring

​
Deployment Models (Planned)

Satellites will support two deployment patterns:
  • Global Satellites: DeployStack-operated cloud infrastructure serving all teams with resource isolation
  • Team Satellites: Customer-deployed within corporate networks for internal resource access
  • Dual MCP Server Support: Both HTTP proxy (external endpoints) and stdio subprocess (local) MCP servers

​
Technology Stack

  • Runtime: Node.js with TypeScript
  • HTTP Framework: Fastify with native JSON Schema validation
  • Logging: Pino logger with structured logging
  • MCP Transport: SSE, Streamable HTTP, Direct HTTP protocols
  • Session Management: Cryptographically secure 32-byte session IDs
  • Authentication: OAuth 2.1 Resource Server (planned)
  • Process Management: stdio subprocess management (planned)
  • Team Isolation: Linux namespaces and cgroups (planned)
  • Build System: TypeScript + Webpack
  • Development: Nodemon with hot reload

​
Quick Start

​
Current Development Setup

# Clone and setup
cd services/satellite
npm install

# Configure environment
cp .env.example .env
# Edit LOG_LEVEL, PORT as needed

# Start development server
npm run dev
# Server runs on http://localhost:3001
# API docs: http://localhost:3001/documentation

​
Available Scripts

npm run dev      # Development server with hot reload
npm run build    # Production build
npm run start    # Start production server
npm run lint     # ESLint with auto-fix
npm run release  # Release management

​
Development Guides

Architecture Design

Learn the satellite system architecture, current implementation, and planned features.

MCP Transport Protocols

External communication endpoints for MCP client integration - SSE, Streamable HTTP, and Direct HTTP.

Logging & Configuration

Pino logging setup, log levels, environment configuration, and development patterns.

Global Satellites

Managed satellite infrastructure, auto-scaling, multi-region deployment, and freemium model.

Team Satellites

Enterprise on-premise deployment, internal resource access, and complete team isolation.

Security & Isolation

Resource jailing, team isolation, credential management, and enterprise security features.

MCP Server Management

Satellite-hosted MCP servers, process management, and tool availability.

Configuration Management

Satellite configuration, team settings, and deployment parameters.

Testing Strategy

Testing satellite infrastructure, deployment validation, and integration testing.

Deployment & Operations

Satellite deployment patterns, monitoring, scaling, and operational considerations.

Background Jobs

Cron-like job system for recurring tasks with automatic error handling and monitoring.

Event System

Real-time event emission from satellite to backend with automatic batching and error handling.

​
Current Features

​
MCP Transport Layer

  • SSE Transport: Server-Sent Events with session management
  • SSE Messaging: JSON-RPC message sending via established sessions
  • Streamable HTTP: Direct HTTP communication with optional streaming
  • Session Management: 32-byte cryptographically secure session IDs
  • JSON-RPC 2.0: Full protocol compliance with error handling
  • CORS Support: Cross-origin request handling

​
Foundation Infrastructure

  • Fastify HTTP Server: High-performance server with automatic request validation
  • Swagger Documentation: Auto-generated API documentation at /documentation
  • Environment Configuration: .env file support with LOG_LEVEL control
  • Structured Logging: Pino logger with development and production modes
  • TypeScript Support: Full type safety with hot reload development

​
Development Workflow

  • Hot Reload: Automatic server restart on code changes
  • Linting: ESLint with auto-fix for code quality
  • Build System: TypeScript compilation with Webpack bundling
  • Release Management: Conventional changelog with release-it

​
Implemented Features

​
Phase 2: MCP Server Process Management

  • Process Lifecycle: Spawn, monitor, auto-restart (max 3), and terminate MCP servers
  • stdio Communication: Full JSON-RPC 2.0 protocol over stdin/stdout
  • HTTP Proxy: Reverse proxy for external MCP server endpoints working
  • Health Monitoring: Process crash detection with auto-restart
  • Resource Limits: nsjail with 100MB RAM, 60s CPU, 50 processes (production Linux)
  • Tool Discovery: Automatic tool caching from both HTTP and stdio servers
  • Team-Grouped Heartbeat: processes_by_team reporting every 30 seconds

​
Phase 3: Team Isolation

  • nsjail Sandboxing: Complete process isolation with built-in resource limits
  • Namespace Isolation: PID, mount, UTS, IPC namespaces per team
  • Filesystem Isolation: Team-specific read-only and writable directories
  • Credential Management: Secure environment injection via nsjail

​
Phase 4: Backend Integration

  • HTTP Polling: Outbound communication with DeployStack Backend
  • Configuration Sync: Dynamic configuration updates from Backend
  • Status Reporting: Real-time satellite health and usage metrics
  • Command Processing: Execute Backend commands with acknowledgment
  • Event System: Real-time event emission with automatic batching (10 event types)

​
Phase 5: Enterprise Features

  • OAuth 2.1 Authentication: Resource server with token introspection
  • Audit Logging: Complete audit trails for compliance
  • Multi-Region Support: Global satellite deployment
  • Auto-Scaling: Dynamic resource allocation based on demand

​
Development Patterns

​
MCP Transport Development

Follow established patterns when working with MCP transport:
  1. Use manual JSON serialization with JSON.stringify()
  2. Implement comprehensive error handling with proper HTTP status codes
  3. Include structured logging with operation tracking
  4. Handle session management and activity tracking
  5. Support both streaming and standard response modes

​
API Route Development

Follow established patterns when adding new routes:
  1. Create route files in src/routes/ directories
  2. Use reusable JSON Schema constants for validation
  3. Implement TypeScript interfaces for type safety
  4. Use manual JSON serialization with JSON.stringify()
  5. Register routes in src/routes/index.ts

​
Configuration Management

  • Use environment variables for configuration
  • Provide sensible defaults for development
  • Document all configuration options
  • Support both development and production modes

​
Contributing

When contributing to satellite development:
  1. Follow Backend Patterns: Use identical logging, validation, and error handling
  2. Maintain Type Safety: Leverage TypeScript for compile-time validation
  3. Document Changes: Update relevant documentation for new features
  4. Test Thoroughly: Ensure changes work in both development and production
  5. Consider Enterprise: Design features with team isolation and security in mind
⌘I