Blog · Guide · 28 October 2026
The AEGIS agent manifest: every field and what it enforces
Disclosure: 100monkeys.ai builds AEGIS, so read this guide as a maker's account. It was drafted by one of our AI agents from the public AEGIS documentation, chiefly the Agent Manifest Reference, the CLI Reference, the Workflow Manifest Reference and Human Approvals, and reviewed by the company. Field names, defaults and refusal messages are quoted from those pages.
AEGIS by 100monkeys.ai, in beta, runs an agent from one YAML file. The docs call the agent manifest "the source of truth for an Agent's identity, capabilities, security constraints, and execution requirements." This guide walks it section by section and says, for each field, what the orchestrator does with it.
Step 1. Write the header
apiVersion: 100monkeys.ai/v1
kind: Agent
metadata:
name: pr-reviewer
version: "1.0.0"
description: "Reviews pull request diffs and returns structured feedback."apiVersion and kind must be exactly these values. name must match ^[a-z0-9][a-z0-9-]{0,62}$, and the pair of name and version must be unique: deploying the same pair again fails unless you pass --force. labels and annotations are optional key-value maps for discovery and notes.
Step 2. Choose a runtime
spec.runtime is the only required part of spec. Give either language and version (python, javascript, typescript, rust or go, resolved to an official image) or a fully qualified image, never both; language without version is invalid. image_pull_policy defaults to IfNotPresent. model names a model alias from aegis-config.yaml, and an alias that generates images is refused. isolation accepts inherit, docker, firecracker and process; the reference marks docker as Phase 1 and the other two as Phase 2.
Step 3. Give it a task
task.instruction is the guidance the agent works from, and setting it "auto-enables semantic validation". task.prompt_template is a Handlebars template; its variables are {{intent}}, {{instruction}}, {{input}}, {{iteration_number}}, {{previous_error}} and {{context}}. spec.input_schema, a JSON Schema with type: object, declares named inputs and validates them before the agent runs.
Step 4. Declare only the access it needs
"All permissions are deny-by-default." With no spec.security, the agent has no network and no filesystem access. network.mode is allow (only the allowlist), deny (everything but the denylist) or none, which "attaches no network interface to the container". filesystem.read and filesystem.write list paths, globs allowed. Resources default to cpu: 1000 millicores, memory: "512Mi", disk: "1Gi" and timeout: "1800s", with a maximum of one hour. When the agent may try twice or more, the timeout must hold two whole tries, 2 × (iteration_timeout + the judges' timeout_seconds) + 45 s, or the agent "is refused on create and update".
Step 5. Mount its volumes
Each spec.volumes[] entry has a name, a storage_class (ephemeral needs ttl_hours; persistent needs source.volume_id), a mount_path rooted at /workspace and an access_mode. Read-write access to a persistent volume is exclusive to one execution at a time. A volume that cannot be mounted stops the iteration: the agent "never runs without its volume."
Step 6. Set how it iterates and what counts as done
execution.mode is iterative (the default) or one-shot. max_iterations runs from 1 to 20, default 5, and max_retries is the same field. iteration_timeout defaults to 600s and llm_timeout_seconds to 300. After each try, validation runs in order: exit_code, json_schema, regex, semantic (a judge agent, default min_score 0.7) or multi_judge. A failure goes back to the agent as {{previous_error}}. tool_validation judges each tool call before it runs; only semantic entries are used there. outputs names files the run must leave, each with an optional min_bytes and magic, and a missing one fails the try.
Step 7. Grant tools
spec.tools takes strings such as "mcp:filesystem" or objects with name, server and config. To run commands, declare executor: "builtin:cmd" with a required subcommand_allowlist, a map of command to allowed first arguments; any other call "is rejected with a policy violation". The orchestrator checks that the declarations can do the work: an agent that must write files but declares no tools, or declares fs.write with no read-write volume, is refused at deploy with a sentence naming the reason.
Step 8. Pass configuration and secrets
spec.env values are a literal, "secret:<name>" (injected from OpenBao and "never logged") or "config:<key>". spec.security_context is for platform operators only; a consumer account that sets it gets 403 Forbidden.
Step 9. Validate, then deploy
aegis agent deploy ./agent.yaml --validate-only
aegis agent deploy ./agent.yaml--validate-only parses and validates without deploying. aegis agent show <AGENT_ID> prints the stored manifest back.
Where a human yes goes
The agent manifest has no approval field. A person's yes belongs to a workflow, in a state of kind: Human: prompt is required, timeout defaults to 3600s, and default_response is the answer taken when it elapses; without one, the workflow fails. Human Approvals says a gate's input_equals_yes transition takes yes and input_equals_no takes no, and an answer no transition takes is refused and asked again.
What the docs leave open
- The two references disagree on gate words: the Workflow Manifest Reference has
input_equals_yesaccept "yes", "approve", "approved" or "true"; Human Approvals saysyes,yor1. This guide follows Human Approvals. metadata.versionis called "semantic version" in the example and "Manifest schema version" in the table.firecrackerandprocessare listed as validisolationvalues, marked Phase 2; the reference does not say what happens when a manifest names one today.
Next
To run a manifest end to end on a fresh server, read Install AEGIS on a fresh Ubuntu VPS and run your first approved task. AEGIS installs with the command printed on 100monkeys.ai:
curl -fsSL https://get.100monkeys.ai | bash