> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudshipai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Lighthouse

> The CloudShip communication service

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

```mermaid theme={null}
sequenceDiagram
    participant CloudShip
    participant Lighthouse
    participant Station
    
    Station->>Lighthouse: Register (registration_key)
    Lighthouse->>Station: Connection Accepted
    
    loop Management Channel
        Station->>Lighthouse: Status Update
        Lighthouse->>Station: Commands
    end
    
    CloudShip->>Lighthouse: Execute Agent
    Lighthouse->>Station: Agent Task
    Station->>Lighthouse: Agent Response
    Lighthouse->>CloudShip: Result
```

## Communication Protocol

### Registration

Station connects with registration key:

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

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

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

```bash theme={null}
cd cloudshipai/infrastructure/lighthouse
go run cmd/main.go
```

Configure Station to connect:

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