Configuration

Configuration is typed in the kernel and loaded from YAML plus environment overrides. Secrets are redacted in Admin snapshots and logs.

Project files

Every generated project keeps its Boson metadata together:

.boson/
├── project.toml
├── config.yaml
├── logs/          # generated, ignored
└── run/           # generated, ignored

project.toml identifies the project and its workspace packages:

schema_version = 1
name = "my-app"
package_prefix = "my_app"
migrate_package = "my_app_migrate"
server_package = "my_app_server"
worker_package = "my_app_worker"

Boson discovers this marker by walking upward from the current directory, so lifecycle commands work inside nested capability folders too. Project configuration always lives at .boson/config.yaml.

Load order

Runtime configuration is merged in this order:

1. Typed platform defaults
2. .boson/config.yaml
3. BOSON__ environment variables

Environment keys use double underscores for nesting:

export BOSON__DATABASE__URL=postgres://boson:boson@localhost:5432/boson
export BOSON__ADMIN__BOOTSTRAP_TOKEN=replace-me
export BOSON__TELEMETRY__LOG_LEVEL=debug

BOSON_CONFIG remains a low-level override for launching a runtime binary directly. Project-aware CLI commands always use .boson/config.yaml.

Platform sections

Generated local configuration typically includes:

Section	Purpose
app	Application name and environment
http	Bind host/port and optional dashboard_dir for served Admin UI
database	PostgreSQL URL, pool size, connect/migrate flags
database_inspection	Optional Admin database browser
telemetry	Log level and JSON formatting
admin	Bootstrap Admin token
auth	JWT issuer, secret, and token TTLs
storage	Object-store provider (local or s3) and credentials
queue	Background queue provider and lease settings
mail	Mailer provider (local or smtp) and credentials
capabilities.*	Product-owned settings

Local endpoints

Service	Default
Server	http://localhost:8080
Dashboard	Served by Server when http.dashboard_dir is set
PostgreSQL	Connection from database.url (developer-owned)
Admin bootstrap token	local-development-token

Server readiness is gated on /readyz. When the Server binds 0.0.0.0 or ::, local health checks use 127.0.0.1.

Capability settings

Platform sections are closed and typed. Product settings belong below the capability namespace:

capabilities:
  items:
    max_items: 100

Capabilities deserialize their section with config.capability_config::<T>("items").

Inspect effective config

boson config

The command loads the discovered local project configuration and prints JSON with secrets redacted. It does not call the Admin API. The Admin API exposes its own redacted runtime snapshot separately.

Principles

• Prefer explicit config over magic defaults in production.
• Never commit production secrets.
• Keep runtime state in .boson/run and logs in .boson/logs.
• The Admin API only exposes a redacted configuration snapshot.