Configuration

openroutines.yml sits at the root of the agent repository and holds the agent’s identity and the defaults its routines inherit. openroutines configure fills it in; after that it’s a file you edit like any other in the repo.

Decoding is strict, so a misspelled key fails the load rather than being quietly ignored, and openroutines check reports anything missing or invalid before you deploy.

Every key, with the optional ones filled in:

name: "Product Pal"
instructions: "Keep the roadmap and the docs honest about what actually shipped."
repo: https://github.com/acme/product-pal
owner:
  name: "Dana Reed"
  email: "dana@acme.com"
timezone: "America/New_York"
defaults:
  model: "anthropic/claude-sonnet-5"
  timeout: 5m
max_timeout: 6h
concurrency: 2
knowledge:
  retention: 30d
variables:
  product_repo: acme/product
credentials:
  product_bot:
    type: github_app
    app_id: "1234567"

Key reference

Key	What it declares
`name`	Required. The agent’s identity, and standing context in every run.
`instructions`	Optional. A standing prompt every run receives ahead of the routine’s own. Routine-specific direction belongs in the routine.
`repo`	Optional locally, required to deploy. The git URL the agent pushes its knowledge to. `check` fails without it.
`owner.name`	Optional. Who is responsible for the agent.
`owner.email`	Optional. The address `openroutines status` reports.
`timezone`	Required. An IANA timezone, like `America/New_York`. Every routine’s cron schedule is read in it.
`defaults.model`	Required. The `provider/model` a routine uses unless its frontmatter overrides it. Browse models.dev.
`defaults.timeout`	Optional, `5m`. How long a run may take when the routine doesn’t set its own.
`max_timeout`	Optional, `6h`. The ceiling on any run, whatever the routine or the defaults ask for.
`concurrency`	Optional, `1`. How many routines may run at once, up to 32. Unset means serial, and new agents are scaffolded at 2.
`knowledge.retention`	Optional, `30d`. How long working knowledge is kept before it’s trimmed, as `Nd` or a duration like `720h`. Git history is kept either way.
`variables`	Optional. Non-secret values injected into every run’s environment, so `product_repo` arrives as `$PRODUCT_REPO`. See Variables.
`credentials`	Optional. Per-credential metadata that gives a stored secret a type. A credential with no entry here is injected verbatim. See below.

Naming variables and credentials

Both maps are keyed in lowercase snake_case — ^[a-z][a-z0-9_]*$ — because each name becomes an environment variable in uppercase. Two families are refused: anything starting with openroutines, and anything that would shadow anything the framework sets for a run, which means tz, path, home, tmpdir, and any name beginning ld_ or xdg_.

Credential types

A credential entry declares a type and the fields that type owns. Fields belonging to another type are rejected rather than ignored, and an entry with no type is an error — omit the entry entirely for a raw credential. Typed credentials covers what each type does and how to store its secret.

Type	Fields
`github_app`	`app_id` — the App’s numeric id.
`oauth2_client`	`token_url`, which must be https; `client_id`; and `inject_as`, the snake_case name the minted bearer arrives under.