Overview

Saturn uses a two-layer architecture for service discovery and communication:

1. Service Discovery Layer

   Services announce themselves using DNS-based Service Discovery (DNS-SD) over multicast DNS (mDNS). This allows zero-configuration discovery on local networks.
2. API Layer

   Services expose HTTP endpoints following OpenAI API conventions. All Saturn services speak the same API format, making them interchangeable.

Service Discovery Protocol

Saturn services register under the following mDNS service type:

_saturn._tcp.local.

Implementation Approaches

There are two primary methods for implementing Saturn service discovery in your application:

1. DNS-SD Command-Based Discovery (Recommended): Use native system commands (dns-sd or avahi-browse) via subprocess calls. This approach works in any programming language and requires no additional libraries. Used by most Saturn servers and clients including servers/ollama_server.py, servers/openrouter_server.py, and clients/local_proxy_client.py.
2. Zeroconf Python Library: Use the Python zeroconf library for pure-Python implementation. Provides cleaner API but requires installing a dependency. Used by servers/fallback_server.py and clients/file_upload_client.py.

This section focuses on the DNS-SD command-based approach. For the zeroconf library approach, visit the Zeroconf Library section of these docs..

DNS-SD Command Reference

Cross-Platform Commands

Different operating systems provide different tools for DNS-SD operations:

Discovery Process

Step 1: Browse for Services

Send an mDNS query for PTR records to find available services:

# Browse for services (continues until interrupted)
dns-sd -B _saturn._tcp local

# Browse with full resolution
avahi-browse -r _saturn._tcp

# Parseable output
avahi-browse -rpt _saturn._tcp

Example response (dns-sd):

Browsing for _saturn._tcp.local.
DATE: ---Sat 18 Nov 2024---
Timestamp     A/R    Flags  if Domain    Service Type    Instance Name
10:30:00.000  Add        2   4 local.    _saturn._tcp.   OpenRouter
10:30:00.100  Add        2   4 local.    _saturn._tcp.   Ollama

Step 2: Resolve Service Details

For each discovered service, query for SRV and TXT records to get connection details:

dns-sd -L "OpenRouter" _saturn._tcp local

Example response:

Lookup OpenRouter._saturn._tcp.local.
DATE: ---Sat 18 Nov 2024---
OpenRouter._saturn._tcp.local. can be reached at DESKTOP-ABC.local.:8080
 priority=10 version=1.0 api=OpenRouter

Step 3: Resolve Host Address

The hostname from Step 2 (e.g., DESKTOP-ABC.local.) needs to be resolved to an IP address. This is typically done automatically using your system's DNS resolver (socket.gethostbyname() in most languages).

DESKTOP-ABC.local. has address 192.168.1.100

Implementing Discovery in Your Application

Below are basic examples showing how to implement Saturn service discovery using subprocess calls to DNS-SD commands. These snippets demonstrate the core pattern used in Saturn's own clients and servers.

Python Implementation

This example shows the subprocess-based approach used by clients/local_proxy_client.py:

import subprocess
import time
import re
import socket

def discover_saturn_services():
    """Discover all Saturn services on the local network."""
    services = []

    # Start browsing for services
    browse_proc = subprocess.Popen(
        ['dns-sd', '-B', '_saturn._tcp', 'local'],
        stdout=subprocess.PIPE,
        stderr=subprocess.PIPE,
        text=True
    )

    # Let it run for 2 seconds to collect responses
    time.sleep(2.0)
    browse_proc.terminate()
    stdout, _ = browse_proc.communicate(timeout=1)

    # Parse service names from output
    service_names = []
    for line in stdout.split('\n'):
        if 'Add' in line and '_saturn._tcp' in line:
            parts = line.split()
            if len(parts) > 6:
                service_names.append(parts[6])

    # Resolve each service to get details
    for service_name in service_names:
        lookup_proc = subprocess.Popen(
            ['dns-sd', '-L', service_name, '_saturn._tcp', 'local'],
            stdout=subprocess.PIPE,
            stderr=subprocess.PIPE,
            text=True
        )

        time.sleep(1.5)
        lookup_proc.terminate()
        stdout, _ = lookup_proc.communicate(timeout=2)

        hostname = None
        port = None
        priority = 50  # default

        # Parse hostname and port
        for line in stdout.split('\n'):
            if 'can be reached at' in line:
                match = re.search(r'can be reached at (.+):(\d+)', line)
                if match:
                    hostname = match.group(1).rstrip('.')
                    port = int(match.group(2))

            # Parse priority from TXT record
            if 'priority=' in line:
                parts = line.split('priority=')
                if len(parts) > 1:
                    priority_str = parts[1].split()[0]
                    priority = int(priority_str)

        if hostname and port:
            # Resolve hostname to IP address
            try:
                ip_address = socket.gethostbyname(hostname)
            except socket.gaierror:
                ip_address = hostname

            services.append({
                'name': service_name,
                'address': ip_address,
                'port': port,
                'priority': priority,
                'url': f"http://{ip_address}:{port}"
            })

    # Sort by priority (lowest first)
    services.sort(key=lambda s: s['priority'])
    return services

# Example usage
if __name__ == "__main__":
    services = discover_saturn_services()
    for service in services:
        print(f"{service['name']}: {service['url']} (priority: {service['priority']})")

TypeScript/Node.js Implementation

Basic service discovery using Node.js child processes:

