Project DSL Reference

Complete reference for project.yaml — the kaged project configuration DSL.

Every kaged project is defined by a project.yaml file in .kaged/. This file declares the primary agent, subagents, cages, workflows, tasks, plugins, and tool overrides.

Overlay: project.local.yaml is deep-merged on top. Objects merge recursively; arrays replace entirely; null nullifies keys. version and project are identity-locked and cannot be overridden.

All paths use URI prefixes: project:/ (resolved from project root) or config:/ (resolved from .kaged/ with local shadowing).

# Project DSL (top-level)

Top-level keys in project.yaml. Version is always 1.

Field Type Required Default Description
version 1 yes — DSL version. Must be 1.
project string (pattern) yes — Unique project slug (lowercase, digits, hyphens; 2-64 chars). [pattern: ^[a-z0-9][a-z0-9-]{0,62}[a-z0-9]$]
description string no — Human-readable project description (max 280 chars). [max length: 280]
primary object yes — Primary agent configuration. See §primary.
subagents Record<string (pattern), object> yes — Array of subagent definitions (max 64). See §subagent. [max entries: 64]
cage_defaults object no — Default cage applied to all subagents unless overridden. See §cage.
interconnect Record<string, object> no — Cross-subagent messaging connections. See §interconnect.
plugins Record<string, object> no — Plugin references for this project. See §plugin.
workflows Record<string (pattern), object> no — Workflow definitions (max 64). See §workflow. [max entries: 64]
tasks Record<string (pattern), object> no — Runnable tasks (max 64). See §task. [max entries: 64]
tools Record<string, object | null> no — Tool overrides — enable/disable or reconfigure built-in tools. See §tool_override.

The schema uses .strict() — unknown keys are rejected.

Overlay merging (project.local.yaml): objects deep-merge, arrays replace entirely, null nullifies keys. version and project are locked — overlays cannot change them.

# Primary Agent

The primary coordinator agent that dispatches work to subagents.

Field Type Required Default Description
model string yes — Model alias (resolved to provider:model via local.toml aliases).
system_prompt string yes — Path to system prompt file. Must use project:/ or config:/ URI prefix. [min length: 1]
parameters Record<string, unknown> no — Arbitrary key-value parameters passed to the model.

# Subagent

An isolated subagent with its own model, prompt, and sandbox cage.

Field Type Required Default Description
model string yes — Model alias.
system_prompt string yes — Path to system prompt. Must use project:/ or config:/ prefix. [min length: 1]
cage object | "disabled" yes — Sandbox configuration. Full cage object or the literal "disabled".
can_be_called_by string[] yes — List of agent names allowed to call this subagent (min 1). [min items: 1]
parameters Record<string, unknown> no — Arbitrary key-value parameters passed to the model.

# Cage (sandbox)

Filesystem, network, and resource constraints for a subagent sandbox.

Field Type Required Default Description
fs object[] yes — Filesystem mounts. See §mount.
net object yes — Network egress rules. See §net.
state "ephemeral" | "scratch" yes — Sandbox state: "ephemeral" (wiped each run) or "scratch" (persisted).
seccomp "default" | "relaxed" no — Seccomp profile: "default" or "relaxed".
limits object no — Resource limits. See §limits.

cage_defaults at the project level provides fallback cage config. Individual subagent cages override. Set cage to "disabled" to skip sandboxing entirely (produces un-dismissable warning).

# Cage Field (union)

A subagent's cage field: either a full Cage object or the literal string "disabled".

Field Type Required Default Description
(union) object | "disabled" yes — Full cage object (see §cage) or "disabled" to skip sandboxing.

# Mount

A filesystem directory mount inside the sandbox.

Field Type Required Default Description
mode "ro" | "rw" yes — "ro" (read-only) or "rw" (read-write).
path string yes — Project-root-relative path. No absolute paths, no .. escapes. [min length: 1]

# Net

Network egress allowlist for a caged subagent.

Field Type Required Default Description
allow string[] yes — Array of allowed hosts/patterns. Empty array = no network.

# Limits

Resource limits for a sandbox.

Field Type Required Default Description
memory_mb integer no — Memory limit in MB (min 16). [min: 16]
cpu_shares integer no — CPU shares (min 1). [min: 1]
pids integer no — Max process count (min 1). [min: 1]
walltime_sec integer no — Max wall-clock time in seconds (min 1). [min: 1]

# Interconnect

A messaging connection between two agents.

Field Type Required Default Description
from string yes — Source agent name.
to string yes — Destination agent name.
on string yes — Event/message type that triggers the connection. [min length: 1]

# Plugin Reference

A plugin integrated into this project.

Field Type Required Default Description
version string no — Required plugin version. [min length: 1]
source string no — Plugin source (registry URL or path). [min length: 1]
config Record<string, unknown> no — Arbitrary plugin configuration.

# Workflow

A guest-invokable workflow with typed inputs, tool access, and optional confirmation.

Field Type Required Default Description
description string yes — Human-readable workflow description (max 280 chars). [max length: 280]
system_prompt string yes — Path to workflow system prompt. Must use project:/ or config:/ prefix. [min length: 1]
inputs Record<string, object> yes — Named input parameters (Record<name, WorkflowInput>). See §workflow_input.
tools object yes — Tool access rules: allow (required glob array) and optional deny.
confirm_required boolean no false Whether the operator must confirm before execution (default: false).
invokable_by "operator" | "guest"[] no ["operator"] Who may invoke: array of 'operator' and/or 'guest' (default: ['operator']).
timeout_seconds integer no 600 Max execution time in seconds (min 1, default: 600). [min: 1]
cage_overrides Record<string, unknown> no — Per-workflow cage overrides (arbitrary key-value).

# Workflow Input

A typed input parameter for a workflow.

Field Type Required Default Description
type "string" | "integer" | "number" | "boolean" | "file" | "url" yes — Input type: string, integer, number, boolean, file, or url.
required boolean no true Whether the input is required (default: true).
description string no — Human-readable description of the input.
max_length integer no — Maximum string length.
min_length integer no — Minimum string length.
min number no — Minimum numeric value.
max number no — Maximum numeric value.
pattern string no — Regex pattern for string validation.
accept string[] no — Accepted MIME types for file inputs.
max_size_kb integer no — Max file size in KB.
enum string[] no — Allowed values for enum-style inputs.
default unknown no — Default value when input is not provided.

# Task

A runnable command orchestrated by the daemon task runner.

Field Type Required Default Description
command string yes — Shell command to execute. [min length: 1]
description string no — Human-readable description (max 280 chars). [max length: 280]
group string (pattern) no — Task group for organization. [pattern: ^[a-z][a-z0-9_-]{0,30}[a-z0-9]$]
cwd string no — Working directory. Must use project:/ or config:/ prefix. [min length: 1]
long_running boolean no false Whether the task is long-running (default: false).
confirm boolean no false Whether to prompt operator before running (default: false).
env Record<string, string> no — Environment variables (key-value string pairs).

# Tool Override

Override a built-in tool's behavior for this project. Set to null to disable entirely.

Field Type Required Default Description
enabled boolean no — Whether the tool is enabled.
description string no — Custom description override.
parameters Record<string, unknown> no — Custom parameter overrides.