> ## 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.

# Satellite Commands Reference

> Complete reference of satellite command types, priorities, and their purposes in the DeployStack satellite system.

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

| Priority    | Polling Interval | Use Case                              |
| ----------- | ---------------- | ------------------------------------- |
| `immediate` | 2 seconds        | MCP installations, critical updates   |
| `high`      | 10 seconds       | MCP deletions, configuration changes  |
| `normal`    | 30 seconds       | Routine 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**:

```json theme={null}
{
  "event": "mcp_installation_created|mcp_installation_updated|mcp_installation_deleted|mcp_recovery|mcp_redeploy",
  "installation_id": "installation-uuid",
  "team_id": "team-uuid",
  "user_id": "user-uuid"
}
```

**Event Types**:

| Event                      | Purpose                          | Triggered By                                     |
| -------------------------- | -------------------------------- | ------------------------------------------------ |
| `mcp_installation_created` | Initial MCP server installation  | User installs new MCP server                     |
| `mcp_installation_updated` | Configuration update (args, env) | User modifies MCP server settings                |
| `mcp_installation_deleted` | MCP server removal               | User uninstalls MCP server                       |
| `mcp_recovery`             | Offline server recovery          | Backend health check detects server back online  |
| `mcp_redeploy`             | GitHub deployment redeploy       | User clicks "Redeploy" on GitHub-deployed server |

**Satellite Actions**:

**For `mcp_installation_created` and `mcp_installation_updated`**:

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. Perform tool discovery on newly spawned/configured servers
5. Report process status to backend via events

**For `mcp_installation_deleted`**:

1. Terminate MCP servers for deleted installations:
   * **stdio transport**: Graceful process termination (SIGTERM → SIGKILL)
   * **HTTP transport**: Remove proxy routes
2. Clean up deployment directories (GitHub deployments)
3. Clear dormant configs and restart tracking

**For `mcp_recovery`**:

1. Find server config by installation\_id
2. Skip stdio servers (handled via process lifecycle)
3. For HTTP/SSE servers:
   * Emit `connecting` status
   * Trigger tool re-discovery
   * Emit `discovering_tools` → `online` status progression
4. Update frontend with recovered server status

**For `mcp_redeploy`** (GitHub deployments only):

1. Find server config by installation\_id and user\_id
2. For active stdio processes:
   * Call `removeServerCompletely()` to delete deployment directory
   * Trigger config refresh to download fresh from GitHub
   * Extract, install dependencies, build, spawn with new code
3. For dormant stdio processes:
   * Clear dormant config to force fresh download
   * Trigger config refresh
4. For HTTP/SSE servers:
   * Trigger tool re-discovery (no code download needed)
5. Status progression: `restarting` → `connecting` → `discovering_tools` → `online`
6. New tools from GitHub repository become available

**GitHub Redeploy Flow**:

* Deletes old deployment directory (`/tmp/mcp-xxx` or `/opt/mcp-deployments/...`)
* Downloads fresh tarball from GitHub (new commit SHA)
* Extracts to new directory
* Runs `npm install` or `uv sync`
* Runs build scripts if configured
* Spawns process with updated code
* Discovers new/updated tools

### restart

**Purpose**: Restarts specific MCP server processes

**Priority**: `high`

**Triggered By**:

* Manual restart requests
* Error recovery procedures
* Configuration reload requirements

**Payload Structure**:

```json theme={null}
{
  "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**:

```json theme={null}
{
  "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

### health\_check

**Purpose**: Validates MCP server credentials and connectivity

**Priority**: `immediate`

**Triggered By**:

* Backend credential validation cron (every 1 minute)
* Manual credential testing
* OAuth token expiration detection

**Payload Structure**:

```json theme={null}
{
  "check_type": "credential_validation",
  "installation_id": "installation-uuid",
  "team_id": "team-uuid"
}
```

**Satellite Actions**:

1. Find MCP server configuration by installation\_id
2. Skip stdio servers (no HTTP credentials to validate)
3. Build HTTP request with configured credentials (headers, query params)
4. Call `tools/list` with 15-second timeout
5. Detect authentication errors:
   * HTTP 401/403 responses
   * Error messages containing "auth", "unauthorized", "forbidden"
6. Emit status event:
   * On auth failure → `requires_reauth` status
   * On success → credentials valid (no status change)

**Error Detection Patterns**:

* HTTP status codes: 401, 403
* Response body keywords: "auth", "unauthorized", "forbidden", "token", "credentials"

See [Status Tracking](/development/satellite/status-tracking) for credential validation status flow.

## 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