Configuration

valved init scaffolds a project’s config. This page summarizes each file; the control plane merges them into one effective config at runtime.

valved.toml — control-plane config

The project-root config. References components by name rather than containing them.

[project]
name = "jaffle-shop"
default_target = "dev"
valved_version = ">=0.1,<0.2"

[state_store]
url = "${DATABASE_URL}"          # Postgres only; env-var interpolation

# [components.<name>] blocks are OPTIONAL — omit them for "simple mode"
# (components discovered by convention). Add them when a component graduates.
[components.analytics]
type = "dbt"                     # "dlt" | "dbt"
mode = "separate-remote"         # "same-repo" | "separate-local" | "separate-remote"
url  = "git@github.com:acme/analytics.git"
ref  = "9f3a1c7"                 # optional pin (SHA or tag)
# branch = "main"                # or track a branch HEAD

[components.<name>] fields: type and mode are always required; path is required for separate-local; url for separate-remote; ref/branch are optional pins. dbt components also take dbt_backend (local | snowflake-native | dbt-cloud | remote).

Pin precedence: ref → branch → default-branch HEAD. Convention-discovered components are never pinned.

valved/connections.toml — targets

Named targets (dev, prod, …). Each carries a warehouse dialect and role-scoped credentials — referenced, never inlined.

[targets.dev]
dialect = "duckdb"
path = "./dev.duckdb"

[targets.prod]
dialect = "snowflake"
account = "${SNOWFLAKE_ACCOUNT}"
user = "${SNOWFLAKE_USER}"
auth = "key_pair"                # password | key_pair | oauth | external_browser
private_key = "${SNOWFLAKE_PRIVATE_KEY}"
role = "TRANSFORM"               # write/deploy role
read_role = "READER"             # optional lower-privilege read role
warehouse = "TRANSFORM_WH"
database = "ANALYTICS"
schema = "DBT"

Credential indirection: ${ENV_VAR} or { file = "/path" } (Docker/K8s secrets). Valved never stores secrets in the state store.

valved/runner.toml (scaffolded)

Venv-backed execution knobs (all commented by default → built-in defaults apply).

# type = "local_venv"
# venv_cache_dir = ".valved/venvs"
# default_timeout_seconds = 1800
# max_concurrent_runs = 4

# [auto_fix]                      # recovery budget per failure
# enabled = true
# max_attempts = 3

valved/models.toml (scaffolded)

How the harness authenticates to Anthropic and which model it defaults to.

# auth_mode = "api_key"          # ANTHROPIC_API_KEY | "oauth" (ANTHROPIC_AUTH_TOKEN)
# anthropic_api_key = "${ANTHROPIC_API_KEY}"
# default_model = "claude-opus-4-8"

# [tiers]                        # optional named tiers a per-agent model: may reference
# fast = "claude-haiku-4-5"

Leave auth_mode unset to auto-resolve (API key first, then a Claude-subscription OAuth token minted via valved auth login).

valved/runtime.toml (optional — not scaffolded)

Tunes the supervisor loops. Create it only to override defaults.

[scheduler]
interval_s = 30

[reaper]
interval_s = 30
stale_threshold_s = 60           # missed heartbeats → reclaim a crashed worker's jobs

[worker]
intra_pipeline_slots = 4         # parallel steps per worker

[runtime.archive]
interval_s = 3600
jobs_window = "7d"
runs_window = "30d"
logs_window = "30d"

[recovery]
enabled = true
daily_token_budget_usd = 5       # spent → log-only until reset

[permissions]                    # TIGHTEN-ONLY: narrows mode defaults, never widens
# effective grant = mode-default ∩ this config ∩ the agent's frontmatter

[api.cors]
allowed_origins = ["http://127.0.0.1:*"]   # OSS default: loopback for the static UI

pipelines/<name>.toml

A pipeline’s step DAG plus an optional [seed_schedule]. Authored via plan/build, not by hand. The [seed_schedule] block is applied only at first registration — editing it later is a no-op unless you run valved schedule reseed <pipeline>. There is no paused/enabled key: pause/resume is live data (valved schedule).

Extensibility files

File	Format	Notes
valved/agents/<name>.md	Markdown + YAML frontmatter	Overrides a built-in of the same name.
valved/skills/<name>/SKILL.md	Markdown + frontmatter	A skill; testable with valved skills test.
valved/hooks.toml	TOML	Lifecycle hooks.
valved/mcp.toml	TOML	External MCP servers Valved consumes.

Files Valved generates

• .valved/ — generated runtime state (gitignored), including .valved/token (the REST/MCP bearer token, mode 0600) and .valved/venvs/.
• .dlt/secrets.toml — dlt connector credentials (gitignored). .dlt/config.toml is safe to commit.

The exhaustive schema for every file lives in the project’s specs/reference/config-schema.md.