@cool-ai/beach-config

Declarative YAML configuration for Beach applications.

What this package is

Beach treats configuration as data, not code. A Beach application is described by a small tree of YAML files — one per actor, one per channel, one per tool, one per model class — that together describe what the application is, where it runs, and which secrets it depends on. Beach loads, validates, and cascades these files at startup, producing a frozen typed object the rest of the application reads.

The three axes:

| Axis | Files | Reviewer | | -------------- | -------------------------------------------------------- | ------------------------------ | | Functional | beach.functional.yaml, actors/*, tools/*, models/* | App engineers, code review | | Environmental | beach.environment.yaml, beach.environment.<env>.yaml, channels/* | Ops, deployment review | | Secret | beach.secrets.env | Secrets owner, rotation gate |

For the prose introduction, see Configuring a Beach application. For the JSON Schemas the package ships, see Reference: Configuration Schemas. For the CLI in detail, see Reference: beach-config CLI.

Quickstart

npm install @cool-ai/beach-config
npx beach-config init        # scaffolds ./config with three model files,
                             # functional + environmental files, and the
                             # conventional actors/, channels/, tools/ dirs

Add --with-starter to the init call to lay down a worked example (one actor, one tool, one streaming channel) wired for @cool-ai/beach-starter's request-reply pipeline.

npx beach-config validate    # CI-friendly check; exits 1 on any error
npx beach-config tree        # navigable inventory of the loaded config
npx beach-config explain actors.concierge.maxTokens   # walk the cascade for one key

CLI

beach-config init               # scaffold the directory layout
beach-config validate           # CI-friendly check, with --with-app-schema for app: blocks
beach-config tree               # print the inventory (with --section, --depth, --diff, --json)
beach-config explain <key>      # walk the cascade for one key
beach-config split <section>    # inline → one-file-per-thing
beach-config merge <section>    # one-file-per-thing → inline
beach-config update-models      # refresh shipped model files (opt-in)

Programmatic API

import { loadBeachConfig } from '@cool-ai/beach-config';

const { config } = await loadBeachConfig({
  configRoot: './config',
  deployment: process.env.BEACH_DEPLOYMENT,
});

// Hand the relevant slice to each Beach primitive's `fromConfig` factory.
const router  = EventRouter.fromConfig(config.functional.router);
const manager = SessionTurnManager.fromConfig(config.functional.session, { router });

Application-side extensibility

Beach is silent on consumer-defined fields, but the config tree is the right place to keep them. Three reserved namespaces give consumers room without forcing Beach to validate anything it has no opinion about: top-level app: on the functional file, per-instance app: on actor / channel / tool files, and app.collections.<name> for consumer-defined collection-shaped data using the same include vocabulary as Beach's own collections.

To bring app: blocks under per-file checking, ship a JSON Schema with the application and run beach-config validate --with-app-schema ./schemas/app.schema.json.