App Configuration

Canonical app YAML for Digitorn. Unknown keys are rejected when the compiler schema enforces them. Field lists below match internal/compiler/schema in the Go daemon.

Tool names in examples must match registered modules. Prefer database.query, http.request, scheduler.schedule. See YAML building blocks.

Top-level blocks (`AppDefinition`)

Block	Required	Role
`schema_version`	no	Forward-compat int (default 2)
`app`	yes	Identity (`app_id`, `name`, ...)
`runtime`	no	Modes, workdir, triggers, hooks, injection
`agents`	no	Agent list
`tools`	no	`modules`, `capabilities`, `channels`
`security`	no	`behavior`, `sandbox`, credentials schema
`ui`	no	Client manifest
`dev`	no	Variables, skills, secrets helpers
`flow`	no	Declarative flow graph
`templates`	no	Seed / preview templates
`requirements`	no	Install requirements
`context`	no	Context inject blocks
`documents`	no	Document declarations
`docs`	no	In-app docs
`modules` / `capabilities`	no	Legacy top-level aliases

`app`

Typical fields: app_id, name, short_name, version, description, author, tags, icon, color, category, quick_prompts, attachments, attachments_mode, features, theme, mode.

`runtime`

Field	Notes
`mode`	Conversation / background / etc.
`entry_agent`	Default agent id
`max_turns`, `timeout`	Turn budget
`workdir`, `workdir_mode`	Session workspace
`modes`, `default_mode`	Named mode overlays (`ModeDef`)
`input`, `output`	Activation I/O shape
`max_sessions_per_user`	How many conversations one person may keep open at once
`max_concurrent_activations`	How many runs of this app happen at once; it can only tighten the server's own limit, never raise it
`payload_schema`	Structured activation
`context`	Context window policy
`direct_modules`	Force modules into direct injection
`tool_injection`	`direct` / `compact_direct` / `discovery`
`hooks`, `middleware`	Lifecycle hooks
`max_stop_retries`	Stop retry budget
`default_channel`	Default channel instance name
`workbench*`	Workbench / reflection flags
`flow`	Inline flow (also top-level `flow:`)
`mid_turn_messages`	Mid-turn message policy

What wakes a background app

digitorn-background arms one listener per entry under tools.modules.channels.config.providers. Seven adapters: cron, webhook, rss, telegram, discord, whatsapp, pieces. See Channels.

Durable project knowledge

A context section, not a runtime field: context.sections[].builtin: memory_index injects .digitorn/memory/ every turn and lets the agent write to it. See Project memory.

`agents[]`

Each agent has identity (id, role, ...), brain, system_prompt, module grants, and related fields from schema.Agent. Brain backends are resolved by the LLM stack (OpenAI-compatible, Anthropic, ...).

`tools`

yaml
tools:
  modules:
    filesystem: {}
    bash: {}
    scheduler: {}
  capabilities:
    default_policy: auto   # or approve / deny policies as implemented
    grant:
      - module: filesystem
      - module: bash
  channels:
    alerts:
      type: webhook
      config:
        url: "{{secret.WEBHOOK_URL}}"

`tools.modules.<id>` (`ModuleBlock`)

Key	Role
`config`	Module-specific map (also accepts unknown keys folded into config)
`setup`	`[{action, params}]` run at bootstrap
`constraints`	e.g. `allowed_actions`, `blocked_actions`
`middleware`	Module middleware entries
`credential`	Credential reference

YAML alias: workspace under modules/grants (file I/O intent) is rewritten to filesystem. The Git module remains registered as workspace in the runtime.

`tools.channels.<name>`

Key	Role
`type`	Adapter id (see Channels)
`config`	Adapter config map
`user_resolver`	Optional `{module, action, params, mapping, cache_ttl}`

`security`

yaml
security:
  behavior:
    profile: coding          # dev|coding|research|data|creative|assistant
    classify_turns: true
    rules: {}                # boolean / threshold overrides
    rule_definitions: []     # declarative rules
    state_tracking: {}
    classifier: {}
    brain: {}                # optional classifier brain
  sandbox: {}
  credentials_schema: {}

Full behavior: Behavior.

Minimal valid sketch

app.yaml
schema_version: 2
app:
  app_id: hello
  name: Hello
  version: "0.1.0"
agents:
  - id: main
    role: assistant
    brain:
      provider: ollama
      model: qwen2.5:7b
      backend: openai_compat
      config:
        base_url: http://localhost:11434/v1
        api_key: ollama
    system_prompt: "Be concise."
tools:
  modules:
    filesystem: {}
  capabilities:
    grant:
      - module: filesystem

Top-level blocks (AppDefinition)​

app​

runtime​

What wakes a background app​

Durable project knowledge​

agents[]​

tools​

tools.modules.<id> (ModuleBlock)​

tools.channels.<name>​

security​

Minimal valid sketch​

Related​