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

Important: The persistent_data/ directory must be writable by the satellite process. In production deployments, ensure proper volume mounting and permissions.

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

# Optional satellite URL configuration
DEPLOYSTACK_SATELLITE_URL=https://satellite.example.com

Satellite URL Configuration (Optional)

DEPLOYSTACK_SATELLITE_URL Environment Variable: This optional environment variable configures the publicly accessible URL of the satellite instance. Behavior:

If set: Satellite sends explicit URL to backend during registration
If not set: Backend uses default http://127.0.0.1:3001 or auto-detects from request headers
Important: URL is sent only during registration, NOT in heartbeats

When to Use:

Production deployments with known public URLs
OAuth 2.0 Protected Resource Metadata requirements
Satellites behind reverse proxies or load balancers

Format:

Base URL without path suffix
Example: https://satellite.example.com (NOT https://satellite.example.com/mcp)

Examples:

# Production global satellite
DEPLOYSTACK_SATELLITE_URL=https://satellite.deploystack.io

# Production team satellite
DEPLOYSTACK_SATELLITE_URL=https://satellite-team1.example.com

# Development (auto-detection or default)
# DEPLOYSTACK_SATELLITE_URL=    # Leave blank - uses default http://127.0.0.1:3001

Default URL:

Database default: http://127.0.0.1:3001
Used when DEPLOYSTACK_SATELLITE_URL is not set during registration
Can be overridden by setting the environment variable

Region Configuration (Backend-Only)

Region Field: The region field is a backend-configurable field for organizational purposes. Satellites do not send region data - it must be set by backend administrators. Purpose:

Geographic grouping of satellites
Capacity planning and analytics
Regional routing strategies

Configuration: Backend administrators set the region via API or database:

-- Set region for a satellite
UPDATE satellites
SET region = 'us-east-1'
WHERE id = 'sat-xxx';

Common Values:

AWS-style regions: us-east-1, eu-central-1, ap-southeast-1
Geographic labels: north-america, europe, asia-pacific
Custom labels: on-premise, data-center-1, cloud

The satellite service does NOT send region information during registration or heartbeat. Region is a backend-only field managed by administrators.

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']
  satellite_url?: string;         // From DEPLOYSTACK_SATELLITE_URL (optional)
  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.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
✅ Bearer token authentication for Backend communication
✅ Admin interface for registration token management
✅ Satellite client registration token support
🚧 API key rotation and renewal
🚧 Registration status monitoring and alerts

The satellite registration system implements secure JWT-based pairing to prevent unauthorized satellite connections. Once registered with a valid token, satellites receive permanent API keys for ongoing communication. See Backend API Security for complete token management details.

Basics

Advanced

MCP Server Management

Status & Health Tracking

Backend Communication

Persistent Storage

API Key Persistence

Registration Token Usage

Storage Management

Registration Overview

Automatic Registration Flow

Secure Token-Based Registration

Environment Variables

Required Configuration

Satellite URL Configuration (Optional)

Region Configuration (Backend-Only)

Registration Token Requirements

Token Types and Sources

Security Model

Satellite Name Validation

Validation Rules

Fail-Fast Validation

Registration Data Structure

System Information Collection

MCP Server Capabilities

Database Integration

Satellite Tables

Registration Database Operations

Development Setup

Local Registration Testing

Expected Registration Output

Token Expiration and Re-Registration

Security Considerations

API Key Management

Centralized Security Model

Troubleshooting

Common Registration Issues

Debug Endpoints

Implementation Status

Basics

Advanced

MCP Server Management

Status & Health Tracking

Backend Communication

​Persistent Storage

​API Key Persistence

​Registration Token Usage

​Storage Management

​Registration Overview

​Automatic Registration Flow

​Secure Token-Based Registration

​Environment Variables

​Required Configuration

​Satellite URL Configuration (Optional)

​Region Configuration (Backend-Only)

​Registration Token Requirements

​Token Types and Sources

​Security Model

​Satellite Name Validation

​Validation Rules

​Fail-Fast Validation

​Registration Data Structure

​System Information Collection

​MCP Server Capabilities

​Database Integration

​Satellite Tables

​Registration Database Operations

​Development Setup

​Local Registration Testing

​Expected Registration Output

​Token Expiration and Re-Registration

​Security Considerations

​API Key Management

​Centralized Security Model

​Troubleshooting

​Common Registration Issues

​Debug Endpoints

​Implementation Status

Persistent Storage

API Key Persistence

Registration Token Usage

Storage Management

Registration Overview

Automatic Registration Flow

Secure Token-Based Registration

Environment Variables

Required Configuration

Satellite URL Configuration (Optional)

Region Configuration (Backend-Only)

Registration Token Requirements

Token Types and Sources

Security Model

Satellite Name Validation

Validation Rules

Fail-Fast Validation

Registration Data Structure

System Information Collection

MCP Server Capabilities

Database Integration

Satellite Tables

Registration Database Operations

Development Setup

Local Registration Testing

Expected Registration Output

Token Expiration and Re-Registration

Security Considerations

API Key Management

Centralized Security Model

Troubleshooting

Common Registration Issues

Debug Endpoints

Implementation Status