Skip to main content

​
What is Lighthouse?

Lighthouse is the gRPC service that enables communication between CloudShip Platform and registered Stations.

​
Features

  • Bidirectional Streaming - Real-time command dispatch and response
  • Station Management - Track connected Stations and their capabilities
  • Secure Communication - TLS-encrypted gRPC channels
  • Load Balancing - Distribute commands across healthy Stations

​
Architecture

​
Communication Protocol

​
Registration

Station connects with registration key: 
service Lighthouse {
  rpc Register(RegisterRequest) returns (RegisterResponse);
  rpc ManagementChannel(stream StationMessage) returns (stream LighthouseMessage);
}

​
Commands

Lighthouse sends commands to Stations:
CommandDescription
EXECUTE_AGENTRun an agent with task
LIST_AGENTSGet available agents
LIST_TOOLSGet available MCP tools
INSTALL_BUNDLEInstall bundle from registry
SYNCTrigger configuration sync

​
Self-Hosted Lighthouse

For enterprise deployments, run your own Lighthouse:

​
Requirements

  • PostgreSQL database
  • Redis (optional, for caching)
  • TLS certificates

​
Docker Deployment

services:
  lighthouse:
    image: ghcr.io/cloudshipai/lighthouse:latest
    ports:
      - "50051:50051"
    environment:
      - DATABASE_URL=postgresql://user:pass@postgres:5432/lighthouse
      - GRPC_PORT=50051
      - LOG_LEVEL=info
    volumes:
      - ./certs:/certs:ro

​
Configuration

# lighthouse.yaml
grpc:
  port: 50051
  tls:
    enabled: true
    cert_file: /certs/server.crt
    key_file: /certs/server.key

database:
  url: postgresql://user:pass@localhost:5432/lighthouse
  max_connections: 100

redis:
  url: redis://localhost:6379/0

​
Local Development

Run Lighthouse locally for testing: 
cd cloudshipai/infrastructure/lighthouse
go run cmd/main.go
Configure Station to connect: 
# Station config.yaml
cloudship:
  enabled: true
  registration_key: "test-key"
  endpoint: localhost:50051
  use_tls: false  # Disable TLS for local dev

​
Monitoring

Lighthouse exposes metrics:
MetricDescription
lighthouse_stations_connectedNumber of connected Stations
lighthouse_commands_totalTotal commands processed
lighthouse_command_duration_secondsCommand execution time
lighthouse_errors_totalError count
Access metrics at /metrics endpoint.

​
Troubleshooting

​
Station Won’t Connect

Error: connection refused
Check:
  • Lighthouse is running
  • Port 50051 is accessible
  • TLS configuration matches

​
Commands Timeout

Error: deadline exceeded
Check:
  • Station is responsive
  • Network latency
  • Command timeout settings

​
Authentication Failed

Error: invalid registration key
Check:
  • Registration key is valid
  • Key hasn’t been used before
  • Organization permissions