Satellite Registration

DeployStack Satellite implements automatic registration with the Backend during startup. This document covers the complete registration process, environment variable requirements, validation rules, and upsert logic for satellite restarts.

Persistent Storage

API Key Persistence

Satellites automatically save their registration credentials to persistent storage to avoid re-registration on restart:

Storage Location:

services/satellite/persistent_data/
└── backend.key.json

File Structure:

{
  "api_key": "deploystack_satellite_api_global_EACQ7NeRD4gNjFjPAiz90AR7NqL-LF9d",
  "satellite_id": "vwokw4qbax0cyin",
  "satellite_name": "dev-satellite-005",
  "registered_at": "2025-09-23T15:42:46.118Z",
  "last_verified": "2025-09-23T15:42:46.118Z"
}

Registration Token Usage

Single-Use Registration Flow:

• First startup: Uses registration token → Saves API key to file
• Subsequent startups: Uses saved API key → No token needed
• Token expiration: Only affects first-time registration

Benefits:

• No re-registration: Satellites restart without consuming new tokens
• Server restarts: Automatic recovery after system reboots
• Development workflow: Frequent restarts don't require new tokens

Storage Management

Automatic Operations:

• Save: Credentials saved after successful registration
• Load: Credentials loaded on startup before attempting registration
• Verify: API key verified with backend heartbeat
• Clear: Invalid credentials automatically cleared

Manual Operations:

# Force re-registration (delete persistent storage)
rm services/satellite/persistent_data/backend.key.json

# View current credentials
cat services/satellite/persistent_data/backend.key.json

Registration Overview

Automatic Registration Flow

Satellites register automatically during startup following this sequence:

Satellite Startup
    │
    ├── 1. Check Persistent Storage
    │   ├── Load persistent_data/backend.key.json
    │   ├── If API key exists → Verify with heartbeat
    │   └── If valid → Skip registration
    │
    ├── 2. Validate DEPLOYSTACK_SATELLITE_NAME
    │   ├── Length: 10-32 characters
    │   ├── Characters: a-z, 0-9, -, _
    │   └── Fail-fast if invalid
    │
    ├── 3. Validate DEPLOYSTACK_REGISTRATION_TOKEN
    │   ├── JWT token format validation
    │   ├── Required token prefix check
    │   └── Fail-fast if missing or invalid
    │
    ├── 4. Test Backend Connection
    │   ├── GET /api/health (5s timeout)
    │   └── Exit if unreachable
    │
    ├── 5. Register with Backend (if needed)
    │   ├── POST /api/satellites/register
    │   ├── Authorization: Bearer {registration_token}
    │   ├── Receive permanent API key
    │   └── Save credentials to persistent storage
    │
    └── 6. Start MCP Transport Services
        ├── SSE Handler
        ├── Streamable HTTP Handler
        └── Session Manager

Secure Token-Based Registration

The registration system requires valid JWT registration tokens for security:

• Token Required: All satellites must provide valid registration tokens during startup
• Single-Use: Registration tokens are consumed after successful pairing
• Admin-Controlled: Only administrators can generate registration tokens
• No Open Registration: Satellites cannot register without proper authorization

For detailed token management, see Registration Token Authentication.

Environment Variables

Required Configuration

# Mandatory satellite identity
DEPLOYSTACK_SATELLITE_NAME=dev-satellite-001

# Backend connection
DEPLOYSTACK_BACKEND_URL=http://localhost:3000

# Registration token (required for secure pairing)
DEPLOYSTACK_REGISTRATION_TOKEN=deploystack_satellite_global_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Registration Token Requirements

Token Types and Sources

Satellites require registration tokens generated by administrators:

Global Satellite Tokens:

• Format: deploystack_satellite_global_eyJhbGc...
• Generated by: global_admin users via backend API
• Scope: Can register global satellites serving all teams
• Expiration: 1 hour (configurable)

Team Satellite Tokens:

• Format: deploystack_satellite_team_eyJhbGc...
• Generated by: team_admin users for specific teams
• Scope: Can register team satellites for specific team only
• Expiration: 24 hours (configurable)

For token generation APIs, see Satellite Communication - Registration Tokens.

Security Model

All satellites register with secure defaults controlled by the backend:

