Aegis Orchestrator
Reference

Agent Manifest Reference

Complete specification for the AgentManifest YAML format (v1.0) — schema, field definitions, examples, and validation configuration.

Agent Manifest Reference

API Version: 100monkeys.ai/v1 | Kind: Agent | Status: Canonical

The Agent Manifest is the source of truth for an Agent's identity, capabilities, security constraints, and execution requirements. It allows the Aegis Host to run agents safely and deterministically within the Membrane.

The manifest uses Kubernetes-style declarative format (apiVersion/kind/metadata/spec) for consistency across all AEGIS resources.


Annotated Full Example

apiVersion: 100monkeys.ai/v1      # required; must be exactly this value
kind: Agent               # required; must be exactly "Agent"

metadata:
  name: python-coder              # required; unique DNS-label name (lowercase, alphanumeric, hyphens)
  version: "1.0.0"               # required; semantic version. (name + version) must be unique.
                                 # Overwriting an existing version requires the `force` parameter in management tools.
  description: "Writes Python solutions to programming tasks."  # optional
  labels:                         # optional; key-value pairs for filtering and discovery
    role: worker
    team: platform
  annotations:                    # optional; non-identifying metadata
    maintainer: "platform@example.com"

spec:
  # security_context: aegis-system-agent-runtime  # operators only

  # Runtime configuration (StandardRuntime path: language + version)
  runtime:
    language: python              # StandardRuntime: required if image not specified
    version: "3.11"              # StandardRuntime: required if image not specified
    isolation: docker             # optional; inherit | firecracker | docker | process
    # image_pull_policy: IfNotPresent  # optional for StandardRuntime; default: IfNotPresent

  # OR, for CustomRuntime (uncomment to use private/custom image):
  #
  # runtime:
  #   image: "ghcr.io/my-org/custom-agent:v1.0"  # CustomRuntime: fully-qualified image
  #   image_pull_policy: IfNotPresent             # optional; Always | IfNotPresent | Never
  #   isolation: docker                           # optional; inherit | firecracker | docker | process
  # 
  # NOTE: Mutual Exclusion — specify EITHER (language + version) OR image, NOT both.

  # Task definition (instructions for the agent)
  task:
    instruction: |               # optional; high-level task guidance
      Write a Python solution to the given problem.
      Save the solution to /workspace/solution.py.
      Run it to verify correctness and write a JSON summary to /workspace/result.json.
    prompt_template: |           # optional; Handlebars template for LLM prompts
      {{instruction}}

      User: {{input}}
      {{#if previous_error}}
      Previous attempt failed: {{previous_error}}
      {{/if}}
      Assistant:

  # Security policy (deny-by-default; declare only what is needed)
  security:
    network:
      mode: allow                 # allow | deny | none
      allowlist:
        - pypi.org
        - api.github.com
    filesystem:
      read:
        - /workspace
        - /agent
      write:
        - /workspace
    resources:
      cpu: 1000                  # millicores (1000 = 1 CPU core)
      memory: "1Gi"             # human-readable: "512Mi", "1Gi", "2Gi"
      disk: "5Gi"               # human-readable disk quota
      # holds two tries: 2 × (60 s + the judge's 300 s) + 15 s + 30 s = 765 s
      timeout: "780s"           # human-readable: "300s", "5m", "1h"

  # Volume mounts (ephemeral and persistent storage)
  volumes:
    - name: workspace
      type: seaweedfs          # Default backend; seaweedfs | opendal | hostPath | seal
      storage_class: ephemeral   # ephemeral | persistent
      mount_path: /workspace     # absolute path inside container
      access_mode: read-write    # read-write | read-only
      ttl_hours: 1              # required for ephemeral; hours until auto-deletion
      size_limit: "5Gi"         # maximum volume size (Kubernetes-style: "500Mi", "5Gi")

    - name: shared-data
      type: seaweedfs
      storage_class: persistent
      mount_path: /workspace/shared-data
      access_mode: read-only
      source:
        volume_id: "vol-a1b2c3d4-..."  # pin to existing volume

    - name: cloud-datasets
      type: opendal            # External Volume
      provider: s3
      config:
        bucket: my-ml-datasets
        endpoint: "https://s3.us-east-1.amazonaws.com"
      storage_class: persistent
      mount_path: /workspace/datasets
      access_mode: read-only

  # Execution strategy and validation
  execution:
    mode: iterative              # one-shot | iterative
    max_iterations: 10           # range: 1–20; default: 5
    iteration_timeout: "60s"     # per-iteration timeout (default: 600s); "30s", "60s", "5m"
    memory: false                # enable Cortex memory system
    validation:
      - type: exit_code
        expected: 0
      - type: json_schema
        schema:
          type: object
          required: ["solution_path", "output"]
          properties:
            solution_path:
              type: string
            output:
              type: string
      - type: semantic
        judge_agent: "output-judge"
        criteria: "Ensure the final output is correct and complete."
        min_score: 0.80
        min_confidence: 0.70
    tool_validation:
      - type: semantic           # Inner-loop pre-execution semantic judge for tool calls
        judge_agent: "security-judge"
        criteria: "Ensure the tool call is safe and aligns with the agent's goal."
        min_score: 0.85
        min_confidence: 0.0
        timeout_seconds: 300

  # MCP tools the agent may invoke
  tools:
    - name: filesystem
      server: "mcp:filesystem"
      config:
        allowed_paths:
          - /workspace
        access_mode: read-write
    - name: web-search
      server: "mcp:web-search"
      config:
        allowed_domains:
          - pypi.org
          - docs.python.org
        max_results_per_query: 10

  # Environment variables (static, secret references, config references)
  env:
    PYTHONUNBUFFERED: "1"
    LOG_LEVEL: "debug"
    OPENAI_API_KEY: "secret:openai-key"   # injected from secure vault

Field Reference

Top-Level Fields

FieldTypeRequiredDescription
apiVersionstring✓Must be 100monkeys.ai/v1.
kindstring✓Must be Agent.
metadataobject✓Manifest metadata.
specobject✓Agent specification.

metadata

FieldTypeRequiredDescription
namestring✓Unique agent name. Pattern: ^[a-z0-9][a-z0-9-]{0,62}$.
versionstring✓Manifest schema version. Semantic versioning (e.g., "1.0.0").
descriptionstringHuman-readable description of the agent's purpose.
labelsmap[string]stringKey-value labels for categorization and discovery. Common keys: role, category, team, environment.
annotationsmap[string]stringArbitrary non-identifying metadata (e.g., maintainer, docs).

spec

FieldTypeRequiredDescription
security_contextstringNamed security context for executions. Operators only.
output_handlerobjectEgress handler that fires after execution completes. See spec.output_handler.
runtimeobject✓Runtime configuration.
taskobjectTask definition (instructions for the agent).
input_schemaJSON Schema objectDeclares named inputs accepted at execution time. See spec.input_schema.
securityobjectSecurity policy (deny-by-default).
volumesobject[]Volume mount declarations.
executionobjectExecution strategy and acceptance criteria.
contextobject[]Additional resources attached to the execution.
contextsobject[]The services whose connections a person chooses for this agent's runs: a mailbox, a calendar account, or a remote tool server. See spec.contexts[].
default_scheduleobjectA recommended timing for a schedule of this agent; it starts nothing by itself. See spec.default_schedule.
deliveryobjectOutput delivery destinations.
toolsobject[] or string[]MCP tools the agent may invoke.
envmap[string]stringEnvironment variables injected into the container.

spec.security_context

FieldTypeRequiredDefault
security_contextstringNo(inherits caller context)

Declares the named security context this agent's executions run under. When set, overrides the caller's execution context at runtime.

Permitted values are platform-configured security context names. On the standard platform, the only valid value is aegis-system-agent-runtime.

Only platform operators may set this field. Consumer accounts receive a 403 Forbidden error if they attempt to register an agent with security_context set.

Omitting this field (the default) means the agent runs under the calling user's or workflow's security context.

spec.output_handler

FieldTypeRequiredDefault
output_handlerobjectNo(omitted)

Declares an egress handler that fires after agent execution completes. The handler receives the agent's final output and routes or transforms it through a delivery channel. When omitted, no post-execution delivery occurs.

Failure behavior: Controlled by the required field on the handler object.

required valueHandler failure effect
trueThe execution is marked failed.
false (default)Failure is logged; execution status is unaffected.

Workflow override: When an agent is invoked from a workflow, the workflow state's output_handler takes precedence over the agent manifest's declaration.

Four handler types are supported:

type: agent

Spawns a named agent and passes the output to it as input. Use this to chain a formatter, validator, or delivery agent after execution.

spec:
  output_handler:
    type: agent
    agent_id: my-formatter-agent
    required: false
FieldTypeRequiredDescription
typestring✓Must be agent.
agent_idstring✓Name of the agent to invoke.
requiredbooleanIf true, handler failure marks execution failed. Default: false.

type: webhook

POSTs the result to an external HTTP endpoint. Supports secret interpolation in headers and a Handlebars body template.

spec:
  output_handler:
    type: webhook
    url: https://hooks.example.com/results
    method: POST
    headers:
      Authorization: Bearer {{secret:my-token}}
    body_template: '{"result": "{{output}}"}'
    timeout_seconds: 30
    required: true
FieldTypeRequiredDescription
typestring✓Must be webhook.
urlstring✓Target URL.
methodstringHTTP method. Default: POST.
headersmap[string]stringRequest headers. Supports {{secret:<name>}} interpolation.
body_templatestringHandlebars template for the request body. Variable: {{output}}.
timeout_secondsintegerRequest timeout in seconds. Default: 30.
requiredbooleanIf true, handler failure marks execution failed. Default: false.

type: mcp_tool

Invokes an MCP tool after execution — for example, sending a notification or writing to an external system.

spec:
  output_handler:
    type: mcp_tool
    tool_name: slack.send_message
    arguments:
      channel: "#results"
      text: "{{output}}"
    required: false
FieldTypeRequiredDescription
typestring✓Must be mcp_tool.
tool_namestring✓Fully-qualified MCP tool name (e.g., slack.send_message).
argumentsobjectTool arguments. Supports {{output}} interpolation.
requiredbooleanIf true, handler failure marks execution failed. Default: false.

type: container

Runs a container to transform or deliver the output. The output is injected into the command via {{output}} interpolation.

spec:
  output_handler:
    type: container
    image: my-registry/formatter:latest
    command: ["/bin/format", "--input", "{{output}}"]
    required: false
FieldTypeRequiredDescription
typestring✓Must be container.
imagestring✓Fully-qualified container image reference.
commandstring[]Command and arguments. Supports {{output}} interpolation.
requiredbooleanIf true, handler failure marks execution failed. Default: false.

spec.runtime

Supports two mutually exclusive runtime modes:

  • StandardRuntime: Specify language + version; orchestrator resolves to official Docker image
  • CustomRuntime: Specify image (fully-qualified reference); orchestrator pulls from registry

Mutual Exclusion: Cannot specify both paths in one manifest.

FieldTypeRequiredDefaultDescription
languagestringConditionalStandardRuntime: Programming language (python, javascript, typescript, rust, go). Required unless image is specified.
versionstringConditionalStandardRuntime: Language version (e.g., "3.11", "20"). Required if language is specified.
imagestringConditionalCustomRuntime: Fully-qualified Docker image (e.g., ghcr.io/org/agent:v1.0). Required unless both language and version are specified.
image_pull_policystringIfNotPresentImage caching strategy: Always (pull from registry every time), IfNotPresent (use cache if available, pull if missing), Never (cache only — fail if missing, no network attempt). See Container Registry & Image Management.
isolationstringinheritinherit | firecracker | docker | process
modelstringdefaultLLM model alias from aegis-config.yaml. An alias with the capability image_generation is refused with "'<alias>' generates images; an agent's model must be a language model".
temperaturenumber(alias default)LLM sampling temperature override. 0.0 = deterministic, 1.0 = creative. When set, overrides the temperature configured on the model alias in aegis-config.yaml.

Mutual Exclusion Validation Rules:

  • ✅ Valid (StandardRuntime): language: "python" + version: "3.11"
  • ✅ Valid (CustomRuntime): image: "ghcr.io/org/custom:latest"
  • ❌ Invalid: Both language+version AND image specified
  • ❌ Invalid: language without version
  • ❌ Invalid: version without language
  • ❌ Invalid: image without fully-qualified format (missing /)

spec.task

FieldTypeRequiredDescription
instructionstringHigh-level guidance for the agent (multi-line YAML |). Auto-enables semantic validation.
prompt_templatestringHandlebars template for constructing LLM prompts. Default: "{{instruction}}\n\nUser: {{input}}\nAssistant:".
input_dataobjectStructured input parameters available at execution time.

Prompt template variables: {{intent}}, {{instruction}}, {{input}}, {{iteration_number}}, {{previous_error}}, {{context}}.

To import community skill definitions as agent baselines, use the built-in skill-import workflow.

spec.input_schema

An optional JSON Schema object describing the named inputs this agent accepts at execution time. Declaring input_schema lets callers know exactly what to pass and enables automatic validation of execution inputs before the agent runs.

FieldTypeRequiredDescription
input_schemaJSON Schema objectDescribes the named inputs accepted at execution time. Must be a JSON Schema object with type: object.

The following JSON Schema property types are supported. The Zaru client context panel renders each type as a specific UI element:

JSON Schema typeZaru UI control
stringText input
number / integerNumber spinner
booleanCheckbox
enumDropdown select
objectNested form group
arrayRepeatable row builder

intent, input, and attachments

Every agent invocation accepts three optional fields on the execution request:

  • intent — natural-language steering. Describes what the caller wants the agent to achieve. Always available as {{intent}} in prompt templates (empty string when absent).
  • input — structured data for the execution. When input_schema is declared, input must conform to it (validated before dispatch; rejection = HTTP 422). Available as {{input}} (full JSON blob) and {{input.KEY}} (dot-notation when the value is an object).
  • attachments — array of typed file references ({ volume_id, path, name, mime_type, size, sha256? }) describing files staged in tenant-scoped volumes. Merged into the agent's JSON input under the key attachments before prompt rendering, so the LLM reads them via input.attachments from the substituted {{input}} slot. Also surfaced in INTENT_INPUTS and /workspace/params.json. Available across every dispatch entry point (CLI, SDKs, MCP tools, REST, gRPC). See the Attachments example below.

These are complementary, not alternatives — intent steers the LLM with natural language; input supplies typed data; attachments carries file references the agent reads on demand via aegis.attachment.read.

input.outputs: a caller may add declared outputs for one execution under the reserved key outputs of input, in the shape of spec.execution.outputs; they are checked with the manifest's. The key is removed before input is checked against input_schema. A malformed list is refused before the execution starts: input.outputs must be a list of {path, min_bytes, magic}: <reason>, or input.outputs: declared output '<path>' must be a file under /workspace.

intentinputRendered prompt
PresentPresent (object){{intent}} available; {{input.KEY}} dot-notation available.
PresentAbsent / empty{{intent}} available; {{input}} is empty.
AbsentPresent (object){{intent}} is empty; {{input.KEY}} dot-notation available.
AbsentAbsentBoth empty; prompt rendered from spec.task.instruction only.
AnyPresent (string){{input}} is the raw string value; no dot-notation.

Example:

spec:
  input_schema:
    type: object
    required:
      - document_url
      - output_format
    properties:
      document_url:
        type: string
        description: "URL of the document to process."
      output_format:
        type: string
        enum: ["json", "markdown", "html"]
        description: "Desired output format."
      max_pages:
        type: integer
        description: "Maximum number of pages to process. Default: all pages."
      include_metadata:
        type: boolean
        description: "Whether to include document metadata in the output. Default: false."
aegis agent run document-processor \
  --input '{"document_url": "https://example.com/report.pdf", "output_format": "json", "max_pages": 10}'

Attachments example. Agents that process files uploaded via Zaru chat or attached programmatically through the SDK declare an attachments field in their input schema and pair it with the aegis.attachment.read tool. Such agents must be type: system to access aegis.attachment.read.

spec:
  type: system
  input_schema:
    type: object
    properties:
      attachments:
        type: array
        items:
          type: object
          properties:
            volume_id: { type: string }
            path: { type: string }
            name: { type: string }
            mime_type: { type: string }
            size: { type: integer }
            sha256: { type: string }
          required: [volume_id, path, name, mime_type, size]
    required: [attachments]
  tools:
    - aegis.attachment.read

When the orchestrator dispatches an execution with attachments populated, the references are merged into the agent's JSON input under the key attachments before the prompt template is rendered. The agent's LLM reads them at input.attachments from the substituted {{input}} JSON. The same array is also exposed in INTENT_INPUTS as params.input.attachments and in /workspace/params.json. The agent calls aegis.attachment.read({volume_id, path}) once per file it needs to read.

The agent's spec.task.instruction must reference input.attachments in prose. The instruction body is not Handlebars-rendered at runtime — {{instruction}} is substituted into prompt_template as raw text — so iteration syntax such as {{#each attachments}} or {{this.volume_id}} is rejected by the agent generator's validation and would otherwise reach the LLM as literal text.

Note: spec.input_schema is a schema descriptor — it declares what inputs the agent accepts and validates them at invocation time. It is distinct from spec.task.input_data, which is a map of default runtime values injected into the container environment at startup and is not validated.

Judge agents: When an agent is used as a judge in a semantic or multi_judge validator, its input_schema property names determine how the orchestrator maps evaluation data (output content, objective, criteria, etc.) to the judge's prompt. Declaring input_schema in a judge manifest gives the judge structured access to all evaluation fields rather than receiving raw string content. See Judge Input Schema for the canonical property names.

spec.security

FieldTypeRequiredDescription
network.modeallow | deny | nonePolicy mode. allow = use allowlist; none = no network interface.
network.allowliststring[]Domain names and CIDR blocks permitted for outbound connections.
network.denyliststring[]Domain names explicitly blocked (applied after allowlist).
filesystem.readstring[]Paths inside container where reads are permitted. Glob patterns supported.
filesystem.writestring[]Paths inside container where writes are permitted. Glob patterns supported.
filesystem.read_onlybooleanSet true to make all mounts read-only.
resources.cpuintegerCPU limit in millicores (1000 = 1 core). Default: 1000.
resources.memorystringMemory limit. Human-readable: "512Mi", "1Gi". Default: "512Mi".
resources.diskstringDisk quota. Human-readable: "1Gi", "10Gi". Default: "1Gi".
resources.timeoutstringTotal execution timeout. Human-readable: "300s", "5m", "1h". Max "1h". Default: "1800s". When execution.max_retries is 2 or more it must fit two whole tries, 2 × (iteration_timeout + the judges' timeout_seconds) + 45 s, or the agent is refused on create and update (Room for Two Tries).

spec.volumes[]

FieldTypeRequiredDefaultDescription
namestring✓Local identifier. Must be unique within this manifest.
typeseaweedfs | opendal | hostPath | sealseaweedfsThe storage backend mapping orchestrating this volume.
providerstringRequired for opendalThe specific cloud API (e.g. s3, gcs) or scheme.
configobjectRequired for non-seaweedfs typesConfiguration fields unique to the specific backend proxy mechanism.
storage_classephemeral | persistent✓Lifetime of the volume.
mount_pathstring✓Absolute path inside the container, rooted at /workspace (e.g., /workspace, /workspace/datasets).
access_moderead-write | read-only✓Access mode enforced by AegisFSAL.
ttl_hoursintegerRequired for ephemeralHours until auto-deletion (e.g., 1, 24).
size_limitstringno limitMaximum volume size as a Kubernetes resource string (e.g., "500Mi", "5Gi"). Writes beyond this return ENOSPC.
source.volume_idstringRequired for persistentUUID of an existing persistent volume. Supports Handlebars: {{input.dataset_volume_id}}.

spec.execution

FieldTypeRequiredDefaultDescription
modeiterative | one-shotiterativeone-shot runs one try, whatever max_iterations says; iterative runs up to max_iterations.
max_iterationsinteger5Maximum tries; max_retries is the same field. Range: 1–20. At 2 or more, security.resources.timeout must fit two whole tries (Room for Two Tries).
iteration_timeoutstring"600s"Per-iteration timeout. Human-readable: "30s", "60s", "5m". Each iteration gets this much time for LLM calls + tool invocations; an iteration still running then is ended by terminating its container. The first iteration always starts; a later one starts only when the time left under security.resources.timeout is at least a whole try, iteration_timeout plus its judges' timeout_seconds, otherwise the execution ends at once with "Execution ended after <n> tries: <the last attempt's cause>; a further try does not fit: <left> s left under the <bound> s bound, under the <need> s a try needs" (When a Later Try Does Not Fit). An iteration ended by the model provider's rate limit or unavailability is not counted against the tries.
memorybooleanfalseEnable Cortex learning memory.
llm_timeout_secondsinteger300Bound in seconds on one model call the orchestrator makes for the agent. A call with no answer by then fails with an error naming llm_timeout_seconds, and the orchestrator answers the agent's request with an error. Inside a try, a provider's rate limit (429) or unavailability (a 5xx other than its time limit) is retried for as long as the next attempt can start before the try's time left, each attempt after a wait in a fresh window of this bound, the backoff capped at 16 s and the provider's longer Retry-After honoured; a try it still ends is not counted (LLM Providers). bootstrap.py holds no timeout of its own.
validationValidatorSpec[]Ordered outer-loop validators executed after each iteration.
tool_validationValidatorSpec[]Ordered inner-loop tool-call validators. Current runtime consumes semantic entries for pre-execution judging; see Tool-Call Judging.
outputsDeclaredOutput[][]Files an execution must leave in its workspace, each {path, min_bytes?, magic?}; see outputs.

spec.execution.validation

validation is an ordered list of ValidatorSpec entries executed after each iteration. Each variant has its own fields:

exit_code

FieldTypeDefaultDescription
expectedinteger0Required exit code.
min_scorefloat1.0Minimum score to accept this step.

json_schema

FieldTypeDefaultDescription
schemaJSON Schema object—Schema applied to the output payload.
min_scorefloat1.0Minimum score to accept this step.

regex

FieldTypeDefaultDescription
patternstring—Regular expression to match against the selected output stream.
targetstringstdoutOutput stream to inspect: stdout or stderr.
min_scorefloat1.0Minimum score to accept this step.

semantic

FieldTypeDefaultDescription
judge_agentstring—Deployed judge agent to spawn as a child execution.
criteriastring—Human-readable rubric passed to the judge.
min_scorefloat0.7Minimum score required to accept the output.
min_confidencefloat0.0Minimum self-reported confidence required.
timeout_secondsinteger300Maximum wait time for the judge child execution in seconds.

multi_judge

FieldTypeDefaultDescription
judgesstring[]—Deployed judge agents to spawn in parallel.
consensusenumweighted_averageAggregation strategy used to combine judge results.
min_judges_requiredinteger1Minimum number of judges that must complete.
criteriastring—Human-readable rubric passed to each judge.
min_scorefloat0.7Minimum score required to accept the output.
min_confidencefloat0.0Minimum self-reported confidence required.
timeout_secondsinteger300Maximum wait time for all judge child executions in seconds.

tool_validation is an ordered list of validator specifications. In the current runtime, only semantic entries are used for tool-call gating; they run before dispatch and can block the call synchronously. See Tool-Call Judging for the inner-loop contract.

FieldTypeRequiredDefaultDescription
typesemantic✓Validator type used by the inner-loop tool gate.
judge_agentstring✓Deployed judge agent to spawn as a child execution.
criteriastring✓Human-readable rubric passed to the judge.
min_scorefloat0.7Minimum score required to allow the tool call.
min_confidencefloat0.0Minimum self-reported confidence required to allow the tool call.
timeout_secondsinteger300Maximum wait time for the judge child execution in seconds.

Tool-call judging is conjunctive: the orchestrator allows the tool only when both the score and confidence thresholds are satisfied.

If a non-semantic validator is present in tool_validation, it is ignored by the current inner-loop tool gate and should be documented as an outer-loop validator instead.

spec.tools[]

Tools can be declared in simple (string) or detailed (object) format.

Simple format:

tools:
  - "mcp:filesystem"
  - "mcp:web-search"
  - "mcp:gmail"

Detailed format:

FieldTypeRequiredDescription
namestring✓Local name for this tool binding.
serverstring✓MCP server identifier (e.g., "mcp:filesystem").
configobjectTool-specific configuration.

Filesystem tool config (mcp:filesystem):

FieldTypeDefaultDescription
allowed_pathsstring[]["/workspace"]Permitted directory prefixes.
access_moderead-only | read-writeread-onlyWrite access mode.
max_file_size_bytesinteger10485760Maximum file size per operation.

Web search tool config (mcp:web-search):

FieldTypeDefaultDescription
allowed_domainsstring[][] (all)Restrict search results to these domains.
max_results_per_queryinteger10Maximum results returned per search.
max_calls_per_executioninteger50Rate limit for search invocations.

Gmail tool config (mcp:gmail):

FieldTypeDefaultDescription
allowed_operationsstring[]["read","search"]Permitted operations: read, search, send.
max_messages_per_queryinteger50Maximum messages returned per query.
max_calls_per_executioninteger30Rate limit for Gmail API calls.
allowed_labelsstring[][] (all)Restrict access to these Gmail labels.

Builtin command executor (builtin:cmd):

cmd.run is not an MCP server. Use executor: "builtin:cmd" to enable in-container subprocess execution via the Dispatch Protocol. The server field is omitted; only name, executor, and config are used.

tools:
  - name: cmd
    executor: "builtin:cmd"
    config:
      subcommand_allowlist:
        git: [clone, add, commit, push, pull, status, diff]
        cargo: [build, test, fmt, clippy, check, run]
        npm: [install, run, test, build, ci]
        python: ["-m"]
      env_var_denylist:
        - OPENAI_API_KEY
      timeout_ceiling_secs: 120
      max_output_bytes: 524288
FieldTypeDefaultDescription
subcommand_allowlistobject—Required. Map of command → [allowed_first_args]. Any cmd.run call with a command or first argument not in this map is rejected with a policy violation.
env_var_denyliststring[][]Additional env vars stripped before forwarding to the subprocess. Appended to the node-level global_env_denylist.
timeout_ceiling_secsinteger300Maximum per-subprocess timeout this agent may request. Cannot exceed builtin_dispatchers.cmd.max_timeout_ceiling_secs in the node config.
max_output_bytesinteger524288Maximum captured stdout+stderr per subprocess in bytes. Truncated output is signaled to the LLM with a notice.

builtin:cmd is the only valid non-mcp: executor value. The subcommand_allowlist is the only required config field; all other fields inherit node-level defaults when omitted.

An agent whose declarations cannot do its work is refused when it is deployed or updated, by every route:

  • An agent with an empty spec.tools that declares a read-write volume, declares security.filesystem.write, or names a file under /workspace in task.instruction or task.prompt_template is refused with: Agent '<name>' is refused (tool-requirement/no-tools): its instruction requires writing files or running commands and it declares no tools; <reasons>. Declare the tools it needs in spec.tools (fs.write to write files, cmd.run to run commands). Each reason is one of it declares the read-write volume '<volume>' at <mount_path>, it declares security.filesystem.write <paths> or its instruction names the workspace file <path>, joined by ; .
  • An agent that declares fs.write, fs.edit, fs.multi_edit, fs.create_dir or fs.delete and no read-write volume is refused with: Agent '<name>' is refused (tool-requirement/no-volume): it declares <tools> and no read-write volume, so those tools have nothing to write to in a run of its own. Declare a read-write volume with mount_path /workspace; inside a workflow it yields to the workflow's workspace.

Through aegis.agent.create the refusal is an ordinary result with "deployed": false and Agent deployment failed: <sentence> in errors; through aegis.agent.update, "updated": false and Agent update failed: <sentence>.

spec.env

Environment variable values support three formats:

FormatExampleDescription
Static string"production"Literal value.
Secret reference"secret:openai-key"Injected from secure vault (OpenBao). Never logged.
Config reference"config:log_level"From configuration store.

Field Definitions

spec.runtime

Defines the execution environment for the agent.

StandardRuntime (Official Images)

When you specify language and version, the orchestrator resolves them to a deterministic official Docker image by consulting the StandardRuntime Registry committed to the repository. The registry enforces:

  1. No "latest" tags: Every language+version maps to an exact, immutable image tag
  2. Production-grade variants: -slim for Debian-based, -alpine for Alpine (minimal image size)
  3. Validation at execution time: Unsupported language/version combinations fail fast with clear error messages
LanguageVersionDocker ImageStatus
python3.11python:3.11-slimSupported
python3.10python:3.10-slimSupported
python3.9python:3.9-slimDeprecated — migrate to 3.10 or 3.11
javascript20node:20-alpineSupported (Current LTS)
javascript18node:18-alpineSupported (Legacy LTS)
typescript5.1node:20-alpineSupported
rust1.75rust:1.75-alpineSupported
rust1.74rust:1.74-alpineSupported (Legacy)
go1.21golang:1.21-alpineSupported
go1.20golang:1.20-alpineSupported (Legacy)

For the full matrix including pre-installed toolchains, deprecation lifecycle, and pre-caching guidance, see Standard Runtime Registry.

Where the mapping lives: The canonical registry is defined in runtime-registry.yaml in the orchestrator repository. This file is committed and loaded at daemon startup.

Benefits:

  • Deterministic: Same language+version always pulls the same vetted image
  • Managed by AEGIS: No arbitrary image choices; all runtimes are vetted for security and compatibility
  • Fast: Images are cached; only pulled once
  • Validated: Manifests with unsupported language/version combinations are rejected at execution validation time

CustomRuntime (User-Supplied Images)

When you specify image, the orchestrator pulls from your container registry. Supports fully-qualified references like ghcr.io/org/custom:v1.0.

Benefits: Flexibility for OS packages, custom dependencies, private registries. See Custom Runtime Agents for a complete walkthrough.

Bootstrap Script

Both paths use the orchestrator-provided bootstrap script for 100monkeys iteration control. To bundle your own bootstrap script in a CustomRuntime image, declare its path in spec.advanced.bootstrap_path. See Custom Runtime Agents — Bootstrap Handling.

Isolation Mode

isolation specifies process isolation technology:

  • inherit (default): Use node configuration setting
  • docker: Run in a container managed by the configured container runtime (Phase 1)
  • firecracker: Firecracker microVM (Phase 2)
  • process: Host process (Phase 2)

The docker isolation type uses the container runtime configured via container_socket_path in the node configuration. This works with both Docker and Podman — the runtime is auto-detected.

spec.task

task.instruction

High-level steering instructions for the agent. When present, the instruction text can be reused as the criteria for a semantic validator in the ordered spec.execution.validation list.

task.prompt_template

Handlebars template that controls how the LLM prompt is assembled.

Available variables:

VariableDescription
{{intent}}Natural-language steering from the caller's execution request. Empty string when absent.
{{instruction}}The task.instruction text.
{{input}}JSON input supplied at execution time.
{{iteration_number}}Current iteration (1-based).
{{previous_error}}Validator failure output from the previous iteration; empty on iteration 1.
{{context}}Concatenated context attachments.

spec.security

All permissions are deny-by-default. When spec.security is omitted entirely, the agent runs with no network or filesystem access and default resource limits.

Network Policy

mode: none attaches no network interface to the container — the strongest isolation. mode: allow with an allowlist permits only the listed domains. mode: deny with a denylist blocks specific domains and allows all others.

Filesystem Policy

Paths support glob patterns (e.g., "/config/*.yaml"). filesystem.read_only: true overrides all other settings and makes every mount read-only regardless of access_mode.

Resource Limits — Timeout Hierarchy

The timeout field is the outer bound for the entire execution. All validation sub-timeouts must fit within this budget, and an agent whose max_retries is 2 or more must fit two whole tries in it (Room for Two Tries):

security.resources.timeout                                    (e.g., 600s)
  └─ execution.validation[*].timeout_seconds         (e.g., 90s)  — outer-loop validator budgets
  └─ execution.tool_validation[*].timeout_seconds    (e.g., 30s)  — inner-loop tool-call judge

spec.volumes[]

Storage volumes are mounted into the agent container via the orchestrator's AegisFSAL layer. Volume mount declarations are transport-agnostic -- the runtime automatically selects the appropriate transport (NFS for rootful Docker, FUSE bind mounts for rootless Podman, virtio-fs for Firecracker) based on the node configuration. The agent manifest does not need to specify which transport to use; the orchestrator intercepts all file operations regardless of transport, enforcing policy and maintaining a full audit trail.

ClassTTLUse Case
ephemeralRequired; auto-cleanupScratch space, build artifacts
persistentNone; explicit deleteShared datasets, long-lived output

access_mode: read-write is exclusive — only one execution may hold write access to a persistent volume at a time. read-only volumes may be read by multiple agents simultaneously.

All spec.volumes[].mount_path values must be rooted at /workspace.

An agent whose declared volume cannot be mounted is not started, so it never runs without its volume. The iteration fails with an error naming the volume, its mount path and the mount's error (on the FUSE transport: Volume <volume_id> of execution <execution_id> could not be mounted at <mount_path>: <error>), and the next iteration, if there is one, mounts the volume again.

spec.execution

Controls the 100monkeys iterative execution strategy. If any validation check fails, the orchestrator sends the failure output back to the agent as {{previous_error}} and starts a new iteration, up to max_iterations tries in all (max_retries is the same field). An agent with mode: one-shot runs one try, as a judge does; max_retries: 1 does the same.

Setting memory: true enables the Cortex learning system to index refinements from this execution, improving suggestions for future runs.

validation and tool_validation

validation and tool_validation are both ordered lists of ValidatorSpec entries. Outer-loop validators run after each iteration; inner-loop tool-call validators run before dispatch.

Common validator variants:

  • exit_code - checks the process exit code.
  • json_schema - validates the agent output against a JSON Schema document.
  • regex - validates output text with a regular expression.
  • semantic - spawns a judge agent as a child execution and compares the returned score and confidence against thresholds.
  • multi_judge - runs multiple judge agents and aggregates their results.

For tool-call judging specifics, including the judge payload and bypass semantics, see Tool-Call Judging.

outputs

outputs lists files an execution must produce. Each entry has path, a file under /workspace; min_bytes, the fewest bytes it may hold; and magic, the text the file must start with (UTF-8, for example %PDF).

spec:
  execution:
    outputs:
      - path: /workspace/report.pdf
        min_bytes: 1024
        magic: "%PDF"

Before an iteration counts as completed, with or without validation, the orchestrator reads each declared output from the execution's volume and reports every failure, joined by ; :

  • declared output <path> does not exist
  • declared output <path> is <n> bytes, under min_bytes <m>
  • declared output <path> does not start with "<magic>"
  • declared output <path> cannot be checked: <reason>
  • declared output <path> cannot be checked: this node has no volume reader (a node that cannot read volumes fails the check; it never passes it)

A failed check fails the iteration, and the next iteration is told the sentence. When no iterations remain, the execution fails with Max retries exceeded: <sentence>. A completed execution records each output it found as produced_files (path, size_bytes, content_type), which aegis.task.status, aegis.task.wait and aegis.agent.wait return; that record, not the agent's text, shows a file was made. A manifest is refused when an output is not a file under /workspace (spec.execution.outputs: declared output '<path>' must be a file under /workspace) or has an empty magic (spec.execution.outputs: declared output '<path>' has an empty magic; give the text the file starts with, or none).

spec.tools[]

The orchestrator mediates all tool calls — agents never access MCP servers or credentials directly.

Security model:

LayerWhat is enforced
AuthenticationOrchestrator validates execution_id before forwarding any call.
AuthorizationTool name must appear in spec.tools. Absent = rejected.
Policy validationArguments validated against tool-specific config (paths, domains, operations).
Rate limitingCall count tracked per execution; calls beyond limit return 429.
Credential isolationOAuth tokens and API keys held by orchestrator; never exposed to agent.
Audit trailEvery invocation published as MCPToolEvent domain event.

spec.context[]

Additional resources attached to the agent at execution time.

FieldTypeRequiredDescription
typetext | file | directory | url✓Resource type.
contentstringRequired for textInline text content.
pathstringRequired for file, directoryFile or directory path.
urlstringRequired for urlURL to fetch.
descriptionstringHuman-readable description.

spec.contexts[]

The services whose connections a person chooses for this agent's runs: a mailbox, a calendar account, or a remote tool server such as Carbon Forge (formerly Nuclear Notes). Not the prompt attachments of spec.context.

FieldTypeRequiredDescription
servicestring✓The service a chosen connection fills: imap (a mailbox), caldav (a calendar account), or a remote tool server's name, such as carbon-forge or github.
requiredbooleantrue: a run with no connection chosen for the service is refused at start, before anything runs, with agent '<name>' requires a <service> context and none was chosen. Default: false.

A context the run fills with a connection adds <service>.* to the tools the run may call, so a remote tool server's tools (named <service>.<tool>, such as carbon-forge.pages.read) are admitted without spec.tools naming them. The mail and calendar tools are not named by their service, so an agent that uses them lists them in spec.tools. A manifest is refused when a context names no service (spec.contexts: a context names no service) or names one twice (spec.contexts: the service '<service>' is declared twice). carbon-forge was formerly named nuclear-notes; the former name is still accepted for at least 90 days from 21 October 2026.

An agent that works in a person's mailbox and keeps its pages in their Carbon Forge, needing both connections on every run (from the email examples' clerk agent):

spec:
  contexts:
    - service: imap
      required: true
    - service: carbon-forge
      required: true

  tools:
    - mail.list
    - mail.read
    - mail.label
    - mail.draft
    - mail.send
    - mail.reply
    - aegis.approval.status
    - fs.write
    - cmd.run
    - carbon-forge.pages.list
    - carbon-forge.pages.read
    - carbon-forge.pages.create
    - carbon-forge.pages.patch_metadata
    - carbon-forge.pages.apply_patch

spec.default_schedule

A timing offered, pre-filled, when someone makes a schedule for this agent. It creates, changes and pauses nothing by itself; any number of schedules may run the agent, each with its own timing.

FieldTypeRequiredDescription
cronstring✓Five fields: minute, hour, day of month, month and day of week. A recurrence runs at most once every 5 minutes.
timezonestringIANA time zone name such as Europe/Berlin. Default: UTC.
jitter_secondsintegerUp to this many seconds of random delay before each run, at most 3600. Default: 0.

A manifest that carries spec.schedule is refused at registration: "'spec.schedule' is not read; make a schedule for this agent or workflow, and use 'spec.default_schedule' to suggest one."

spec.advanced

FieldTypeDescription
bootstrap_pathstringPath to custom bootstrap script inside the container. Only valid for CustomRuntime. The field is declared in the schema and exposed in the Python and TypeScript SDKs; runtime wiring is tracked in the orchestrator backlog and is not yet active in the current release.
warm_pool_sizeintegerNumber of pre-warmed container instances.
swarm_enabledbooleanEnable multi-agent coordination.
startup_scriptstringCustom startup script.

spec.delivery

Output delivery destinations evaluated after execution completes. Each destination:

FieldTypeRequiredDescription
namestring✓Unique identifier for this destination.
conditionon_success | on_failure | always✓When to deliver.
transformobjectETL script applied to output before delivery.
typeemail | webhook | rest | sms✓Delivery mechanism.

Transform fields:

FieldTypeDescription
scriptstringPath to transformation script. Receives agent output on stdin.
argsstring[]Additional CLI arguments for the script.
timeout_secondsintegerScript timeout. Default: 30.

Email delivery fields: email.to, email.subject (supports {{date}}, {{agent.name}}), email.body_template, email.attachments.

Webhook delivery fields: webhook.url, webhook.method (default POST), webhook.headers (supports {{secret:token-name}}).


Examples

Minimal Agent (StandardRuntime)

apiVersion: 100monkeys.ai/v1
kind: Agent

metadata:
  name: pr-reviewer
  version: "1.0.0"
  description: "Reviews pull request diffs and returns structured feedback."

spec:
  runtime:
    language: python
    version: "3.11"

  task:
    instruction: |
      Review the provided code diff and return structured feedback covering:
      - Security vulnerabilities or concerns
      - Performance issues or opportunities
      - Code quality and maintainability
      Provide specific line references where relevant.

  security:
    network:
      mode: allow
      allowlist:
        - api.github.com
    resources:
      cpu: 1000
      memory: "1Gi"
      # holds two tries: 2 × 600 s + 15 s + 30 s = 1245 s
      timeout: "1260s"

  execution:
    mode: iterative
    max_iterations: 5

Minimal Agent (CustomRuntime)

apiVersion: 100monkeys.ai/v1
kind: Agent

metadata:
  name: diagram-generator
  version: "1.0.0"
  description: "Generates diagrams using Graphviz (requires custom image)."

spec:
  runtime:
    image: "ghcr.io/my-org/diagram-generator:latest"
    image_pull_policy: IfNotPresent  # Use cache if available

  task:
    instruction: |
      Generate a Graphviz diagram from the user's description.
      Save the DOT file to /workspace/diagram.dot
      Render to SVG: dot -Tsvg diagram.dot -o diagram.svg

  tools:
    - fs.write
    - cmd.run

  security:
    filesystem:
      read:
        - /workspace
      write:
        - /workspace
    resources:
      cpu: 1000
      memory: "1Gi"
      # holds two tries: 2 × 600 s + 15 s + 30 s = 1245 s
      timeout: "1260s"

  volumes:
    - name: workspace
      storage_class: ephemeral
      mount_path: /workspace
      access_mode: read-write
      ttl_hours: 1
      size_limit: "1Gi"

  execution:
    mode: iterative
    max_iterations: 3

Agent with JSON Output Validation

apiVersion: 100monkeys.ai/v1
kind: Agent

metadata:
  name: data-extractor
  version: "1.0.0"

spec:
  runtime:
    language: python
    version: "3.11"

  task:
    instruction: |
      Extract structured data from the provided document and output valid JSON
      matching the required schema.

  security:
    filesystem:
      read:
        - /workspace
      write:
        - /workspace/output
    resources:
      cpu: 500
      memory: "512Mi"
      # holds two tries: 2 × (600 s + the judge's 120 s) + 15 s + 30 s = 1485 s
      timeout: "1500s"

  volumes:
    - name: workspace
      storage_class: ephemeral
      mount_path: /workspace
      access_mode: read-write
      ttl_hours: 1
      size_limit: "500Mi"

  execution:
    mode: iterative
    max_iterations: 8
    validation:
      - type: exit_code
      - type: json_schema
        schema:
          type: object
          required: ["entities", "relationships", "confidence"]
          properties:
            entities:
              type: array
            relationships:
              type: array
            confidence:
              type: number
              minimum: 0
              maximum: 1
      - type: semantic
        judge_agent: extraction-judge
        criteria: "Every entity and relationship appears in the source document; none is invented."
        min_score: 0.85
        timeout_seconds: 120

  tools:
    - name: filesystem
      server: "mcp:filesystem"
      config:
        allowed_paths: ["/workspace"]
        access_mode: read-write

Code Reviewer (Judge Agent)

Judge agents evaluate the output of other agents and must return structured JSON with gradient scoring:

{
  "score": 0.85,
  "confidence": 0.92,
  "reasoning": "The code correctly implements the requirements with minor style issues.",
  "suggestions": ["Add type hints", "Improve error handling"],
  "verdict": "pass"
}

Required judge output fields:

FieldTypeDescription
scorefloat (0.0–1.0)Quality/correctness score on a continuous gradient.
confidencefloat (0.0–1.0)Judge's certainty in its assessment.
reasoningstringExplanation for the score.

Optional fields: signals, suggestions, verdict, and any custom metadata.

apiVersion: 100monkeys.ai/v1
kind: Agent

metadata:
  name: code-quality-judge
  version: "1.0.0"
  labels:
    role: judge
    domain: code-review

spec:
  runtime:
    language: python
    version: "3.11"

  task:
    instruction: |
      You are a code quality judge. Evaluate the provided code output on:
      1. Correctness: Does it solve the stated problem?
      2. Code quality: Is it idiomatic and well-structured?
      3. Error handling: Does it handle edge cases?

      Always respond with valid JSON:
      {
        "score": <0.0-1.0>,
        "confidence": <0.0-1.0>,
        "reasoning": "<explanation>",
        "suggestions": ["<improvement>"],
        "verdict": "pass|fail|warning"
      }

  security:
    network:
      mode: none
    resources:
      cpu: 500
      memory: "512Mi"
      timeout: "60s"

  execution:
    mode: one-shot
    max_retries: 1  # a judge tries once
    validation:
      - type: exit_code
      - type: json_schema
        schema:
          type: object
          required: ["score", "confidence", "reasoning"]
          properties:
            score:
              type: number
              minimum: 0
              maximum: 1
            confidence:
              type: number
              minimum: 0
              maximum: 1
            reasoning:
              type: string

Multi-Judge Consensus

For validation requiring multiple independent judges with consensus aggregation, use ValidatorSpec::MultiJudge inside spec.execution.validation. For workflow-level fan-out and consensus, use workflow ParallelAgents states. See:

Featurespec.execution.validation.multi_judgeWorkflow ParallelAgents
Number of judgesSingleMultiple in parallel
Consensus algorithmN/Amean, min, max, majority
Configuration locationAgent manifestWorkflow manifest
Use casePer-iteration quality gateFinal output multi-panel review

Runtime Selection Guide

When to Use StandardRuntime

✅ Choose StandardRuntime if:

  • Your agent only needs Python, Node.js, TypeScript, Rust, or Go
  • Standard system packages are sufficient (no OS binaries required)
  • You want AEGIS to manage image updates
  • You want deterministic, cached deployments

When to Use CustomRuntime

✅ Choose CustomRuntime if:

  • You need OS-level packages (graphviz, imagemagick, system libraries)
  • You require a specialized language version not in StandardRuntime registry
  • You want to include custom dependencies in the image
  • You're using a private container registry
  • You need image signing or vulnerability scanning

See: Custom Runtime Agents for complete walkthrough.


Image Pull Policies

IfNotPresent (Default)

Use local cached image if available; pull from registry only if missing.

Best for: Release versions (stable, changes rarely), reducing network traffic, offline deployments.

Always

Always pull from registry, even if already cached locally.

Best for: -dev, -latest tags (frequently updated), ensuring agents use current fixes.

Never

Only use cached images; fail if image is not already cached.

Best for: Locked production versions, guaranteed deterministic content, airgapped deployments. Images must be pre-loaded on the node via docker pull before execution. See Pre-Caching for Airgapped Environments.


Version History

VersionDateNotes
v1.02026-02-16Kubernetes-style format with apiVersion/kind/metadata/spec. Canonical format for all new agents.

On this page