import { spawn } from 'child_process';
import { promisify } from 'util';

interface SaturnService {
  name: string;
  address: string;
  port: number;
  priority: number;
  url: string;
}

async function discoverSaturnServices(): Promise<SaturnService[]> {
  const services: SaturnService[] = [];

  // Browse for services
  const browseProc = spawn('dns-sd', ['-B', '_saturn._tcp', 'local']);
  let browseOutput = '';

  browseProc.stdout.on('data', (data) => {
    browseOutput += data.toString();
  });

  // Wait 2 seconds for responses
  await new Promise(resolve => setTimeout(resolve, 2000));
  browseProc.kill();

  // Parse service names
  const serviceNames: string[] = [];
  const lines = browseOutput.split('\n');

  for (const line of lines) {
    if (line.includes('Add') && line.includes('_saturn._tcp')) {
      const parts = line.split(/\s+/);
      if (parts.length > 6) {
        serviceNames.push(parts[6]);
      }
    }
  }

  // Resolve each service
  for (const serviceName of serviceNames) {
    const lookupProc = spawn('dns-sd', [
      '-L', serviceName, '_saturn._tcp', 'local'
    ]);

    let lookupOutput = '';
    lookupProc.stdout.on('data', (data) => {
      lookupOutput += data.toString();
    });

    await new Promise(resolve => setTimeout(resolve, 1500));
    lookupProc.kill();

    // Parse connection details
    let hostname: string | null = null;
    let port: number | null = null;
    let priority = 50;

    const lookupLines = lookupOutput.split('\n');
    for (const line of lookupLines) {
      const reachMatch = line.match(/can be reached at (.+):(\d+)/);
      if (reachMatch) {
        hostname = reachMatch[1].replace(/\.$/, '');
        port = parseInt(reachMatch[2]);
      }

      if (line.includes('priority=')) {
        const priorityMatch = line.match(/priority=(\d+)/);
        if (priorityMatch) {
          priority = parseInt(priorityMatch[1]);
        }
      }
    }

    if (hostname && port) {
      services.push({
        name: serviceName,
        address: hostname,
        port,
        priority,
        url: `http://${hostname}:${port}`
      });
    }
  }

  // Sort by priority
  services.sort((a, b) => a.priority - b.priority);
  return services;
}

// Example usage
discoverSaturnServices().then(services => {
  services.forEach(service => {
    console.log(`${service.name}: ${service.url} (priority: ${service.priority})`);
  });
});

Go Implementation

Basic service discovery using Go's exec package:

package main

import (
    "bufio"
    "context"
    "fmt"
    "os/exec"
    "regexp"
    "sort"
    "strconv"
    "strings"
    "time"
)

type SaturnService struct {
    Name     string
    Address  string
    Port     int
    Priority int
    URL      string
}

func discoverSaturnServices() ([]SaturnService, error) {
    var services []SaturnService

    // Create context with timeout for browse command
    ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
    defer cancel()

    // Browse for services
    cmd := exec.CommandContext(ctx, "dns-sd", "-B", "_saturn._tcp", "local")
    output, _ := cmd.Output()

    // Parse service names
    serviceNames := []string{}
    scanner := bufio.NewScanner(strings.NewReader(string(output)))

    for scanner.Scan() {
        line := scanner.Text()
        if strings.Contains(line, "Add") && strings.Contains(line, "_saturn._tcp") {
            parts := strings.Fields(line)
            if len(parts) > 6 {
                serviceNames = append(serviceNames, parts[6])
            }
        }
    }

    // Resolve each service
    for _, serviceName := range serviceNames {
        ctx2, cancel2 := context.WithTimeout(context.Background(), 2*time.Second)
        defer cancel2()

        cmd2 := exec.CommandContext(ctx2, "dns-sd", "-L", serviceName, "_saturn._tcp", "local")
        output2, _ := cmd2.Output()

        var hostname string
        var port int
        priority := 50

        scanner2 := bufio.NewScanner(strings.NewReader(string(output2)))
        reachRegex := regexp.MustCompile(`can be reached at (.+):(\d+)`)
        priorityRegex := regexp.MustCompile(`priority=(\d+)`)

        for scanner2.Scan() {
            line := scanner2.Text()

            // Parse hostname and port
            if matches := reachRegex.FindStringSubmatch(line); matches != nil {
                hostname = strings.TrimSuffix(matches[1], ".")
                port, _ = strconv.Atoi(matches[2])
            }

            // Parse priority
            if matches := priorityRegex.FindStringSubmatch(line); matches != nil {
                priority, _ = strconv.Atoi(matches[1])
            }
        }

        if hostname != "" && port > 0 {
            services = append(services, SaturnService{
                Name:     serviceName,
                Address:  hostname,
                Port:     port,
                Priority: priority,
                URL:      fmt.Sprintf("http://%s:%d", hostname, port),
            })
        }
    }

    // Sort by priority
    sort.Slice(services, func(i, j int) bool {
        return services[i].Priority < services[j].Priority
    })

    return services, nil
}

func main() {
    services, err := discoverSaturnServices()
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }

    for _, service := range services {
        fmt.Printf("%s: %s (priority: %d)\n",
            service.Name, service.URL, service.Priority)
    }
}

Service Registration

To make your AI service discoverable on the network, you need to register it using DNS-SD. This announces your service to all devices on the local network so clients can automatically find and connect to it.

