Global Configuration

Set you-agent-factory operator model defaults and manage global / named factories under ~/.you-agent-factory.

Operator Model Defaults

Use operator defaults when you want one preferred provider and model across runs without editing every factory worker. Defaults apply only to INFERENCE_WORKER and AGENT_WORKER entries that omit modelProvider or model. Authored worker values stay as written. Script workers and poller workers never receive operator defaults. The runtime fills omitted fields in memory at startup and does not persist those fills into factory.json.

Default config path:

~/.you-agent-factory/config.json

Example operator config:

{
  "defaults": {
    "workerModelProvider": "codex",
    "workerModel": "gpt-5-codex"
  }
}

A missing config file is valid and applies no operator defaults. Malformed JSON fails before service construction with an error that names the config file path. Unknown top-level JSON fields are rejected. Empty or unset environment values do not clear a lower-precedence layer.

Environment overrides (each field independently):

Variable	Purpose
YOU_DEFAULT_WORKER_MODEL_PROVIDER	Overrides defaults.workerModelProvider from the config file
YOU_DEFAULT_WORKER_MODEL	Overrides defaults.workerModel from the config file

Global CLI flags (highest precedence per field):

Flag	Purpose
--default-worker-model-provider	Overrides file and environment for the worker model provider
--default-worker-model	Overrides file and environment for the worker model

These are global persistent flags on the root you command. Both bare you and explicit you run honor them:

you --default-worker-model-provider codex --default-worker-model gpt-5-codex run

Effective precedence is independent per field. For each of workerModelProvider and workerModel, the winning layer is:

file < env < flag

You Configuration Schema

The live you-config schema is the contract for ~/.you-agent-factory/config.json. defaults holds operator model preferences parsed from file before env and flag resolution. workerPresets names reusable file-only worker model presets. backendScopeID identifies the local provider-backed runtime boundary. Open the full schema and API references when you need exhaustive contract lookup beyond this teaching embed.

You operator and system configuration

object

The shared .you-agent-factory/config.json contract owned by the Operator Settings service.

additionalPropertiesfalse (closed)

Fields

backendScopeIDbackendScopeIDOptionalstring
Stable identifier for the local provider-backed runtime boundary owned by operator_settings.
defaultsdefaultsOptionalobject
Operator defaults parsed by operator_settings from file before env/flag resolution.
- additionalPropertiesfalse (closed)
runtimeruntimeOptionalobject
Runtime observability settings loaded from operator configuration before command-line overrides.
- additionalPropertiesfalse (closed)
workerPresetsworkerPresetsOptionalworkerPreset[]
Named worker model presets parsed from file only.

Teaching embeds show the live root and addressed definitions that matter on this page. They are not a substitute for the full schema or API inventories.

Named Factories

Named factories are persisted factory definitions under a factory root. The project-local root defaults to ./factory (or the path you pass with --dir). The global shared root is ~/.you-agent-factory/factories. Use you run --named <name> to resolve a canonical persisted name: project-local first, then the global shared root, then built-in catalog materialization on first use. Listing, saving, updating, and deleting always target exactly one root via --dir; they never merge project-local and global entries in one command.

Global shared factories root:

~/.you-agent-factory/factories

Default project-local root:

./factory

you run --named <name> resolves a canonical persisted factory name in this order:

project-local ./factory (or --dir)
→ global ~/.you-agent-factory/factories
→ built-in catalog materialization on first use

you factory list lists exactly one root at a time and never merges project-local and global entries. By default it lists ./factory. Point --dir at ~/.you-agent-factory/factories to list global built-ins and shared factories.Built-ins such as @you/goal, @you/fusion, and @you/tts materialize into the global root on first use and remain editable on disk for later runs. Deep packaged invocation signatures stay on sibling docs surfaces; this page only covers where those factories live and how named resolution finds them.

Factory Name Contract

The live FactoryName definition is the customer-facing identifier for one stored named factory. Named resolution and factory-session lookup use that identity. Exhaustive Factory field inventories stay on the full schema and API reference pages.

FactoryName

string

Customer-facing identifier for one stored named factory. `GET /factory-sessions/~default/factory` may also return the reserved `UNDEFINED` identifier when the active runtime is still the default root factory and no durable current-factory pointer exists. Semantic validation failures return `INVALID_FACTORY_NAME`, including attempts to activate a named factory with the reserved identifier.

pattern^(UNDEFINED|[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$
minLength1

Full Factory schema

Factory Runner Versus Operator Defaults

Factory-level runner in factory.json is topology-owned and distinct from operator model defaults. The live RunnerID contract lists built-in runner identifiers for factory and workstation runner selection. Operator defaults do not rewrite runner fields. Set operator defaults or author modelProvider on workers when you need a preferred model worker provider — do not expect runner to stand in for operator defaults.

RunnerID

string

Stable built-in runner identifiers supported by factory and workstation runner selection.

enum"codex" | "claude" | "antigravity"

How To Use

Create ~/.you-agent-factory/config.json with defaults.workerModelProvider and defaults.workerModel when you want one preferred provider and model across runs. Override a single invocation with YOU_DEFAULT_WORKER_MODEL_PROVIDER and YOU_DEFAULT_WORKER_MODEL, or with --default-worker-model-provider and --default-worker-model on the root you command. Precedence is independent per field: file, then env, then flag. For named factories, list one root at a time, run with you run --named, and save or update under the --dir root you intend to own. Use the factories configuration page when you need factory.json topology instead of operator or global factory settings. Packaged @you/* invocation signatures stay on their sibling docs surfaces.

List named factories under the project-local root:

you factory list

List named factories under the global shared root:

you factory list --dir ~/.you-agent-factory/factories

Run a named factory (project-local first, then global, then built-in materialization):

you run --named @you/goal

Save a named factory under a chosen root:

you factory save staging --from ./factory.json --dir ~/.you-agent-factory/factories

Update an existing named factory under a chosen root:

you factory update staging --from ./factory.json --dir ~/.you-agent-factory/factories

Limits And Assumptions

This page is the web operator-defaults and global / named-factories reference. It is not a sync of packaged CLI docs, not the factory.json topology overview, not workers, workstations, or resources field dumps, not packaged @you/* invocation deep dives, not factory-session, and not submitting-work. Use the related factories and documentation links for factory.json topology, CLI command surfaces, and worker field contracts. Operator-default startup failures stay short here: missing config continues with no defaults; malformed config, unsupported providers, and DEFAULT without a concrete lower-precedence provider fail before dispatch. Exhaustive System config and Factory field inventories live on the schema and API reference pages linked from the schema sections.

Operator-default failure modes:

Condition	Behavior
Missing ~/.you-agent-factory/config.json	Startup continues with no operator defaults
Malformed config JSON	Fails before service construction; error names the config path
Unsupported workerModelProvider	Fails before dispatch with accepted provider summary
DEFAULT without a lower-precedence concrete provider	Fails before dispatch with resolution guidance
Authored worker modelProvider or model	Operator defaults do not override authored values