Digitorn App Language Reference

Digitorn apps are declared in a single YAML file. The compiler parses that YAML into the root model and the daemon runs it.

There is one canonical schema (v2). The usual surface is eight top-level blocks, plus additional first-class blocks when you need them (context, documents, docs, templates, requirements). Every field has exactly one home; legacy flat YAMLs (execution:, modules: at the top level, ...) are still accepted by an alias pass that reshapes them to canonical before validation.

The optional schema_version: 2 declaration at the top of the file future-proofs against breaking changes.

The usual 8 blocks

Block	Required	What it holds	Doc
app:	Yes	Identity - app_id, name, version, icon, color, tags, quick_prompts.	App Configuration
runtime:	No (defaults)	Lifecycle - mode, entry_agent, max_turns, timeout, triggers, hooks, middleware, pipeline, context, workdir, default_channel.	App Configuration, Triggers, Middleware, Tool Hooks, Context Management
agents:	At least 1 in practice	List of agents. Each has id, role, brain, system_prompt, modules, pool, delegate_to.	Agents, Multi-Agent
tools:	No	What the agent can call: modules (dict), capabilities (grant / deny), channels (dict).	Tools, Built-in Tools, MCP Servers, Channels, Security
security:	No	Runtime boundaries: behavior, sandbox, credentials_schema.	Behavior Engine, OS Sandbox, credentials.md
ui:	No	Client display: theme, features, widgets, workspace (renderer), slash_commands, quick_prompts, greeting. Mostly client-side; the daemon still reads a few UI fields (for example activity / tool-call inject hints). Live app preview is the preview / previewshot modules plus HTTP /preview/serve/..., not a web_preview module.	Client Manifest
dev:	No	Developer affordances: skills, variables, include (fragmentation).	Skills System, Bundle namespaces
flow:	No	Optional declarative orchestration graph for multi-agent apps. Top-level since v2 because it changes how agents coordinate (explicit scenography vs implicit Agent() calls).	Flows

Also accepted on the root (see App Configuration → Additional top-level blocks): context:, documents:, docs:, templates:, requirements:.

The ui.workspace block (renderer) is a different concept from runtime.workdir (filesystem path). The schema renames the legacy execution.workspace to runtime.workdir to remove the ambiguity (see RuntimeBlock.workdir).

Quick example

This example uses a local Ollama model so no external credentials are required. Replace the brain block to use any other provider (provider: openai, provider: anthropic, provider: deepseek, etc.); see Agents for the full list.

app.yaml

app:
  app_id: my-assistant
  name: My Assistant

runtime:
  mode: conversation

agents:
  - id: assistant
    role: assistant
    brain:
      provider: ollama
      model: qwen25-7b-gpu:latest
      backend: openai_compat
      config:
        base_url: http://localhost:11434/v1
        api_key: ollama
    system_prompt: |
      You are a helpful assistant. Reply concisely.

tools:
  modules:
    memory:
      config:
        auto_remember: false
  capabilities:
    default_policy: auto
    grant:
      - module: memory
        actions: [remember]

ui:
  greeting: "Hello! How can I help?"

Deploy and chat with it:

bash

digitornd -config config.yaml                  # daemon if not running (subcommand `run` is optional)
digitorn install my-assistant.yaml             # deploy + arm triggers
digitorn chat my-assistant                     # talk to it

Migration from the legacy flat shape

If your YAML has execution:, modules:, channels:, behavior:, ... at the top level, the compiler still accepts it via the alias pass. The bidirectional mirror means both shapes work at read time.

The compiler handles legacy flat-shape YAMLs automatically via the alias pass · no migration command needed. The bidirectional mirror means both shapes work at read time.

To rewrite a file in-place to the canonical form, the compiler also accepts the result directly; simply save in the new shape.

Field renames the migrator applies (no compat retention). Each row shows the legacy v1 path on the left and the v2 canonical path on the right:

Legacy v1	Canonical v2
execution.workspace	runtime.workdir
execution.workspace_mode	runtime.workdir_mode
execution.greeting	ui.greeting
execution.credentials_schema	security.credentials_schema
dependencies.variables	dev.variables
dependencies.channels	tools.channels
dependencies.credentials	security.credentials_schema
dependencies.payload	runtime.payload_schema

Top-level lifts (legacy → canonical home, fields keep their name):

Legacy top-level (v1)	Canonical (v2)
modules:	tools.modules
capabilities:	tools.capabilities
channels:	tools.channels
behavior:	security.behavior
widgets:	ui.widgets
workspace: (block at root)	ui.workspace (renderer)
preview:	the preview module + the HTTP preview routes
theme:	ui.theme
features:	ui.features
slash_commands:	ui.slash_commands
skills:	dev.skills
variables:	dev.variables
include:	dev.include
middleware:	runtime.middleware
pipeline:	runtime.pipeline
flow: (in v1 was top-level too, but is now strictly canonical)	flow: (top-level, NOT under runtime)

