Lighthouse - CloudShip AI

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:

Command	Description
`EXECUTE_AGENT`	Run an agent with task
`LIST_AGENTS`	Get available agents
`LIST_TOOLS`	Get available MCP tools
`INSTALL_BUNDLE`	Install bundle from registry
`SYNC`	Trigger 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:

Metric	Description
`lighthouse_stations_connected`	Number of connected Stations
`lighthouse_commands_total`	Total commands processed
`lighthouse_command_duration_seconds`	Command execution time
`lighthouse_errors_total`	Error 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

​What is Lighthouse?

​Features

​Architecture

​Communication Protocol

​Registration

​Commands

​Self-Hosted Lighthouse

​Requirements

​Docker Deployment

​Configuration

​Local Development

​Monitoring

​Troubleshooting

​Station Won’t Connect

​Commands Timeout

​Authentication Failed

What is Lighthouse?

Features

Architecture

Communication Protocol

Registration

Commands

Self-Hosted Lighthouse

Requirements

Docker Deployment

Configuration

Local Development

Monitoring

Troubleshooting

Station Won’t Connect

Commands Timeout

Authentication Failed