Settings

This interface is experimental — no production implementation exists yet. The API surface may change.

Overview

Settings is the kernel interface for managing system-wide configuration that applies to all agents and workflows running on the platform. Unlike Preferences, which are scoped to individual agents or users, Settings entries are global — changing a setting affects every agent and workflow in the system. Analogous to Vercel Project Settings, Cloudflare Zone Settings, or AWS SSM Parameter Store.

TypeScript API

import type {
  SettingsEntry,
  SettingsContext,
  SettingsActions,
  Settings,
} from 'osprotocol/system/settings'

SettingsEntry

A single configuration entry stored in the system.

interface SettingsEntry<T = unknown> {
  key: string
  value: T
  description?: string
  readOnly?: boolean
  metadata?: Record<string, unknown>
}

Field	Type	Description
`key`	`string`	Unique identifier for the setting
`value`	`T`	The stored value (generic, defaults to `unknown`)
`description`	`string?`	Human-readable explanation of the setting
`readOnly`	`boolean?`	When `true`, the entry cannot be modified at runtime
`metadata`	`Record<string, unknown>?`	Arbitrary additional data (e.g. source, last modified)

SettingsContext

Read-only interface used during the gather phase. Lets agents inspect system configuration without mutation rights.

interface SettingsContext {
  get<T = unknown>(key: string): Promise<SettingsEntry<T> | null>
  list(): Promise<SettingsEntry[]>
}

SettingsActions

Write interface used during the act phase. Restricts callers to mutation operations only.

interface SettingsActions {
  set<T = unknown>(key: string, value: T): Promise<SettingsEntry<T>>
  remove(key: string): Promise<boolean>
}

Full interface combining read and write operations. Intended for privileged system-level callers.

interface Settings {
  get<T = unknown>(key: string): Promise<SettingsEntry<T> | null>
  set<T = unknown>(key: string, value: T): Promise<SettingsEntry<T>>
  remove(key: string): Promise<boolean>
  list(): Promise<SettingsEntry[]>
}

Usage Examples

Reading a setting

import type { Settings } from 'osprotocol/system/settings'

async function getMaxConcurrency(settings: Settings) {
  const entry = await settings.get<number>('workflow.max_concurrency')

  if (entry === null) {
    return 4 // default
  }

  return entry.value
}

Handling read-only settings

Some entries are marked readOnly and must not be modified at runtime. Check the flag before attempting a write.

async function updateSetting(settings: Settings, key: string, value: unknown) {
  const existing = await settings.get(key)

  if (existing?.readOnly) {
    throw new Error(`Setting "${key}" is read-only and cannot be modified.`)
  }

  return settings.set(key, value)
}

Typed settings with metadata

import type { Settings, SettingsEntry } from 'osprotocol/system/settings'

interface RateLimitConfig {
  requestsPerMinute: number
  burstAllowance: number
}

async function configureRateLimit(settings: Settings): Promise<SettingsEntry<RateLimitConfig>> {
  return settings.set<RateLimitConfig>('agent.rate_limit', {
    requestsPerMinute: 60,
    burstAllowance: 10,
  })
}

Settings vs Preferences

	Settings	Preferences
Scope	System-wide	Per-agent or per-user
Applies to	All agents and workflows	A specific agent or user
Who manages it	Platform operators	Individual agents or users
Typical values	Concurrency limits, feature flags, rate limits	Language, persona, output format
Change impact	Platform-wide	Isolated to the scope

Integration

Preferences — per-agent or per-user configuration, scoped rather than global
Environment — platform-level variables; settings govern higher-level behavioral configuration

Settings

On this page