Configuration

The client is configured through an options object passed to the constructor. This page documents every available option.

Client Options

TypeScript

import { StarfishClient } from "@starfish/client";

const client = new StarfishClient({
  server: "ws://localhost:4000",
  project: "studio-42",
  webSocketFactory: (url) => new WebSocket(url),
  client: {
    name: "my-app",
    role: "performer",
    meta: { version: "1.0" },
  },
  auth: { type: "token", token: "my-secret" },
  reconnect: {
    enabled: true,
    maxRetries: 10,
    baseDelayMs: 1000,
    maxDelayMs: 30_000,
  },
  rtc: {
    peerConnectionFactory: (config) => new RTCPeerConnection(config),
    iceServers: [{ urls: "stun:stun.l.google.com:19302" }],
  },
});

Python

from starfish import (
    StarfishClient,
    StarfishClientOptions,
    ClientIdentity,
    AuthOptions,
    ReconnectOptions,
)

client = StarfishClient(StarfishClientOptions(
    server="ws://localhost:4000",
    project="studio-42",
    client=ClientIdentity(
        name="my-app",
        role="performer",
        meta={"version": "1.0"},
    ),
    auth=AuthOptions(type="token", token="my-secret"),
    reconnect=ReconnectOptions(
        enabled=True,
        max_retries=10,
        base_delay=1000,
        max_delay=30_000,
    ),
))

Swift

import StarfishClient

let client = StarfishClient(options: StarfishClientOptions(
    server: URL(string: "ws://localhost:4000")!,
    client: ClientIdentity(
        name: "my-app",
        role: "performer",
        meta: ["version": "1.0"]
    ),
    auth: AuthOptions(type: "token", token: "my-secret"),
    reconnect: ReconnectOptions(
        enabled: true,
        maxRetries: 10,
        baseDelay: 1.0,
        maxDelay: 30.0
    )
))

Options Reference

server

The WebSocket URL of the Starfish server.

	TypeScript	Python	Swift
Type	string	str	URL
Required	Yes	Yes	Yes

project

The Project to bind the connection to, declared once at the handshake.

	TypeScript	Python
Type	string?	str | None
Default	"default" (when omitted)	"default" (when omitted)

Omitting it — or passing an empty string — binds the connection to the reserved "default" Project, which is always implicit and keeps the zero-config local-development behavior. You can also declare it when connecting: await client.connect("studio-42"). The effective Project the server bound you to is exposed on client.project after connecting.

webSocketFactory / ws_factory

A factory function that creates a WebSocket connection. Required in Node.js where no global WebSocket exists. Browsers and Python use their built-in implementations by default.

TypeScript

// Node.js
import WebSocket from "ws";
{ webSocketFactory: (url) => new WebSocket(url) }

Python

# Custom factory (optional — default uses websockets library)
{ ws_factory: my_custom_factory }

Swift

// Custom factory (optional — default uses URLSession)
{ webSocketFactory: { url in MyCustomTransport(url: url) } }

client

Identity information sent to the server during the handshake.

Field	Type	Default	Description
name	string	"starfish-client"	Display name for this client
role	string	"default"	Client role (application-defined)
meta	object	{}	Arbitrary metadata

auth

Authentication credentials sent during the handshake.

Field	Type	Default	Description
type	string	"none"	Auth type (e.g. "none", "token")
token	string?	—	Auth token value

reconnect

Controls automatic reconnection when the connection drops. The client uses exponential backoff with jitter.

Field	Type	Default	Description
enabled	boolean	true	Enable automatic reconnection
maxRetries	number	Infinity	Maximum reconnection attempts
baseDelayMs	number	1000	Initial delay in milliseconds
maxDelayMs	number	30000	Maximum delay cap in milliseconds

The delay formula is: min(baseDelayMs * 2^attempt + random jitter, maxDelayMs)

rtc (TypeScript only)

Enables WebRTC peer-to-peer connections. When provided, the client can establish direct data channels with other peers for low-latency communication.

Field	Type	Description
peerConnectionFactory	(config?) => RTCPeerConnection	Optional factory to create RTCPeerConnection instances. Defaults to the global RTCPeerConnection in browsers; supply one in environments where it is not available.
iceServers	IceServer[]	ICE server configuration for NAT traversal

{
  rtc: {
    peerConnectionFactory: (config) => new RTCPeerConnection(config),
    iceServers: [
      { urls: "stun:stun.l.google.com:19302" },
    ],
  },
}

TIP

WebRTC is optional. Without it, all communication goes through the WebSocket server. Enable it when you need lower latency for high-frequency updates like cursor positions or sensor data.

Server Options

The server is configured through a config object. Only the authentication seam is documented here; see each server's README for the full config surface.

Server authenticator

The validator that authenticates clients during the handshake. Defaults to an allow-all authenticator, so authentication is off until you set this. Supplying one makes the server require credentials, reject unauthenticated or invalid clients with auth.required / auth.failed, and advertise auth: { required: true } in the welcome.

	TypeScript	Go	Python
Field	StarfishConfig.authenticator	Config.Authenticator	StarfishConfig.authenticator
Type	Authenticator	Authenticator (interface)	Authenticator (protocol)
Default	new AllowAllAuthenticator()	AllowAllAuthenticator{}	AllowAllAuthenticator()

TypeScript

import { defaultConfig, TokenAuthenticator } from "@starfish/server";

const config = defaultConfig();
config.authenticator = new TokenAuthenticator("my-secret");

Go

config := starfish.DefaultConfig()
config.Authenticator = starfish.NewTokenAuthenticator("my-secret")

Python

from starfish_server import default_config
from starfish_server.auth import TokenAuthenticator

config = default_config()
config.authenticator = TokenAuthenticator("my-secret")

Use the built-in constant-time TokenAuthenticator for a single shared token, or implement the Authenticator seam for custom schemes (JWT, HMAC, database lookup). See the Authentication guide for the validator signature and worked examples.

Server managementKey

The admin key that guards the control plane — the HTTP API for provisioning declared Projects. The control plane is off by default: /admin/projects is mounted only when a management key is set. Without one, every referenced Project is implicit and the server runs zero-config.

	TypeScript	Go	Python
Field	StarfishConfig.managementKey	Config.ManagementKey	management key + port
CLI flag	--mgmt-key <key>	-mgmt-key <key>	--management-key <key> --management-port <port>
Env var	STARFISH_MGMT_KEY	—	—

Clients present the key as Authorization: Bearer <key> on every control-plane request. The Go and TypeScript servers mount /admin on the data-plane port; the Python server serves it on a separate management port. See the Project Provisioning API for the endpoints and schemas.

Join Options

Options passed when joining a session:

Field	Type	Default	Description
name	string?	Client ID	Display name in the session
role	string?	"default"	Role in the session
meta	object?	{}	Session-specific metadata
create	boolean?	false	Create the session if it doesn't exist; omitted, join is join-only