Digitorn App Language Reference

Digitorn apps are declared in a single YAML file. The compiler parses that YAML 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; two flat root keys (modules:, capabilities:) are still accepted as aliases - see The two root-level aliases below for the full, exact list. Anything else at the root is an unknown-key compile error.

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, hooks, middleware, context, workdir, modes / default_mode.	App Configuration, Modes, 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	behavior and credentials_schema - the two real sub-keys. Path confinement (the "sandbox") isn't declared under security: at all; it's automatic, tuned per module via tools.modules.<id>.constraints.	Behavior Engine, Workdir 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/....	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 → Top-level blocks): context:, documents:, docs:, templates:, requirements:.

The ui.workspace block (renderer) is a different concept from runtime.workdir (filesystem path) - don't confuse the two.

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: {}
  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 channel providers
digitorn chat my-assistant                     # talk to it

The two root-level aliases

Only two legacy flat keys are still accepted directly on the YAML root - everything else needs its canonical home under tools: / security: / ui: / dev: / runtime: or it's an unknown-key compile error, full stop:

Root key	Folds into	Merge behavior
modules:	tools.modules	Per-entry: a name already declared under tools.modules wins over the root-level one.
capabilities:	tools.capabilities	Whole-block: only applies if tools.capabilities isn't set at all.

Separately, workspace used as a module id (under tools.modules or a root-level modules:) is always rewritten to filesystem - see Built-in Tools. That's a module-name alias, not a shape migration.

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, watch loops, 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, multiple vector-store backends

Runtime control

• Flows - declarative orchestration graph
• Middleware Pipeline - secret masking, content filter, response filtering
• Tool Hooks - pre/post hooks around tool calls
• Skills System - /commit, /review, custom commands
• Channels (background mode / bidirectional I/O) - cron, webhook, telegram, discord, whatsapp, rss, connector
• 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
• Modes - Plan/Build-style overlays; user- or agent-switched (change_mode)
• 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
• @digitornai/sdk - the React package any custom view or preview renders behind: hooks, components, host protocol
• Bundle namespaces - {{prompt.X}}, {{include:}}, app-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
• 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, connector, preview, previewshot, rag, scheduler, web, plus memory, agent_spawn, context_builder, and channels. Widgets live under ui.widgets.

From YAML to a running chat

1. Author the YAML (and optional bundle files).
2. Install into your Digitorn instance - the daemon compiles it server-side and reports diagnostics if anything's wrong.
3. Chat, or let a background channel provider 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 via agents[].brain.backend: 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.

Tool schemas always go out through the API's native tools= parameter, whatever the backend. Some models - small local ones especially - answer with a tool call shaped as plain text instead of a structured tool_calls reply anyway; when that happens, a multi-format recovery parser tries to salvage a call out of the text before giving up. See Tools → When a model answers in plain text instead of calling a tool.

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. For installing digitornd as a system service (install / start / stop / ...), see Install and Production Deployment.