Satellite Commands

Documentation Index

Fetch the complete documentation index at: https://docs.deploystack.io/llms.txt

Use this file to discover all available pages before exploring further.

​

Command Queue Architecture

​

Command Flow

Backend → Creates Command → satelliteCommands Table → Satellite Polls → Executes → Reports Result → Backend Updates Status

• Command Queue: PostgreSQL table with priority-based ordering
• Polling: Satellites poll every 2-60 seconds based on priority
• Execution: Satellite processes command and performs action
• Result Reporting: Satellite reports success/failure back to backend

​

Command Types

​

Configure Commands

1. Backend creates configure command with event metadata
2. Satellite fetches fresh configuration from backend
3. DynamicConfigManager compares old vs. new config
4. Identifies added/removed/modified servers
5. Takes appropriate action (spawn/restart/terminate)

​

Command Priorities

​

Command Payload Structure

interface CommandPayload {
  event?: string;                 // Event type for logging/tracking
  installation_id?: string;       // MCP installation identifier
  team_id?: string;              // Team context
  server_name?: string;          // Legacy server identifier
  // Additional command-specific fields
}

​

Status Changes Triggered by Commands

1. Backend creates installation → creates instances for all team members
2. If user has required config → status=provisioning
3. If user missing required config → status=awaiting_user_config (not sent to satellite)
4. User configures settings → status changes to provisioning → satellite spawns
5. Satellite connects → status=connecting
6. Satellite discovers tools → status=discovering_tools
7. Process complete → status=online

​

Command Event Types

​

Event Field Usage

1. Fetches fresh config from backend
2. Compares with current running config
3. Identifies added/removed/modified servers
4. Takes appropriate action

• Installation created → All team members get instances (status depends on required user config)
• Installation updated → Only affects users with existing configs (others remain awaiting_user_config)
• Installation deleted → CASCADE deletes all user instances

• Database record keeping
• Structured logging
• Future extensibility
• Developer debugging

{
  "event": "mcp_installation_deleted",
  "installation_id": "U3hCfHenbK5kH2_8ehSGx",
  "team_id": "4vj7igb2fcwzmko"
}

​

SatelliteCommandService API

​

notifyMcpInstallation()

await satelliteCommandService.notifyMcpInstallation(
  installationId,
  teamId,
  userId
);

​

notifyMcpUpdate()

await satelliteCommandService.notifyMcpUpdate(
  installationId,
  teamId,
  userId
);

​

notifyMcpDeletion()

await satelliteCommandService.notifyMcpDeletion(
  installationId,
  teamId,
  userId
);

​

notifyMcpRecovery()

await satelliteCommandService.notifyMcpRecovery(
  installationId,
  teamId
);

• Triggered by health check detecting offline installation
• Sets status to connecting
• Satellite rediscovers tools
• Status progresses: offline → connecting → discovering_tools → online

​

notifyMcpRedeploy()

await satelliteCommandService.notifyMcpRedeploy(
  installationId,
  teamId,
  userId,
  {
    commit_sha: latestSha,
    branch: branchName
  }
);

{
  "event": "mcp_redeploy",
  "installation_id": "installation-uuid",
  "team_id": "team-uuid",
  "user_id": "user-uuid",
  "commit_sha": "abc123...",
  "branch": "main"
}

1. For active processes:
   • Calls removeServerCompletely() to delete deployment directory
   • Triggers config refresh
   • Downloads fresh tarball from GitHub
   • Extracts, installs dependencies, builds
   • Spawns with new code
2. For dormant processes:
   • Clears dormant config cache
   • Triggers config refresh
   • Forces fresh download on respawn

• Backend sets status to restarting
• Satellite deletes old deployment directory
• Downloads fresh code from GitHub (new SHA)
• Status progresses: restarting → connecting → discovering_tools → online
• New/updated tools become available

• notifyMcpUpdate() → Restarts with existing cached code
• notifyMcpRedeploy() → Deletes cache, downloads fresh from GitHub

​

Critical Pattern

• Installation created → notifyMcpInstallation()
• Installation updated → notifyMcpUpdate()
• Installation deleted → notifyMcpDeletion()
• Server recovered → notifyMcpRecovery()
• GitHub deployment redeploy → notifyMcpRedeploy()

• ❌ Don’t call notifyMcpInstallation() for delete operations
• ❌ Don’t call notifyMcpUpdate() for GitHub redeploy (won’t download fresh code)
• ❌ Don’t call notifyMcpInstallation() for redeploy (wrong semantic meaning)

​

Command Lifecycle

​

Retry Logic

• Max Retries: 3 attempts
• Retry Delay: Exponential backoff
• Expiration: Commands expire after 5 minutes

​

Database Schema

• id: Command UUID
• satellite_id: Target satellite
• command_type: One of 5 command types
• priority: Command priority level
• payload: JSON command data (includes event type)
• status: Current execution state
• target_team_id: Team context
• correlation_id: Request tracing
• retry_count: Retry attempts
• error_message: Failure details
• result: Execution result

​

Command Processing on Satellite

1. Fetch fresh configuration from backend
2. Compare with current running config
3. Identify changes (added/removed/modified servers)
4. Execute appropriate actions:
   • Added: Spawn new processes
   • Modified: Restart affected processes
   • Removed: Terminate processes

1. Parse server configuration
2. For stdio: Launch subprocess with JSON-RPC
3. For HTTP/SSE: Create proxy tracker entry
4. Discover tools via tools/list call

1. Locate running process
2. Send SIGTERM for graceful shutdown
3. Wait for timeout (10 seconds)
4. Send SIGKILL if needed

1. Execute kill sequence
2. Wait for process termination
3. Execute spawn sequence

1. Check payload.check_type field:
   • connectivity (default): Call tools/list to verify server responds
   • credential_validation: Validate OAuth tokens for installation
2. Execute appropriate validation
3. Report health status via mcp.server.status_changed event:
   • online - Health check passed
   • requires_reauth - OAuth token expired/revoked
   • error - Validation failed with error

• Backend cron job sends health_check command with check_type: 'credential_validation'
• Satellite validates OAuth token (performs token refresh test)
• Emits status event based on validation result
• Backend updates mcpServerInstallations.status and last_credential_check_at

​

Example Usage

​

Creating Commands for Installation Deletion

// In route handler
const satelliteCommandService = new SatelliteCommandService(db, logger);
const commands = await satelliteCommandService.notifyMcpDeletion(
  installationId,
  teamId,
  userId
);

logger.info({
  installationId,
  commandsCreated: commands.length,
  satelliteIds: commands.map(c => c.satellite_id)
}, 'Satellite commands created for deletion');

​

Creating Commands for Configuration Update

// After updating environment variables
const satelliteCommandService = new SatelliteCommandService(db, logger);
const commands = await satelliteCommandService.notifyMcpUpdate(
  installationId,
  teamId,
  userId
);

​

Monitoring Commands

​

Check Command Status

SELECT id, command_type, status, priority, created_at, updated_at
FROM "satelliteCommands"
WHERE satellite_id = 'sat-123'
ORDER BY created_at DESC
LIMIT 10;

​

View Command Payload

SELECT id, command_type, payload::json->>'event' as event_type, payload
FROM "satelliteCommands"
WHERE id = 'cmd-456';

​

Monitor Failed Commands

SELECT id, command_type, status, retry_count, error_message
FROM "satelliteCommands"
WHERE status = 'failed'
AND retry_count >= max_retries;

​

Related Documentation

• Satellite Communication - Overall communication architecture
• Satellite Events - Event system for real-time updates
• Database Management - Schema and migrations