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

# Lattice Setup

> Configuration guide for Station Lattice networking

# Lattice Setup & Configuration

This guide covers all configuration options for Station Lattice, including config file setup, environment variables, TLS encryption, and NKey authentication.

## Configuration Methods

Station Lattice can be configured through:

1. **CLI flags** (highest priority)
2. **Environment variables**
3. **Config file** (`config.yaml`)

### Config File

Add a `lattice` section to your `config.yaml`:

```yaml title="config.yaml" theme={null}
workspace: /path/to/workspace
ai_provider: openai
ai_model: gpt-4o-mini

# Lattice configuration
lattice:
  # Mode: "orchestrator" or "member"
  mode: orchestrator
  
  # Station identity
  station_id: sre-station-prod
  station_name: SRE Production Station
  
  # Orchestrator settings (when mode: orchestrator)
  embedded_nats_port: 4222
  embedded_nats_host: 0.0.0.0
  
  # Member settings (when mode: member)
  nats_urls:
    - nats://orchestrator.example.com:4222
  
  # Presence settings
  heartbeat_interval: 5s
  presence_timeout: 15s
  
  # TLS settings (optional)
  tls:
    enabled: true
    cert_file: /path/to/cert.pem
    key_file: /path/to/key.pem
    ca_file: /path/to/ca.pem
  
  # NKey authentication (optional)
  nkey:
    seed_file: /path/to/nkey.seed
```

### Environment Variables

All lattice settings can be configured via environment variables:

| Variable                         | Description                | Default        |
| -------------------------------- | -------------------------- | -------------- |
| `STN_LATTICE_MODE`               | `orchestrator` or `member` | -              |
| `STN_LATTICE_STATION_ID`         | Unique station identifier  | auto-generated |
| `STN_LATTICE_STATION_NAME`       | Human-readable name        | hostname       |
| `STN_LATTICE_NATS_URLS`          | Comma-separated NATS URLs  | -              |
| `STN_LATTICE_NATS_PORT`          | Embedded NATS port         | `4222`         |
| `STN_LATTICE_HEARTBEAT_INTERVAL` | Heartbeat frequency        | `5s`           |
| `STN_LATTICE_TLS_ENABLED`        | Enable TLS                 | `false`        |
| `STN_LATTICE_TLS_CERT`           | TLS certificate path       | -              |
| `STN_LATTICE_TLS_KEY`            | TLS key path               | -              |
| `STN_LATTICE_TLS_CA`             | TLS CA certificate path    | -              |
| `STN_LATTICE_NKEY_SEED`          | NKey seed file path        | -              |

### CLI Flags

```bash theme={null}
# Orchestrator mode
stn serve --orchestration \
  --lattice-port 4222 \
  --lattice-host 0.0.0.0

# Member mode
stn serve --lattice nats://host:4222 \
  --station-id my-station \
  --station-name "My Station"
```

## Orchestrator Configuration

### Basic Setup

```yaml title="orchestrator-config.yaml" theme={null}
workspace: /opt/station/orchestrator

lattice:
  mode: orchestrator
  station_id: orchestrator-main
  station_name: Main Orchestrator
  embedded_nats_port: 4222
  embedded_nats_host: 0.0.0.0
```

### JetStream Storage

The orchestrator uses JetStream for persistent storage:

```yaml theme={null}
lattice:
  mode: orchestrator
  jetstream:
    # Storage directory for JetStream data
    store_dir: /var/lib/station/jetstream
    # Max storage size (default: 1GB)
    max_store: 1073741824
    # Max memory (default: 256MB)
    max_mem: 268435456
```

### Cluster Mode (High Availability)

For production deployments, run multiple orchestrators in cluster mode:

```yaml title="orchestrator-1.yaml" theme={null}
lattice:
  mode: orchestrator
  cluster:
    enabled: true
    name: station-cluster
    # This node's route address
    host: orchestrator-1.example.com
    port: 6222
    # Other cluster members
    routes:
      - nats://orchestrator-2.example.com:6222
      - nats://orchestrator-3.example.com:6222
```

## Member Configuration

### Basic Setup

```yaml title="member-config.yaml" theme={null}
workspace: /opt/station/member

lattice:
  mode: member
  station_id: sre-station-east
  station_name: SRE Station (US-East)
  nats_urls:
    - nats://orchestrator.example.com:4222
```

### Multiple NATS URLs (Failover)

```yaml theme={null}
lattice:
  mode: member
  nats_urls:
    - nats://orchestrator-1.example.com:4222
    - nats://orchestrator-2.example.com:4222
    - nats://orchestrator-3.example.com:4222
```

### Reconnection Settings

```yaml theme={null}
lattice:
  mode: member
  nats_urls:
    - nats://orchestrator.example.com:4222
  reconnect:
    # Max reconnection attempts (-1 for infinite)
    max_attempts: -1
    # Wait between reconnection attempts
    wait: 2s
    # Max wait time (with jitter)
    max_wait: 30s
```

## Security Configuration

### TLS Encryption

Generate certificates for secure communication:

