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:

CLI flags (highest priority)
Environment variables
Config file (config.yaml)

Config File

Add a lattice section to your config.yaml:

config.yaml

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

# 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

orchestrator-config.yaml

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:

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:

orchestrator-1.yaml

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

member-config.yaml

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)

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

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:

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

orchestrator-config.yaml

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:

member-config.yaml

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:

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

orchestrator-config.yaml

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:

member-config.yaml

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:

agent.yaml

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:

config.yaml

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:

# 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

# 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

Documentation Index

​Lattice Setup & Configuration

​Configuration Methods

​Config File

​Environment Variables

​CLI Flags

​Orchestrator Configuration

​Basic Setup

​JetStream Storage

​Cluster Mode (High Availability)

​Member Configuration

​Basic Setup

​Multiple NATS URLs (Failover)

​Reconnection Settings

​Security Configuration

​TLS Encryption

​NKey Authentication

​Agent Configuration

​Declaring Capabilities

​Restricting Remote Access

​Monitoring

​Health Endpoints

​Metrics

​Troubleshooting

​Connection Issues

​Common Errors

Lattice Setup & Configuration

Configuration Methods

Config File

Environment Variables

CLI Flags

Orchestrator Configuration

Basic Setup

JetStream Storage

Cluster Mode (High Availability)

Member Configuration

Basic Setup

Multiple NATS URLs (Failover)

Reconnection Settings

Security Configuration

TLS Encryption

NKey Authentication

Agent Configuration

Declaring Capabilities

Restricting Remote Access

Monitoring

Health Endpoints

Metrics

Troubleshooting

Connection Issues

Common Errors