Everything that was under execution: (mode, triggers, hooks, max_turns, timeout, session_mode, direct_modules, tool_injection, default_channel, context, payload_schema, watchers, scheduler, ...) lifts to runtime: with the same name. security.credentials_schema → security.credentials_schema, ui.greeting → ui.greeting.

Documentation by topic

Getting started

• Getting Started - install, first app, run loop
• App Configuration - exhaustive reference for the 8 blocks
• Examples - complete real-world apps

Agents and tools

• Agents - agent definition, brain, providers, fallback
• Multi-Agent - coordinator + specialists, agent_spawn, isolation
• Tools - adaptive tool injection, discovery, semantic search
• Built-in Tools - delegation, memory, todo, messaging
• Execution Primitives - parallel execution, watchers, scheduler
• MCP Servers - connect external MCP servers, OAuth2
• Web Module - search + fetch + parse
• LSP Diagnostics - real-time code diagnostics

Memory and context

• Cognitive Memory - working memory, tasks, notes, facts
• Context Management - compaction, summary brain, hooks
• Advanced RAG - hybrid retrieval, citations, semantic cache, Text2SQL

Runtime control

• Triggers - cron, watch, http (background mode)
• Flows - declarative orchestration graph
• Middleware Pipeline - secret masking, content filter, RAG inject
• Tool Hooks - pre/post hooks around tool calls
• Skills System - /commit, /review, custom commands
• Channels (Bidirectional I/O) - webhooks, cron, email, RSS
• Background Sessions - mono / multi session modes
• Macros - reusable YAML fragments
• Composition - referencing other apps
• Rules - modular project instructions

Security

• Capabilities - default_policy, grant / deny, approve gates
• Behavior Engine - declarative runtime rules + classifier
• Auth - JWT, per-user installs

UI and client

• Client Manifest - features, theme, slash_commands
• Widgets - declarative UI primitives
• filesystem / workspace / preview - file I/O, Git tracking, live canvas
• Preview SDK - @digitorn/preview-sdk React package: hooks, components, host protocol, hidden namespaces
• Bundle namespaces - {{prompt.X}}, {{include:}}, hot reload

Shipping apps

• Production checklist - harden app YAML for real use
• Multi-tenant installs - system-wide vs per-user apps
• Bundle namespaces - prompts, skills, assets
• Dev CLI - digitorn lint / install / chat
• External APIs - http module from an app
• Expressions - {{env.X}}, {{secret.X}}, …

Modules

See YAML building blocks for the inventory. Per-module pages: reference/modules/.

Common modules: bash, browser, database, filesystem, http, lsp, mcp, pieces, preview, previewshot, rag, scheduler, web, workspace, plus memory, agent_spawn, context_builder, and channels.

Do not invent web_preview, dev_tools, queue, or vector modules. File I/O is filesystem; workspace is Git revise / approve. Widgets live under ui.widgets.

From YAML to a running chat

1. Author the YAML (and optional bundle files).
2. Lint until it compiles cleanly.
3. Install into your Digitorn instance.
4. Chat, or let background triggers wake the app.

Tool delivery - direct, compact, or discovery

Control how many tool schemas the model sees up front with runtime.tool_injection (or let Digitorn pick from tool count):

• direct - full schemas up front (small apps).
• compact_direct - short descriptions; full schema via get_tool.
• discovery - meta-tools (search_tools, get_tool, execute_tool, run_parallel, background_run, …) first; domain tools on demand.

See Discovery tutorial.

LLM compatibility

Three backends are supported (agents[].brain.backend). The three backends are openai_compat (default), anthropic, and github_copilot.

• openai_compat - any OpenAI-compatible /v1 endpoint (OpenAI, DeepSeek, Groq, Mistral, Together, Ollama, vLLM, LM Studio, OpenRouter, Cerebras, Perplexity, Fireworks, xAI, Gemini, ...).
• anthropic - Anthropic SDK (also accepts the claude-code API-key alias for Claude Code OAuth tokens, see llm_provider module).
• github_copilot - uses your GitHub Copilot subscription.

Models that support native tool calling (OpenAI, Anthropic, DeepSeek, Groq, Mistral, Together) get tools via the API tools= parameter. Models that don't (Ollama, LM Studio, vLLM, small local models) get tool schemas injected into the system prompt; tool calls are parsed from the text output via a multi-format recovery parser.

bash

# Auth
digitorn login
digitorn logout
digitorn whoami

# App lifecycle
digitorn install <app.yaml>
digitorn list
digitorn uninstall <app-id>
digitorn enable <app-id>
digitorn disable <app-id>
digitorn app-reload <app-id>
digitorn app-info <app-id>
digitorn app-status <app-id>

# Secrets
digitorn secret list <app-id>
digitorn secret get <app-id> <key>
digitorn secret set <app-id> <key>
digitorn secret delete <app-id> <key>

# Chat
digitorn chat <app-id>
digitorn chat <app-id> -s <sid>
digitorn sessions <app-id>

# Daemon reachability (CLI client)
digitorn status
digitorn doctor
digitorn daemon-stats

Full flag lists: digitorn --help and CLI reference. For installing digitornd as a system service (install / start / stop / ...), see Install and Production Deployment.