Registration with DNS-SD Commands

The simplest way to register a Saturn service is using the dns-sd -R command. This works on macOS and Windows (with Bonjour installed).

Basic Registration

Register a service with a single command:

# Register a Saturn service
dns-sd -R "OpenRouter" "_saturn._tcp" "local" 8081 "version=1.0" "api=OpenRouter" "priority=50"

This command does the following:

• -R: Register a service
• "OpenRouter": Service name (appears to clients)
• "_saturn._tcp": Service type (must be exactly this for Saturn)
• "local": Domain (always "local" for local network)
• 8081: Port number where your service listens
• "version=1.0": Version property in TXT record
• "api=OpenRouter": API type property
• "priority=50": Priority for service selection

Registration on Linux (Avahi)

On Linux systems, use the avahi-publish command instead:

# Register with avahi-publish
avahi-publish -s "OpenRouter" _saturn._tcp 8081 "version=1.0" "api=OpenRouter" "priority=50"

Registration in Application Code

For production servers, you'll want to register the service programmatically. Here's how Saturn's servers do it:

Python Implementation (subprocess)

This example shows the pattern used in servers/openrouter_server.py and servers/ollama_server.py:

import subprocess
import socket

def register_saturn_service(
    service_name: str,
    port: int,
    priority: int = 50,
    api_type: str = "Generic",
    version: str = "1.0",
    features: str = None
) -> subprocess.Popen:
    """
    Register a Saturn service using dns-sd.
    Returns the subprocess Popen object - keep it running!
    """

    # Build the registration command
    cmd = [
        'dns-sd', '-R',
        service_name,
        '_saturn._tcp',
        'local',
        str(port),
        f'version={version}',
        f'api={api_type}',
        f'priority={priority}'
    ]

    # Add optional features
    if features:
        cmd.append(f'features={features}')

    try:
        # Start the registration process
        proc = subprocess.Popen(
            cmd,
            stdout=subprocess.PIPE,
            stderr=subprocess.PIPE,
            text=True
        )

        print(f"Registered '{service_name}' on port {port} with priority {priority}")
        return proc

    except FileNotFoundError:
        print("ERROR: dns-sd not found. Install Bonjour services.")
        return None

# Example usage
if __name__ == "__main__":
    # Register the service
    registration_proc = register_saturn_service(
        service_name="MyAIService",
        port=8080,
        priority=10,
        api_type="OpenRouter",
        features="multimodal,streaming"
    )

    try:
        # Your HTTP server runs here...
        # uvicorn.run(app, host="0.0.0.0", port=8080)
        input("Press Enter to stop...")
    finally:
        # Clean shutdown
        if registration_proc:
            print("Unregistering service...")
            registration_proc.terminate()
            registration_proc.wait(timeout=2)

Shell Script Registration

For quick testing or scripting, you can register directly from the command line:

#!/bin/bash

# Register Saturn service in background
dns-sd -R "MyService" "_saturn._tcp" "local" 8080 \
    "version=1.0" \
    "api=Custom" \
    "priority=50" &

# Store the PID so we can kill it later
DNS_SD_PID=$!

# Cleanup function
cleanup() {
    echo "Unregistering service..."
    kill $DNS_SD_PID
    exit 0
}

# Register cleanup on script exit
trap cleanup SIGINT SIGTERM

# Start your HTTP server
echo "Service registered. Starting server..."
python -m http.server 8080

Registration Properties

When registering your service, include these TXT record properties:

Testing Your Registration

After registering your service, verify it's discoverable:

# Browse for all Saturn services
dns-sd -B _saturn._tcp local

# You should see your service appear in the output
# Example output:
# Browsing for _saturn._tcp.local.
# Timestamp     A/R Flags if Domain    Service Type    Instance Name
# 10:30:00.000  Add     2  4 local.    _saturn._tcp.   MyService

Then resolve the service to see its details:

# Look up your specific service
dns-sd -L "MyService" _saturn._tcp local

# You should see the connection details and TXT records:
# MyService._saturn._tcp.local. can be reached at hostname.local.:8080
#  version=1.0 api=Custom priority=50

Client Discovery with Zeroconf Library

As an alternative to subprocess-based DNS-SD commands, clients can use the Python zeroconf library for a pure-Python implementation. This approach provides a cleaner API and better event handling but requires installing an additional dependency.

When to Use This Approach

• Python-only projects: If you're building in Python and don't mind the dependency
• Cleaner API: The library provides a more Pythonic interface than parsing subprocess output
• Event-driven discovery: Built-in support for continuous monitoring with callbacks
• Cross-platform without external commands: Works consistently across platforms without requiring dns-sd or avahi-browse

Installation

pip install zeroconf

Service Discovery with Zeroconf

This example is based on clients/file_upload_client.py:

from zeroconf import ServiceBrowser, ServiceListener, Zeroconf
import socket
import time

