App Configuration

Canonical app YAML for Digitorn. Unknown keys are rejected when the compiler schema enforces them. Field lists below match the compiler's schema exactly.

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, hooks, injection
agents	no	Agent list
tools	no	modules, capabilities, channels
security	no	behavior, 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, features, theme, mode, hidden.

Field	Notes
hidden	true keeps the app out of the user-facing catalog (the home screen, the agents list, the app switcher and the command palette). The app stays fully installed and runnable when opened directly by its id, useful for an internal agent reached only from another surface (e.g. builder-assistant, docked inside the Studio). Default false.

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. Background wake-ups (cron/webhook/telegram/...) are armed under tools.modules.channels, not here - see below.
max_stop_retries	Stop retry budget
workbench*	Workbench / reflection flags
flow	Accepted by the schema, but not read anywhere - the flow engine only looks at the top-level flow: block. Declare flows there, not here.
mid_turn_messages	Mid-turn message policy
locked	Publisher-fixed settings applied on every install (byok today) - see Locked settings

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, connector. 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

Background triggers (cron, webhook, RSS, Telegram, Discord, WhatsApp, connector) are a separate module, not a tools sibling: see tools.modules.channels.

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
editable	Publisher opt-in letting installers customize this module's own config - unset/false (default) means the installer's app settings never show a tab for it at all. See Let installers customize a module

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

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
  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

Related

• YAML building blocks
• Tools
• Modules
• Client manifest