Skip to main content

​
Satellite Commands Reference

The satellite command system enables real-time communication between the backend and distributed satellites. Commands are stored in the satelliteCommands database table and processed by satellites through polling mechanisms.

​
Command Architecture

​
Command Structure

Each satellite command contains:
  • Command Type: Defines the action to be performed
  • Priority Level: Determines polling frequency and execution urgency
  • Target Satellite: Specific satellite ID or all global satellites
  • Payload: JSON data containing command-specific parameters
  • Expiration: Commands expire after a defined time period

​
Priority Levels

PriorityPolling IntervalUse Case
immediate2 secondsMCP installations, critical updates
high10 secondsMCP deletions, configuration changes
normal30 secondsRoutine maintenance, non-urgent tasks

​
Command Types

​
configure

Purpose: Triggers MCP server configuration refresh and spawning Priority: immediate (installations/updates) or high (general config changes) Triggered By:
  • MCP server installations
  • MCP server updates
  • MCP server deletions
  • MCP server argument modifications
  • MCP server environment variable changes
Payload Structure: 
{
  "event": "mcp_installation_created|mcp_installation_updated",
  "installation_id": "installation-uuid",
  "team_id": "team-uuid"
}
Satellite Actions:
  1. Fetch updated MCP server configurations from backend
  2. Compare with existing configurations using hash-based change detection
  3. Spawn new MCP servers based on transport type:
    • stdio transport: Spawn Node.js subprocess via ProcessManager
    • HTTP transport: Configure HTTP proxy routes
  4. Terminate MCP servers for deleted installations:
    • stdio transport: Graceful process termination (SIGTERM → SIGKILL)
    • HTTP transport: Remove proxy routes
  5. Perform tool discovery on newly spawned/configured servers
  6. Report process status to backend via team-grouped heartbeat

​
restart

Purpose: Restarts specific MCP server processes Priority: high Triggered By:
  • Manual restart requests
  • Error recovery procedures
  • Configuration reload requirements
Payload Structure: 
{
  "installation_id": "installation-uuid",
  "reason": "error_recovery|manual_restart|config_reload"
}
Satellite Actions:
  1. Gracefully terminate existing MCP server process
  2. Clear process state and temporary resources
  3. Respawn MCP server with current configuration
  4. Re-establish HTTP proxy routes
  5. Perform health checks on restarted process

​
update

Purpose: Updates satellite system components or configurations Priority: normal Triggered By:
  • Satellite software updates
  • System configuration changes
  • Maintenance procedures
Payload Structure: 
{
  "component": "satellite|proxy|discovery",
  "version": "1.2.3",
  "config_changes": {}
}
Satellite Actions:
  1. Download and validate update packages
  2. Perform backup of current state
  3. Apply updates with rollback capability
  4. Restart affected components
  5. Verify system integrity post-update

​
Command Lifecycle

​
Creation

Commands are created by the SatelliteCommandService in the backend: File: services/backend/src/services/satelliteCommandService.ts Methods:
  • createCommandForAllGlobalSatellites() - Broadcasts to all global satellites
  • createCommandForSpecificSatellite() - Targets specific satellite
  • createCommandForTeamSatellites() - Targets team-specific satellites

​
Processing

Commands are processed by satellites through the command polling service: File: services/satellite/src/services/command-polling-service.ts Process:
  1. Poll backend for pending commands
  2. Determine polling frequency based on command priorities
  3. Execute command-specific actions
  4. Mark commands as completed or failed
  5. Report execution results to backend

​
Expiration

Commands automatically expire to prevent stale command execution:
  • Default Expiration: 5 minutes for most commands
  • Cleanup Expiration: 10 minutes for deletion commands
  • Update Expiration: 30 minutes for system updates
Expired commands are ignored during processing and cleaned up by background tasks.

​
Integration Points

​
Backend Integration

The satellite command system integrates with MCP installation routes:
  • services/backend/src/routes/mcp/installations/create.ts
  • services/backend/src/routes/mcp/installations/update.ts
  • services/backend/src/routes/mcp/installations/delete.ts
  • services/backend/src/routes/mcp/installations/updateArgs.ts
  • services/backend/src/routes/mcp/installations/updateEnvironmentVars.ts

​
Satellite Integration

Satellites process commands through dedicated service components:
  • Command Polling: Fetches and prioritizes commands
  • Dynamic Config Manager: Handles configuration updates
  • HTTP Proxy Manager: Manages proxy route changes
  • Remote Tool Discovery: Discovers tools on new MCP servers

​
Performance Characteristics

​
Response Times

  • Immediate Commands: 2-3 second end-to-end response time
  • High Priority Commands: 10-15 second response time
  • Normal Commands: 30-60 second response time

​
Scalability

  • Commands scale horizontally across multiple satellites
  • Global satellites receive broadcast commands automatically
  • Team-specific satellites receive targeted commands only
  • Command processing is asynchronous and non-blocking

​
Reliability

  • Commands include retry mechanisms with configurable limits
  • Failed commands are logged with detailed error information
  • Command expiration prevents indefinite retry loops
  • Correlation IDs enable command tracking across system boundaries
⌘I