```bash theme={null}
# Generate CA
openssl genrsa -out ca.key 4096
openssl req -new -x509 -days 365 -key ca.key -out ca.pem \
  -subj "/CN=Station Lattice CA"

# Generate server cert (for orchestrator)
openssl genrsa -out server.key 2048
openssl req -new -key server.key -out server.csr \
  -subj "/CN=orchestrator.example.com"
openssl x509 -req -in server.csr -CA ca.pem -CAkey ca.key \
  -CAcreateserial -out server.pem -days 365

# Generate client cert (for members)
openssl genrsa -out client.key 2048
openssl req -new -key client.key -out client.csr \
  -subj "/CN=member-station"
openssl x509 -req -in client.csr -CA ca.pem -CAkey ca.key \
  -CAcreateserial -out client.pem -days 365
```

Configure TLS on orchestrator:

```yaml title="orchestrator-config.yaml" theme={null}
lattice:
  mode: orchestrator
  tls:
    enabled: true
    cert_file: /etc/station/certs/server.pem
    key_file: /etc/station/certs/server.key
    ca_file: /etc/station/certs/ca.pem
    # Require client certificates
    verify_client: true
```

Configure TLS on member:

```yaml title="member-config.yaml" theme={null}
lattice:
  mode: member
  nats_urls:
    - nats://orchestrator.example.com:4222
  tls:
    enabled: true
    cert_file: /etc/station/certs/client.pem
    key_file: /etc/station/certs/client.key
    ca_file: /etc/station/certs/ca.pem
```

### NKey Authentication

NKeys provide secure, passwordless authentication using Ed25519 keys.

Generate NKey pairs:

```bash theme={null}
# Install nk tool
go install github.com/nats-io/nkeys/nk@latest

# Generate operator key (for orchestrator)
nk -gen operator -pubout > operator.pub
nk -gen operator > operator.seed

# Generate account key
nk -gen account -pubout > account.pub
nk -gen account > account.seed

# Generate user keys (for members)
nk -gen user -pubout > member1.pub
nk -gen user > member1.seed
```

Configure NKey on orchestrator:

```yaml title="orchestrator-config.yaml" theme={null}
lattice:
  mode: orchestrator
  nkey:
    operator_seed: /etc/station/nkeys/operator.seed
    # Allowed user public keys
    authorized_users:
      - UABC123...  # member1.pub content
      - UDEF456...  # member2.pub content
```

Configure NKey on member:

```yaml title="member-config.yaml" theme={null}
lattice:
  mode: member
  nats_urls:
    - nats://orchestrator.example.com:4222
  nkey:
    seed_file: /etc/station/nkeys/member1.seed
```

## Agent Configuration

### Declaring Capabilities

Agents can declare capabilities for routing:

```yaml title="agent.yaml" theme={null}
name: k8s-health-checker
description: Checks Kubernetes cluster health

# Capabilities for lattice routing
capabilities:
  - kubernetes
  - health-check
  - monitoring

# Tags for filtering
tags:
  environment: production
  region: us-east-1
```

### Restricting Remote Access

Control which agents can be invoked remotely:

```yaml title="config.yaml" theme={null}
lattice:
  mode: member
  # Only expose these agents to the mesh
  exposed_agents:
    - k8s-health-checker
    - log-analyzer
  # Or use patterns
  exposed_agent_patterns:
    - "k8s-*"
    - "*-analyzer"
```

## Monitoring

### Health Endpoints

The lattice exposes health information:

```bash theme={null}
# Check lattice status
curl http://localhost:8080/api/v1/lattice/status

# Response:
{
  "mode": "member",
  "connected": true,
  "station_id": "sre-station-east",
  "orchestrator": "nats://orchestrator.example.com:4222",
  "uptime": "2h15m30s",
  "agents_registered": 5
}
```

### Metrics

Lattice exposes Prometheus metrics:

```
# Station presence
station_lattice_heartbeats_total{station_id="sre-station"}
station_lattice_presence_status{station_id="sre-station"}

# Agent invocations
station_lattice_invocations_total{agent="k8s-health",status="success"}
station_lattice_invocation_duration_seconds{agent="k8s-health"}

# Work queue
station_lattice_work_items_total{status="pending"}
station_lattice_work_items_total{status="completed"}
station_lattice_work_duration_seconds{agent="log-analyzer"}
```

## Troubleshooting

### Connection Issues

```bash theme={null}
# Test NATS connectivity
nats server check nats://orchestrator.example.com:4222

# Check station logs
stn serve --lattice nats://host:4222 --log-level debug

# Verify TLS
openssl s_client -connect orchestrator.example.com:4222 \
  -cert client.pem -key client.key -CAfile ca.pem
```

### Common Errors

| Error                       | Cause            | Solution                             |
| --------------------------- | ---------------- | ------------------------------------ |
| `connection refused`        | NATS not running | Start orchestrator first             |
| `authorization violation`   | Invalid NKey     | Check seed file and authorized users |
| `certificate verify failed` | TLS mismatch     | Verify CA chain matches              |
| `station not found`         | Not registered   | Check heartbeat interval             |