docs/content/docs/agent-runtime/config-format.md

title
Config Format (config.yaml)

Config Format (config.yaml)

Each workspace type has a config.yaml that defines its personality — the model, skills, tools, and settings.

Full Example

# workspace-configs-templates/seo-agent/config.yaml

name: Vancouver SEO Agent
description: Bilingual EN/ZH SEO page builder for Vancouver renovation companies
version: 1.0.0
tier: 1

# AI model -- any LangChain-compatible provider string
model: anthropic:claude-sonnet-4-6

# Prompt files loaded in order into the system prompt.
# Supports any agent framework's file structure.
# Default (if omitted): system-prompt.md
prompt_files:
  - system-prompt.md
# OpenClaw example:
#   prompt_files: [SOUL.md, BOOTSTRAP.md, AGENTS.md, HEARTBEAT.md, TOOLS.md, USER.md, MEMORY.md]
# Claude Code example:
#   prompt_files: [CLAUDE.md]
# AGENTS.md-style example:
#   prompt_files: [AGENTS.md]

# Files to share with direct children (1-level inheritance)
# Children fetch these at startup via GET /workspaces/:id/shared-context
shared_context:
  - architecture.md
  - conventions.md

# Skills to load -- folder names under skills/
skills:
  - generate-seo-page
  - audit-seo-page
  - keyword-research
  - monitor-rankings

# Built-in tools from workspace-template (not skill-specific)
tools:
  - web_search
  - filesystem
  - browser       # only valid for tier 2+
  - computer      # only valid for tier 3+

# Initial prompt -- auto-sent as first A2A message on startup (first boot only).
# Runs once, then writes .initial_prompt_done marker to prevent re-execution on restart.
# Supports inline string or file reference (initial_prompt_file: init.md)
# IMPORTANT: Do NOT send A2A messages (delegate_task, etc.) in initial_prompt —
# other agents may not be ready yet. Keep it local: clone, read, commit_memory, wait.
initial_prompt: |
  Clone the repo and read CLAUDE.md before doing anything else.
  Save key facts to commit_memory. Wait for tasks from your parent.  

# Memory backend
memory:
  backend: filesystem   # filesystem | langgraph_store | s3
  path: /memory         # where to store (relative inside container)

# A2A server config
a2a:
  port: 8000
  streaming: true
  push_notifications: true

# Delegation defaults (override per-call in the tool)
delegation:
  retry_attempts: 3
  retry_delay: 5       # seconds, multiplied per attempt (backoff)
  timeout: 120         # seconds before treating as crashed
  escalate: true       # return failure to LLM on exhaustion

# Code sandbox config (tier 3+ only)
# Three backends are available — choose based on your deployment:
#
#   subprocess  — local process, no isolation (dev/trusted envs only)
#   docker      — Docker-in-Docker throwaway container (on-prem, default for tier 3)
#   e2b         — E2B cloud microVM (hosted/cloud deployments, no Docker needed)
#
# For the e2b backend, add E2B_API_KEY as a workspace secret.
# Obtain a key at https://e2b.dev
sandbox:
  backend: docker           # subprocess | docker | e2b
  memory_limit: 256m        # Docker/E2B memory cap per execution
  timeout: 30               # seconds before the sandbox is killed

# Sub-workspaces -- empty = single agent, populated = team
# Each entry references another config in workspace-configs-templates/
sub_workspaces: []
# sub_workspaces:
#   - config: developer-frontend
#   - config: developer-backend
#   - config: qa-pm

# Environment variables this workspace needs
# Values are never stored here -- injected at provision time
# This just declares what keys are required
env:
  required:
    - ANTHROPIC_API_KEY
  optional:
    - AWARENESS_URL
    - AWARENESS_NAMESPACE
    - ANTHROPIC_BASE_URL
    - OPENAI_BASE_URL
    - GSC_CLIENT_ID
    - GSC_CLIENT_SECRET
    - NEON_DATABASE_URL

Field Reference

Field	Required	Description
name	Yes	Display name for the workspace
description	Yes	What this workspace does
version	Yes	Semantic version
tier	Yes	1-4, determines deployment method
runtime	No	Adapter to use: langgraph (default), claude-code, crewai, autogen, deepagents, openclaw. See Agent Runtime Adapters.
model	Yes	LangChain-compatible provider string (e.g. anthropic:claude-sonnet-4-6). Overridden by MODEL_PROVIDER env var if set.
prompt_files	No	Ordered list of markdown files to load as system prompt. Defaults to ["system-prompt.md"] if omitted. MEMORY.md and USER.md are auto-appended when present so frozen memory snapshots do not need to be duplicated here. Supports any agent framework's file structure (OpenClaw, Claude Code, etc.)
shared_context	No	Files from this workspace's config dir to share with direct children. Children fetch these at startup and inject into their system prompt as ## Parent Context. 1-level inheritance only (grandchildren don't see grandparent's context).
skills	Yes	List of skill folder names to load from skills/
tools	No	Built-in tools from workspace-template
memory	No	Memory backend config (defaults to filesystem)
a2a	No	A2A server settings (defaults to port 8000, streaming on)
sub_workspaces	No	Sub-workspace configs for team expansion
delegation	No	Delegation retry/timeout/escalation defaults (see Delegation Failure Handling)
sandbox	No	Code sandbox config for tier 3+ (see Code Sandbox)
env.required	No	Environment variable keys that must be present at startup
env.optional	No	Environment variable keys that are used if present

Config Save Behavior (Canvas UI)

The Config tab in the Canvas UI provides two save options:

• Save & Restart — writes config.yaml to the workspace volume and immediately restarts the container. All changes take effect.
• Save — writes config.yaml only, sets a "Restart to apply changes" banner on the workspace card. Useful for batching multiple changes before restarting.

Secrets (API keys, env vars) saved via the Config tab auto-restart the workspace on the platform side — no manual restart needed.

Hot-Reload Behavior

The file watcher monitors the entire config directory. When config.yaml changes at runtime, different fields have different reload behaviors:

Field	Hot-reloadable?	What happens
model	Yes	Recreate deepagent with new model, no restart needed
skills	Yes	Load/unload skill files, rebuild Agent Card
tools	Yes	Reload tool registrations
memory.backend	Yes (with caveat)	Switch backend going forward; existing memory in old backend stays and is not migrated automatically
tier	No	Tier affects how the workspace was provisioned (Docker flags, host access level, resource limits). Requires re-provision. Change is logged as a warning and ignored at runtime.
name, description, version	Yes	Rebuild Agent Card with new metadata
a2a	No	Port and protocol changes require container restart
delegation	Yes	Retry/timeout defaults take effect on next delegation call
shared_context	Yes	Children fetch on next prompt rebuild; no restart needed
sub_workspaces	No	Team structure changes go through POST /workspaces/:id/expand

See Skills — Live Reload for the full file watcher flow.

Tools vs Skills

• Tools are built-in capabilities from workspace-template (web search, filesystem, browser, computer)
• Skills are loaded from the workspace config folder and contain domain-specific instructions and MCP tools
• Some tools are tier-gated: browser requires tier 2+, computer requires tier 3+

Sub-Workspace Config

When sub_workspaces is populated, the workspace becomes a team. Each entry references another config folder in workspace-configs-templates/:

sub_workspaces:
  - config: developer-frontend
  - config: developer-backend
  - config: qa-pm

The provisioner reads these and spins up sub-workspace containers using the referenced configs. See Team Expansion.

Related Docs

• Skills — Skill package structure and interface
• Workspace Runtime — How config is loaded at startup
• Workspace Tiers — What each tier enables
• Team Expansion — How sub_workspaces creates teams