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

> Complete guide to DeployStack Satellite registration process - environment variables, validation rules, upsert logic, and database integration.

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:**

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

```bash theme={null}
# 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
```

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

## 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](/development/backend/api/security#registration-token-authentication).

## Environment Variables

### Required Configuration

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

```bash theme={null}
# 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:

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

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

## 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](/development/backend/satellite/communication#satellite-pairing-process).

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

```bash theme={null}
dev-satellite-001
production_worker_main
team-europe-01
staging_mcp_server
```

**Invalid Examples:**

```bash theme={null}
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:

```bash theme={null}
❌ 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:

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

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

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

```bash theme={null}
# 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:

```bash theme={null}
# 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

```bash theme={null}
🔍 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:

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

```bash theme={null}
❌ FATAL ERROR: DEPLOYSTACK_SATELLITE_NAME ist erforderlich
```

**Solution:** Set the required environment variable

**Missing Registration Token:**

```bash theme={null}
❌ FATAL ERROR: DEPLOYSTACK_REGISTRATION_TOKEN ist erforderlich
```

**Solution:** Obtain registration token from admin and set environment variable

**Invalid Registration Token:**

```bash theme={null}
❌ FATAL ERROR: Invalid registration token format or expired
```

**Solution:** Generate new registration token from admin interface

**Invalid Satellite Name:**

```bash theme={null}
❌ FATAL ERROR: Ungültiger Satellite Name
```

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

**Backend Unreachable:**

```bash theme={null}
❌ 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:

```bash theme={null}
# 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

<Info>
  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](/development/backend/api/security#registration-token-authentication) for complete token management details.
</Info>