• Token-Based Pairing: Valid JWT registration token required
• Satellite Type: Determined by token scope (global or team)
• Status: Always inactive (requires admin activation)
• Single-Use Tokens: Registration tokens consumed after successful pairing

Satellite Name Validation

Validation Rules

The DEPLOYSTACK_SATELLITE_NAME environment variable must meet strict requirements:

Length Constraints:

• Minimum: 10 characters
• Maximum: 32 characters

Character Constraints:

• Allowed: lowercase letters (a-z), numbers (0-9), hyphens (-), underscores (_)
• Forbidden: uppercase letters, spaces, special characters

Valid Examples:

dev-satellite-001
production_worker_main
team-europe-01
staging_mcp_server

Invalid Examples:

Dev-Satellite-001        # Uppercase letters
dev satellite 001        # Spaces
dev@satellite#001        # Special characters
dev-sat                  # Too short (< 10 chars)
very-long-satellite-name-that-exceeds-limit  # Too long (> 32 chars)

Fail-Fast Validation

Satellite validates the name before any other operations and exits immediately with clear German error messages:

❌ FATAL ERROR: DEPLOYSTACK_SATELLITE_NAME ist erforderlich
   Bitte setze die Environment Variable DEPLOYSTACK_SATELLITE_NAME
   Beispiel: DEPLOYSTACK_SATELLITE_NAME=dev-satellite-001

❌ FATAL ERROR: Satellite Name zu kurz
   Aktuell: "dev-sat" (7 Zeichen)
   Minimum: 10 Zeichen erforderlich

❌ FATAL ERROR: Ungültiger Satellite Name
   Aktuell: "Dev-Satellite-001"
   Erlaubt: Nur lowercase Buchstaben (a-z), Zahlen (0-9), - und _
   Keine Leerzeichen oder Großbuchstaben erlaubt

Registration Data Structure

System Information Collection

Satellites automatically collect and send system information during registration:

interface SatelliteRegistrationData {
  name: string;                    // From DEPLOYSTACK_SATELLITE_NAME
  capabilities: string[];         // ['stdio', 'http', 'sse']
  system_info: {
    os: string;                   // e.g., "darwin arm64"
    arch: string;                 // e.g., "arm64"
    node_version: string;         // e.g., "v18.17.0"
    memory_mb: number;            // Total system memory
  };
}

Backend-Controlled Fields:

• satellite_type: Always set to 'global' by backend
• team_id: Always set to null by backend (admin can change later)
• status: Always set to 'inactive' by backend (requires admin activation)

MCP Server Capabilities

Satellites report their supported MCP server types:

• stdio: Local MCP servers as child processes
• http: HTTP MCP servers (planned)
• sse: SSE MCP servers (planned)

Database Integration

Satellite Tables

The Backend maintains satellite state across five database tables:

• satellites: Core satellite registry and configuration
• satelliteCommands: Command queue for satellite management
• satelliteProcesses: MCP server process tracking
• satelliteUsageLogs: Usage analytics and audit trails
• satelliteHeartbeats: Health monitoring and status updates

See services/backend/src/db/schema.sqlite.ts for complete schema definitions.

Registration Database Operations

New Satellite Registration:

INSERT INTO satellites (
  id, name, satellite_type, team_id, status,
  capabilities, api_key_hash, system_info,
  created_by, created_at, updated_at
) VALUES (
  ?, ?, 'global', NULL, 'inactive',
  ?, ?, ?, ?, ?, ?
);

Satellite Re-Registration (Upsert):

UPDATE satellites SET
  satellite_type = 'global',
  team_id = NULL,
  status = 'inactive',
  api_key_hash = ?,
  system_info = ?,
  capabilities = ?,
  updated_at = ?
WHERE name = ?;

Security Notes:

• All satellites are created with satellite_type='global', team_id=NULL, status='inactive'
• Admin activation required before satellite can be used
• Team assignment controlled via backend admin interface

Development Setup

Local Registration Testing

# Clone and setup
git clone https://github.com/deploystackio/deploystack.git
cd deploystack/services/satellite
npm install

# Configure satellite identity and registration token
cp .env.example .env
echo "DEPLOYSTACK_SATELLITE_NAME=dev-satellite-001" >> .env
echo "DEPLOYSTACK_BACKEND_URL=http://localhost:3000" >> .env
echo "DEPLOYSTACK_REGISTRATION_TOKEN=your-token-here" >> .env