class SaturnServiceListener(ServiceListener):
    def __init__(self):
        self.services = {}

    def add_service(self, zc: Zeroconf, type_: str, name: str) -> None:
        """Called when a new service is discovered"""
        info = zc.get_service_info(type_, name)
        if not info:
            return

        # Extract service details
        address = socket.inet_ntoa(info.addresses[0])
        port = info.port

        # Parse priority from TXT record
        priority = 50  # default
        if info.properties:
            priority_bytes = info.properties.get(b'priority')
            if priority_bytes:
                try:
                    priority = int(priority_bytes.decode('utf-8'))
                except (ValueError, UnicodeDecodeError):
                    pass

        # Clean up service name
        clean_name = name.replace('._saturn._tcp.local.', '')

        self.services[clean_name] = {
            'name': clean_name,
            'address': address,
            'port': port,
            'priority': priority,
            'url': f"http://{address}:{port}"
        }

        print(f"Discovered: {clean_name} at {address}:{port} (priority: {priority})")

    def remove_service(self, zc: Zeroconf, type_: str, name: str) -> None:
        """Called when a service disappears"""
        clean_name = name.replace('._saturn._tcp.local.', '')
        if clean_name in self.services:
            del self.services[clean_name]
            print(f"Service removed: {clean_name}")

    def update_service(self, zc: Zeroconf, type_: str, name: str) -> None:
        """Called when service information changes"""
        self.add_service(zc, type_, name)

    def get_best_service(self):
        """Get the service with lowest priority"""
        if not self.services:
            return None
        return min(self.services.values(), key=lambda s: s['priority'])

# Example usage
if __name__ == "__main__":
    zeroconf = Zeroconf()
    listener = SaturnServiceListener()

    # Start browsing for services
    browser = ServiceBrowser(zeroconf, "_saturn._tcp.local.", listener)

    try:
        # Wait for services to be discovered
        print("Searching for Saturn services...")
        time.sleep(3)

        # Get the best service
        best = listener.get_best_service()
        if best:
            print(f"\nBest service: {best['name']} at {best['url']}")
        else:
            print("No services found")

        # Keep running to monitor for changes
        input("Press Enter to stop...\n")

    finally:
        browser.cancel()
        zeroconf.close()

Comparison: DNS-SD Commands vs Zeroconf Library (Discovery)

Server Registration with Zeroconf Library

As an alternative to subprocess-based DNS-SD commands, servers can use the Python zeroconf library to register services. This provides a cleaner API but requires installing an additional dependency.

When to Use This Approach

• Python-only servers: If you're building a server in Python and don't mind the dependency
• Cleaner API: The library provides a more Pythonic interface than managing subprocess lifetimes
• Cross-platform without external commands: Works consistently across platforms without requiring dns-sd or avahi-publish
• Programmatic control: Easier to start/stop registration dynamically

Installation

pip install zeroconf

Service Registration with Zeroconf

This example shows how to announce a Saturn service, based on servers/fallback_server.py:

from zeroconf import ServiceInfo, Zeroconf
import socket

def register_saturn_service(port: int, priority: int = 50, service_name: str = "MyService"):
    """Register a Saturn service on the network"""
    zeroconf = Zeroconf()

    # Get local IP address
    hostname = socket.gethostname()
    host_ip = socket.gethostbyname(hostname)

    # Create service info
    service_type = "_saturn._tcp.local."
    full_name = f"{service_name}.{service_type}"

    info = ServiceInfo(
        type_=service_type,
        name=full_name,
        port=port,
        addresses=[socket.inet_aton(host_ip)],
        server=f"{hostname}.local.",
        properties={
            'version': '1.0',
            'api': 'MyAPI',
            'priority': str(priority)
        },
        priority=priority
    )

    # Register the service
    zeroconf.register_service(info)
    print(f"Registered {service_name} on port {port} with priority {priority}")

    return zeroconf, info

# Example usage
if __name__ == "__main__":
    zc, info = register_saturn_service(port=8080, priority=10, service_name="TestServer")

    try:
        input("Service registered. Press Enter to stop...\n")
    finally:
        zeroconf.unregister_service(info)
        zeroconf.close()
        print("Service unregistered")

Integration with FastAPI/Flask

For production servers using FastAPI or Flask, integrate registration into the application lifecycle:

from fastapi import FastAPI
from contextlib import asynccontextmanager
from zeroconf import ServiceInfo, Zeroconf
import socket

# Global variables for cleanup
zeroconf_instance = None
service_info = None

@asynccontextmanager
async def lifespan(app: FastAPI):
    """Manage service registration during app lifecycle"""
    global zeroconf_instance, service_info

    # Startup: Register service
    print("Registering Saturn service...")
    zeroconf_instance = Zeroconf()

    hostname = socket.gethostname()
    host_ip = socket.gethostbyname(hostname)

    service_info = ServiceInfo(
        type_="_saturn._tcp.local.",
        name=f"MyAIService._saturn._tcp.local.",
        port=8080,
        addresses=[socket.inet_aton(host_ip)],
        server=f"{hostname}.local.",
        properties={
            'version': '1.0',
            'api': 'Custom',
            'priority': '10'
        }
    )

    zeroconf_instance.register_service(service_info)
    print("Service registered!")

    yield

    # Shutdown: Unregister service
    print("Unregistering service...")
    if zeroconf_instance and service_info:
        zeroconf_instance.unregister_service(service_info)
        zeroconf_instance.close()
    print("Service unregistered")

app = FastAPI(lifespan=lifespan)

@app.get("/v1/health")
async def health():
    return {"status": "ok"}

Comparison: DNS-SD Commands vs Zeroconf Library (Registration)

Service Properties

Each service advertises these properties in its TXT record:

Service Selection Algorithm

When multiple services are discovered:

1. Parse the priority property from each service's TXT record
2. Sort services by priority in ascending order (lower values first)
3. Connect to the service with the lowest priority number
4. On connection failure, try the next service in priority order

Priority Guidelines

The default priority is 50. Lower numbers indicate higher preference. Clients select the service with the lowest priority number.

API Endpoints

All Saturn services implement these required endpoints:

Health Check

curl http://192.168.1.100:8080/v1/health

{
  "status": "ok",
  "provider": "OpenRouter",
  "models_cached": 344,
  "features": ["multimodal", "auto-routing", "full-catalog"]
}

List Models

curl http://192.168.1.100:8080/v1/models

{
  "models": [
    {
      "id": "openrouter/auto",
      "object": "model",
      "owned_by": "openrouter"
    },
    {
      "id": "anthropic/claude-3-opus",
      "object": "model",
      "owned_by": "anthropic",
      "context_length": 200000
    }
  ]
}

Chat Completions

Send messages and receive AI responses.

Request Format

curl -X POST http://192.168.1.100:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-3-opus",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "Hello!"
      }
    ],
    "max_tokens": 1024,
    "stream": false
  }'

Request Parameters

Message Roles

Response Format

{
  "id": "chatcmpl-1699900000",
  "object": "chat.completion",
  "created": 1699900000,
  "model": "anthropic/claude-3-opus",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 18,
    "total_tokens": 43
  }
}

Streaming Responses

For real-time responses, set stream: true in the request. The response uses Server-Sent Events (SSE).

curl -X POST http://192.168.1.100:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -N \
  -d '{
    "model": "anthropic/claude-3-opus",
    "messages": [
      {"role": "user", "content": "Count to 5"}
    ],
    "stream": true
  }'

Streaming Response Format

Each chunk is prefixed with data: and followed by two newlines:

# First chunk (role announcement)
data: {"id":"chatcmpl-1699900000","object":"chat.completion.chunk","created":1699900000,"model":"anthropic/claude-3-opus","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

# Content chunks
data: {"id":"chatcmpl-1699900000","object":"chat.completion.chunk","created":1699900000,"model":"anthropic/claude-3-opus","choices":[{"index":0,"delta":{"content":"1, "},"finish_reason":null}]}

data: {"id":"chatcmpl-1699900000","object":"chat.completion.chunk","created":1699900000,"model":"anthropic/claude-3-opus","choices":[{"index":0,"delta":{"content":"2, "},"finish_reason":null}]}

# Final chunk
data: {"id":"chatcmpl-1699900000","object":"chat.completion.chunk","created":1699900000,"model":"anthropic/claude-3-opus","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

Required Headers for Streaming

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
X-Accel-Buffering: no

Error Handling

All errors return a JSON response with a detail field:

{
  "detail": "Error description here"
}

HTTP Status Codes

Shell Script Examples

Service Discovery Script

Discover Saturn services on the network and extract connection details:

#!/bin/bash

# Find Saturn services (runs for 3 seconds)
echo "Discovering Saturn services..."
timeout 3 dns-sd -B _saturn._tcp local. 2>/dev/null | grep Add | while read line; do
    SERVICE=$(echo "$line" | awk '{print $NF}')
    echo "Found: $SERVICE"

    # Resolve service details
    dns-sd -L "$SERVICE" _saturn._tcp local. 2>/dev/null | head -2 | tail -1
done

#!/bin/bash

# Find Saturn services and resolve their addresses
echo "Discovering Saturn services..."
avahi-browse -rpt _saturn._tcp 2>/dev/null | grep "^=" | while IFS=';' read _ _ _ name _ _ host ip port txt; do
    echo "Service: $name"
    echo "  Address: $ip:$port"
    echo "  Properties: $txt"
done

Complete Discovery and Chat Script

#!/bin/bash

# Configuration
SERVER="http://127.0.0.1:8080"
MODEL="openrouter/auto"

# Check health
echo "Checking server health..."
curl -s "$SERVER/v1/health" | python3 -m json.tool

# List available models
echo "\nAvailable models:"
curl -s "$SERVER/v1/models" | python3 -c "
import sys, json
data = json.load(sys.stdin)
for model in data['models']:
    print(f\"  - {model['id']}\")
"

# Make a chat request
echo "\nSending chat request..."
curl -s -X POST "$SERVER/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$MODEL"'",
    "messages": [
      {"role": "user", "content": "What is 2+2?"}
    ]
  }' | python3 -c "
import sys, json
data = json.load(sys.stdin)
print(data['choices'][0]['message']['content'])
"

Multi-turn Conversation

#!/bin/bash

SERVER="http://127.0.0.1:8080/v1"
MODEL="openrouter/auto"

# First turn
RESPONSE=$(curl -s -X POST "$SERVER/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$MODEL"'",
    "messages": [
      {"role": "user", "content": "My name is Alice."}
    ]
  }')

ASSISTANT_MSG=$(echo "$RESPONSE" | python3 -c "
import sys, json
print(json.load(sys.stdin)['choices'][0]['message']['content'])
")

echo "Assistant: $ASSISTANT_MSG"

# Second turn with history
curl -s -X POST "$SERVER/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$MODEL"'",
    "messages": [
      {"role": "user", "content": "My name is Alice."},
      {"role": "assistant", "content": "'"$ASSISTANT_MSG"'"},
      {"role": "user", "content": "What is my name?"}
    ]
  }' | python3 -c "
import sys, json
print('Assistant:', json.load(sys.stdin)['choices'][0]['message']['content'])
"

Streaming Output

#!/bin/bash

SERVER="http://127.0.0.1:8080/v1"
MESSAGE="Tell me a short story"

curl -s -N -X POST "$SERVER/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openrouter/auto",
    "messages": [
      {"role": "user", "content": "'"$MESSAGE"'"}
    ],
    "stream": true
  }' | while read -r line; do
    if [[ "$line" == data:* ]] && [[ "$line" != "data: [DONE]" ]]; then
        content=$(echo "${line#data: }" | python3 -c "
import sys, json
try:
    data = json.load(sys.stdin)
    content = data.get('choices', [{}])[0].get('delta', {}).get('content', '')
    print(content, end='')
except: pass
")
        echo -n "$content"
    fi
done
echo

Integration Philosophy

Saturn is designed to be an integration-friendly platform that works seamlessly with existing tools and workflows. Rather than forcing you to adopt new interfaces, Saturn brings AI capabilities to the applications you already use through two primary integration approaches:

Why Integrate with Saturn?

• Automatic Service Discovery: No manual configuration of endpoints or API keys for each service
• Unified Access: Access all Saturn network services through a single integration point
• Automatic Failover: Requests automatically route to healthy services if one becomes unavailable
• Priority-Based Routing: Services can advertise priority levels for intelligent request routing
• Context-Aware: Integrations can leverage application-specific context (like media metadata) for more relevant AI responses
• Zero-Configuration: mDNS-based discovery means services are found automatically on your network

Available Integrations

Saturn currently provides the following integrations, with more planned for the future:

VLC Extensions: Shared Architecture

Both Saturn VLC extensions (Roast and Chat) share the same underlying architecture, making them reliable, portable, and zero-configuration solutions for bringing AI capabilities to VLC Media Player.

How It Works

1. Extension Activation

   When you activate either extension in VLC (View → Extensions), the Lua script automatically detects your operating system and launches the appropriate bundled bridge executable.
2. Bridge Initialization

   The bridge starts an HTTP server and begins discovering Saturn services via mDNS. It writes connection information to a temporary port file, allowing the Lua extension to connect.
3. Service Discovery

   The bridge continuously discovers Saturn AI services broadcasting on _saturn._tcp.local, monitors their health, and maintains a list of available models.
4. Extension Connection

   The Lua extension connects to the bridge using retry logic (up to 7 attempts with exponential backoff), retrieves available services, and presents them in the UI.

Key Components

• Lua Extensions: saturn_roast.lua and saturn_chat.lua provide the user interface and media context extraction
• Discovery Bridge: vlc_discovery_bridge.py (bundled as executable) handles mDNS service discovery and HTTP routing
• Bridge Executables: Pre-built for Windows (.exe), macOS, and Linux - no Python installation required
• Port File System: Temporary file-based communication for dynamic port discovery

VLC Roast Extension

The Saturn Roast extension brings entertainment to VLC Media Player by providing AI-generated roasts based on your media taste. It analyzes what you're currently watching or listening to and delivers comments about your media choices.

How to Use

1. Play any media in VLC (music, video, podcast, etc.)
2. Activate the extension: View → Extensions → Saturn Roast Extension
3. Wait for the bridge to connect and discover Saturn services
4. Select a service and model (or use Auto mode)
5. Click the 🔥 Roast Me! 🔥 button

Example Roasts

Installation - Roast Extension

The Roast extension shares the same installation process as the Chat extension. Both extensions are included in the vlc_extension folder and use the same discovery bridge.

Quick Install

1. Download

   Get the vlc_extension folder from the Saturn repository: VLC Extension Repository
2. Copy to VLC

   Copy the entire folder to your VLC extensions directory:
   
   Windows: %APPDATA%\vlc\lua\extensions\
   macOS: ~/Library/Application Support/org.videolan.vlc/lua/extensions/
   Linux: ~/.local/share/vlc/lua/extensions/
3. Restart VLC

   Restart VLC to load the extension
4. Activate

   Go to View → Extensions → Saturn Roast Extension

Using the Roast Extension

Getting Roasted

1. Make sure media is playing in VLC
2. Select a service and model (or leave on Auto)
3. Click 🔥 Roast Me! 🔥
4. Watch the "Thinking..." message appear
5. Enjoy your roast in the styled verdict display

Tips for Better Roasts

• Metadata Matters: Media with complete metadata (artist, album, genre) generates more personalized roasts
• Try Different Models: Different AI models have different comedy styles - experiment to find your favorite
• Context is Key: The AI sees what you're playing, so the more interesting your media choice, the funnier the roast
• Embrace the Chaos: Play something unusual or embarrassing for the best results

VLC Chat Extension

The Saturn Chat extension provides an interactive conversational AI assistant directly within VLC Media Player. Unlike the entertainment-focused Roast extension, Chat is designed for productive, informative interactions about your media content. The AI assistant is aware of what you're watching or listening to and can answer questions, provide context, and help you understand your media better.

What Makes It Special

• Context-Aware Conversations: The AI knows what you're playing and can reference it in responses
• Full Chat History: Maintains conversation history with color-coded messages for easy reading
• Educational & Informative: Perfect for learning about music, films, podcasts, or educational content
• Multi-turn Discussions: Build on previous messages to have natural, flowing conversations
• Playback Position Tracking: Records when conversations started for temporal context
• Flexible System Prompt: Configured to be helpful and focused on media intelligence

How to Use

1. Play any media in VLC (music, video, podcast, educational content, etc.)
2. Activate the extension: View → Extensions → Saturn VLC Extension
3. Wait for the "Saturn Chat - Media Intelligence" window to appear and connect
4. Select a service and model (or use Auto mode for automatic routing)
5. Type your question or comment in the message input
6. Click Send and watch the AI respond with context-aware information

Installation - Chat Extension

What's Included

The VLC extension comes bundled with everything needed and no additional software installation required:

• saturn_chat.lua — The VLC Lua extension (UI and logic)
• bridge/vlc_discovery_bridge.exe — Windows bridge executable
• bridge/vlc_discovery_bridge — Linux/macOS bridge executable

Installation Steps

1. Download the Extension

   Download the vlc_extension folder from the Saturn repository.
2. Copy to VLC Extensions Directory

   Copy the entire folder to your VLC extensions location:
   
   Windows: %APPDATA%\vlc\lua\extensions\
   macOS: ~/Library/Application Support/org.videolan.vlc/lua/extensions/
   Linux: ~/.local/share/vlc/lua/extensions/
3. Restart VLC

   If VLC was already running, restart it to load the extension.

Manual Copy

xcopy /E /I vlc_extension "%APPDATA%\vlc\lua\extensions\vlc_extension"

Verifying Installation

1. Open VLC (restart if already running)
2. Go to View → Extensions
3. You should see Saturn VLC Extension in the list

Download

Download the Saturn VLC extension from the repository:

Using the Extension

Activating Saturn Chat

1. Open VLC and play some media (music, video, podcast, etc.)
2. Go to View → Extensions → Saturn VLC Extension
3. The "Saturn Chat - Media Intelligence" window will open and automatically:
   • Launch the bundled discovery bridge executable
   • Wait for the bridge to initialize (uses port file for discovery)
   • Search for Saturn services via mDNS
   • Connect with retry logic (up to 7 attempts with exponential backoff)

Starting a Conversation

1. Wait for the status to show "Connected - X service(s) available"
2. Select a service from the dropdown and click Select (or leave on Auto)
3. Select a model from the model dropdown and click Select
4. Type your message in the input box
5. Click Send

The AI response incorporates media context including the current file name, playback position, duration, and any available metadata (artist, album, genre). The system prompt tells the AI it's integrated into VLC Media Player and can help with questions about the user's media.

Clearing the Chat

Click Clear Chat to reset conversation history. This clears all messages and resets the stored playback position context.

Deactivating

Close the extension window or select View → Extensions → Saturn VLC Extension again. The extension sends a POST request to the bridge's /shutdown endpoint and cleans up the port file from the temp directory.

Troubleshooting

[Saturn] Extension activated
[Saturn] OS detected: windows
[Saturn] Extension dir: C:\...\vlc_extension\
[Saturn] Launching bridge: C:\...\bridge\vlc_discovery_bridge.exe
[Saturn] Port file: C:\Users\...\AppData\Local\Temp\vlc_bridge_port.txt
[Saturn] Bridge process launched
[Saturn] Port file found: http://127.0.0.1:9876
[Saturn] Waiting for server to fully initialize...
[Saturn] Bridge should be ready
[Saturn] Health check attempt 1/7
[Saturn] Bridge connection successful!

Jan AI Client Integration

Jan is an open-source desktop application that provides a privacy-focused alternative to ChatGPT. It allows users to download and run large language models entirely offline on their local machines, while also supporting cloud integrations with providers like OpenAI and Anthropic. Saturn integrates with Jan through the local proxy client, turning Jan's polished interface into a front-end for all Saturn services discovered on your network.

Why Use Jan with Saturn?

• Unified Interface: Access all Saturn network services through Jan's clean, user-friendly chat interface
• Automatic Discovery: No need to manually configure connection endpoints - Saturn handles service discovery
• Flexible Routing: Saturn automatically routes requests to the best available service based on priority
• Failover Support: If one Saturn service goes down, requests seamlessly route to backup services
• Model Aggregation: See all models from all Saturn services in one unified list
• Privacy First: Keep your AI conversations on your local network while enjoying Jan's excellent UX

Setting Up Jan with Saturn

Prerequisites

• At least one Saturn server running on your network (OpenRouter or Ollama)
• Jan desktop application installed on your computer
• Python 3.7+ installed for running the local proxy client

Installation Steps

1. Download Jan

   Visit jan.ai and download the desktop application for your platform (Windows, macOS, or Linux). Install and launch Jan.
2. Start a Saturn Server

   If you haven't already, start at least one Saturn server on your network. For example:

   cd servers/
   python openrouter_server.py

3. Start the Local Proxy Client

   The local proxy client discovers Saturn services and exposes them via an OpenAI-compatible API:

   cd clients/
   python local_proxy_client.py

   The proxy will start on http://127.0.0.1:8080 by default and begin discovering Saturn services.
4. Configure Jan

   In Jan, you need to add Saturn as a remote endpoint:

   1. Open Jan and go to Settings (gear icon in top-right)
   2. Navigate to Model Providers or Remote Models section
   3. Add a new OpenAI-Compatible endpoint
   4. Set the Base URL to: http://127.0.0.1:8080/v1
   5. Leave the API Key field empty or enter any placeholder text (not required)
   6. Save the configuration

Using Jan with Saturn

Selecting Models

Once configured, Jan will show all models available from all Saturn services on your network. The local proxy aggregates models from every discovered Saturn server, presenting them as a unified list.

1. In Jan's main interface, look for the model selector (usually in the top bar or sidebar)
2. You should see models from all your Saturn services listed together
3. Select any model to start chatting
4. Jan will send requests through the Saturn local proxy, which routes them to the appropriate service

How Routing Works

When you send a message in Jan:

1. Request Sent to Proxy

   Jan sends your chat request to the local proxy at http://127.0.0.1:8080/v1
2. Service Discovery

   The proxy identifies which Saturn service hosts the selected model
3. Request Forwarding

   The proxy forwards your request to the appropriate Saturn service
4. Response Return

   The AI response flows back through the proxy to Jan's interface

Verifying the Integration

To confirm Jan is successfully connected to Saturn:

• Check Models: You should see models from your Saturn services in Jan's model list
• Check Proxy Logs: The local proxy client logs all incoming requests and service routing
• Send Test Message: Try chatting with a Saturn-provided model and verify you get responses

[INFO] Local proxy starting on http://127.0.0.1:8080
[INFO] Discovered service: OpenRouter at http://192.168.1.100:8000 (priority=50)
[INFO] Available models: gpt-4, claude-3-opus, llama-3-70b
[INFO] Routing request for model 'gpt-4' to OpenRouter service
[INFO] Request completed successfully

Benefits of This Integration

Open WebUI Integration

Open WebUI is a self-hosted, feature-rich web interface for AI chat that supports multiple model providers through extensible functions (similar to plugins). Saturn integrates with Open WebUI through a custom function that uses DNS-SD service discovery to automatically find and connect to AI services on your local network.

Why Use Open WebUI with Saturn?

• Modern Web Interface: Access Saturn services through Open WebUI's responsive, browser-based chat interface
• Zero-Configuration Discovery: The Saturn function automatically discovers all network services without manual endpoint configuration
• Model Aggregation: See all models from all Saturn services in a single unified list
• Automatic Failover: Built-in support for failing over to backup services when primary services are unavailable
• Flexible Deployment: Run as a desktop app or self-hosted web server
• Streaming Support: Full support for streaming responses with real-time token generation

Installation Options

Open WebUI can be installed in two ways. Both support the Saturn function integration - choose based on your deployment preference.

Option 1: Desktop Application (Recommended for Personal Use)

The desktop app provides a standalone application with built-in server, ideal for individual users.

Option 2: Server Installation (Recommended for Network Sharing)

The server installation runs as a web application, allowing multiple users to access Open WebUI from their browsers.

Installing the Saturn Function

Once you have Open WebUI installed (either desktop or server), you need to add the Saturn function to enable service discovery.

Prerequisites

• Open WebUI desktop app or server installed and running
• At least one Saturn server running on your network
• Administrator access to Open WebUI settings

Method 1: Discover from Community (Recommended)

1. Open Function Settings

   Click your Name/Avatar in the top-right corner, then navigate to Settings → Admin Settings → Functions.
2. Discover Function

   Select Discover a Function at the bottom of the page.
3. Search for Saturn

   In the search box, type Saturn. The Saturn function should appear in the results.
4. Install Function

   Click on the Saturn function result and follow the prompts to install it.

Method 2: Manual Installation (If Discovery Doesn't Work)

If the function doesn't appear in search results, you can manually install it by copying the source code:

1. Copy Source Code

   Open owui_saturn.py from the repository root directory and copy all of its contents.
2. Create New Function

   In Open WebUI, go to Settings → Admin Settings → Functions, click the + (plus icon) button, and select Create New Function.
3. Paste Code

   Delete any template code and paste the entire contents of owui_saturn.py into the code editor.
4. Save Function

   Click Save to create the function. Open WebUI will validate the code and add it to your functions list.

Using Saturn with Open WebUI

Enabling the Function

1. Ensure at least one Saturn server is running on your network
2. In Open WebUI, go to Settings → Admin Settings → Functions
3. Find the Saturn function in the list
4. Toggle it to Enabled
5. Refresh Open WebUI (F5 or reload the page)

Selecting Saturn Models

Once enabled, Saturn models will appear in Open WebUI's model selector:

1. Open Model Selector

   In the chat interface, click the model dropdown (usually at the top of the page).
2. Find Saturn Models

   Saturn models are prefixed with SATURN/ followed by the service name and model ID. For example: SATURN/OpenRouter:anthropic/claude-3-opus.
3. Select and Chat

   Select any Saturn model and start chatting. The function automatically routes your requests to the appropriate Saturn service.

Configuring Function Settings

The Saturn function includes configurable "valves" (settings) that you can adjust:

To adjust these settings:

1. Go to Settings → Admin Settings → Functions
2. Click on the Saturn function
3. Look for the "Valves" section
4. Adjust values as needed and save

How Failover Works

If you have multiple Saturn services offering the same model, the function provides automatic failover:

1. Primary Service Selection

   The function selects the service with the lowest priority number for each model.
2. Request Attempt

   Your chat request is sent to the primary service.
3. Automatic Failover

   If the primary service fails, the function automatically tries the next service offering that model.
4. Transparent Recovery

   Failover happens automatically - you'll receive your response without knowing a backup was used.

Integration Troubleshooting