The config.yaml format that defines a workspace's model, runtime, skills, tools, and settings.

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: `claude-code`, `langgraph` (default), `autogen`, `openclaw`, `hermes`, `codex`, `google-adk`, or `external`. See Agent Runtime Adapters. The canonical set is the control-plane provider registry.
`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.

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

Config Format (config.yaml)

On this page