# Start satellite (will auto-register)
npm run dev

⚠️ Obtaining Registration Token: You must first generate a registration token via the backend API or admin interface:

# Generate global registration token (requires global_admin)
curl -X POST http://localhost:3000/api/satellites/global/registration-tokens \
  -H "Cookie: your-session-cookie" \
  -H "Content-Type: application/json"

# Copy the returned token to your .env file

Expected Registration Output

🔍 Validating satellite configuration...
✅ Satellite Name validiert: "dev-satellite-001"
[INFO] 🔗 Connecting to backend - required for satellite operation...
[INFO] ✅ Backend connection successful (49ms)
[INFO] 📡 Registering satellite with backend...
[INFO] ✅ Satellite registered successfully: dev-satellite-001 (k6hm1j7sy2radj8)
[INFO] 🔑 API key received and ready for authenticated communication

Token Expiration and Re-Registration

Registration tokens are single-use and expire:

# First registration (consumes token)
npm run dev
# ✅ Registration successful

# Stop and restart satellite
# Ctrl+C, then npm run dev again
# ✅ Uses permanent API key (no token needed)

# If satellite needs new registration token:
# ❌ Generate new token and update DEPLOYSTACK_REGISTRATION_TOKEN

Important: Once registered, satellites use their permanent API key for all communication. Registration tokens are only needed for initial pairing.

Security Considerations

API Key Management

• Generation: 32-byte cryptographically secure random keys
• Storage: Backend stores argon2 hash, satellite receives plain key
• Rotation: New API key generated on every registration
• Scope: API keys are scoped to satellite type (global vs team)

Centralized Security Model

All Satellites are Global:

• Name uniqueness enforced globally across all satellites
• All satellites start as inactive and require admin activation
• Team assignment controlled exclusively by backend administrators
• No client-side configuration of security-sensitive parameters

Admin-Controlled Team Assignment:

• Satellites can be assigned to teams via backend admin interface
• Team assignment changes satellite behavior and resource access
• Resource isolation enforced at runtime based on team assignment

Troubleshooting

Common Registration Issues

Missing Environment Variable:

❌ FATAL ERROR: DEPLOYSTACK_SATELLITE_NAME ist erforderlich

Solution: Set the required environment variable

Missing Registration Token:

❌ FATAL ERROR: DEPLOYSTACK_REGISTRATION_TOKEN ist erforderlich

Solution: Obtain registration token from admin and set environment variable

Invalid Registration Token:

❌ FATAL ERROR: Invalid registration token format or expired

Solution: Generate new registration token from admin interface

Invalid Satellite Name:

❌ FATAL ERROR: Ungültiger Satellite Name

Solution: Follow naming rules (10-32 chars, lowercase only)

Backend Unreachable:

❌ FATAL ERROR: Cannot reach DeployStack Backend

Solution: Verify DEPLOYSTACK_BACKEND_URL and ensure backend is running

Debug Endpoints

Use these endpoints to troubleshoot registration issues:

# Check backend connection status
curl http://localhost:3001/api/status/backend

# View satellite API documentation
open http://localhost:3001/documentation

Implementation Status

Current Implementation:

• ✅ Automatic registration during startup
• ✅ Mandatory DEPLOYSTACK_SATELLITE_NAME validation
• ✅ Upsert registration logic for restarts
• ✅ System information collection
• ✅ API key generation and management
• ✅ Database integration with 5 satellite tables
• ✅ Fail-fast validation with clear error messages
• ✅ Centralized security model (no client-controlled type/team assignment)
• ✅ Default inactive status requiring admin activation

Security Improvements:

• ✅ JWT-based registration token system prevents unauthorized satellites
• ✅ Single-use tokens with cryptographic validation
• ✅ Admin-controlled token generation with proper scope enforcement
• ✅ All satellites register as inactive requiring admin activation

Planned Features:

• ✅ JWT-based registration token system (Phase 3 complete)
• ✅ Bearer token authentication for Backend communication
• 🚧 Admin interface for registration token management (Phase 4)
• 🚧 Satellite client registration token support (Phase 5)
• 🚧 API key rotation and renewal
• 🚧 Registration status monitoring and alerts