CloudShip Integration

Connect your Station to CloudShip for centralized management, OAuth authentication, and team collaboration.

Why CloudShip?

Feature	Standalone Station	With CloudShip
Management	Local only	Centralized dashboard
Authentication	Manual API keys	OAuth for team members
Collaboration	Single user	Organization-wide access
Audit Trail	Local logs	Centralized tracking

Quick Setup

1. Get a Registration Key

From your CloudShip dashboard:

Go to Settings > Stations
Click Create Registration Key
Copy the key

2. Configure Station

Add to your config.yaml:

cloudship:
  enabled: true
  registration_key: "sk-reg-..."
  name: "my-station"
  tags: ["production", "us-east-1"]

3. Start Station

stn serve
# Output: Successfully registered with CloudShip management channel

Your Station is now connected and visible in your CloudShip dashboard.

Authentication Methods

stn auth login

Using config file: /home/user/.config/station/config.yaml
Enter your CloudShip API key: ▌

Get your API key from CloudShip Settings > API Keys.

Registration Key (Automated)

For automated deployments, use a registration key in config:

cloudship:
  enabled: true
  registration_key: "sk-reg-..."

Check Status

stn auth status

CloudShip Connection:
  ✅ Connected to CloudShip
  Organization: My Company
  Station: production-us-east
  Last sync: 2 minutes ago

OAuth for MCP Access

When CloudShip OAuth is enabled, MCP clients authenticate through CloudShip before accessing your Station’s agents.

Who Can Access?

Only users who:

Have a CloudShip account
Are members of your organization
Successfully authenticate via OAuth

Enable OAuth

Create an OAuth App in CloudShip (Settings > OAuth Apps)
Configure Station:

cloudship:
  enabled: true
  registration_key: "your-key"
  name: "my-station"
  oauth:
    enabled: true
    client_id: "your-oauth-client-id"

Invite team members to your CloudShip organization

How OAuth Works

MCP Client                    Station                      CloudShip
    |                           |                             |
    |------ POST /mcp --------->|                             |
    |<----- 401 Unauthorized ---|                             |
    |       (OAuth discovery)   |                             |
    |                           |                             |
    |------- [Browser Login] -------------------------------->|
    |<------ [Access Token] ----------------------------------|
    |                           |                             |
    |------ POST /mcp --------->|                             |
    |  Authorization: Bearer    |------ Validate Token ------>|
    |                           |<------ {active: true} ------|
    |<----- MCP Response -------|                             |

MCP Client Configuration

Point your MCP client to port 8587 (Dynamic Agent MCP):

{
  "mcpServers": {
    "my-station": {
      "url": "https://my-station.example.com:8587/mcp"
    }
  }
}

When connecting:

Client receives 401 with OAuth discovery URL
Browser opens for CloudShip login
After authentication, client automatically retries with token

Configuration Reference

cloudship:
  # Enable CloudShip integration
  enabled: true
  
  # Registration key from CloudShip dashboard
  registration_key: "sk-reg-..."
  
  # Unique station name (required for multi-station support)
  name: "production-us-east"
  
  # Tags for filtering and organization
  tags: ["production", "us-east-1", "sre-team"]
  
  # CloudShip endpoints (defaults shown - usually no need to change)
  endpoint: "lighthouse.cloudshipai.com:443"
  use_tls: true
  base_url: "https://app.cloudshipai.com"
  
  # OAuth settings for MCP authentication
  oauth:
    enabled: false
    client_id: ""
    # Auto-configured from base_url:
    # auth_url: "https://app.cloudshipai.com/oauth/authorize/"
    # token_url: "https://app.cloudshipai.com/oauth/token/"
    # introspect_url: "https://app.cloudshipai.com/oauth/introspect/"

Development Setup

Local Development (No CloudShip)

# config.yaml - no cloudship section needed
ai_provider: anthropic
ai_model: claude-sonnet-4-20250514

Local Lighthouse (Testing)

For testing CloudShip integration locally:

cloudship:
  enabled: true
  registration_key: "your-dev-key"
  name: "dev-station"
  endpoint: "localhost:50051"
  use_tls: false
  base_url: "http://localhost:8000"
  oauth:
    enabled: true
    client_id: "your-dev-client-id"
    introspect_url: "http://localhost:8000/oauth/introspect/"

Production CloudShip (Recommended)

cloudship:
  enabled: true
  registration_key: "your-registration-key"
  name: "dev-station"
  # Uses defaults: endpoint=lighthouse.cloudshipai.com:443, use_tls=true

Multi-Station Management

Naming Stations

Each Station needs a unique name within your organization:

# Station 1: Production US
cloudship:
  name: "prod-us-east"
  tags: ["production", "us-east-1"]

# Station 2: Production EU
cloudship:
  name: "prod-eu-west"
  tags: ["production", "eu-west-1"]

# Station 3: Development
cloudship:
  name: "dev-local"
  tags: ["development", "local"]

Filtering by Tags

In CloudShip dashboard, filter Stations by tags to manage specific environments.

Security

Registration Keys

Keep registration keys secret
Rotate keys periodically
Use different keys for different environments

OAuth Tokens

Validated on every MCP request
PKCE required (S256 code challenge)
Cached for 5 minutes to reduce introspection calls

Audit Trail

CloudShip logs all:

Station connections/disconnections
Agent executions triggered via MCP
OAuth authentications
Configuration changes

Troubleshooting

Connection Failed

Error: failed to connect to CloudShip

Check:

Registration key is valid
Network allows outbound to lighthouse.cloudshipai.com:443
TLS is properly configured

OAuth 401 Errors

Error: 401 Unauthorized