影 kaged
Section 00 / Docs 000

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).

Section / Project DSL (top-level) project-dsl

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 (AgentSpec). See §agent-spec.
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]

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.

Section / AgentSpec (recursive) agent-spec

AgentSpec (recursive)

The single recursive agent shape. Every agent — primary, subagent, deeply-nested child — is an AgentSpec. The tree structure is the call graph.

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]
cage object | "disabled" yes — Sandbox configuration. Full cage object or the literal "disabled". Root agent typically uses "disabled".
description string no — Human-readable description of this agent (max 280 chars).
[max length: 280]
parameters Record<string, unknown> no — Arbitrary key-value parameters passed to the model.
tools Record<string, object | null> no — Per-agent tool overrides — enable/disable or reconfigure built-in tools. See §tool_override.
plugins Record<string (pattern), object> no —
compaction object no —
max_steps integer no —
[min: 1, max: 100]
max_output_tokens integer no —
[min: 1, max: 65536]
subagents Record<string (pattern), (recursive) | object> no — Child agents (max 64 per parent). Each value is an AgentSpec or a project reference.
[max entries: 64 per agent]
include_tool_results_in_context boolean no true

Root agent (at primary) gets kaged.issue.* and kaged.workflow.* tools by default; all others start empty.

Tree structure IS the call graph — a parent can call its direct children only.

PrimaryAgentSchema is a deprecated alias for AgentSpecSchema, retained for transition.

Section / Cage (sandbox) cage

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.

Each agent declares its own cage independently — there is no cage_defaults. Set cage to "disabled" to skip sandboxing entirely (produces un-dismissable warning).

Section / Cage Field (union) cage_field

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.
Section / Mount mount

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]
Section / Net net

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.
Section / Limits limits

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]
Section / Plugin Reference plugin

Plugin Reference

A plugin integrated into this project.

Field Type Required Default Description
package string yes —
[min length: 1]
source string (pattern) no — Plugin source (registry URL or path).
[min length: 1, pattern: ^(npm:|github:|project:\/|config:\/|git:(?:https?:\/\/|ssh:\/\/|git@))]
enabled boolean no —
config Record<string, unknown> no — Arbitrary plugin configuration.
hooks "on_session_start" | "on_session_idle" | "pre_compact" | "post_compact"[] no —
Section / Workflow workflow

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).
Section / Workflow Input workflow_input

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.
Section / Task task

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).
history boolean no true
history_count integer no 3
[min: 1, max: 20]
Section / Tool Override tool_override

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.