Aegis Orchestrator
Guides

Deploying & Running Agents

Deploy, inspect, execute, and monitor agents with the current AEGIS CLI.

Deploying & Running Agents

This guide covers the complete agent lifecycle using the aegis CLI: deploying manifests, managing agent state, triggering executions, streaming iteration output, and inspecting execution history.

All operations assume the AEGIS daemon is running and accessible. Use --host <host> and --port <port> to target a remote daemon, or the defaults (127.0.0.1:8088) if running locally.

Authoring Approaches

There are two ways to supply an agent's runtime:

ApproachWhen to Use
Generic AEGIS runtimeMost agents. Define all behavior in the manifest via spec.task.instruction. No Dockerfile or custom image needed. Works with both Docker and Podman.
Custom containerAdvanced use case for complex dependencies or a custom bootstrap.py. Works with Docker or Podman. See Custom Runtime Agents (Advanced).

Both approaches use identical lifecycle and execution commands. The difference is entirely in the manifest format.

Generic AEGIS Runtime (No Custom Container)

For most use cases you do not need to build or maintain a Docker (or Podman) image. Define the agent's behavior in the manifest and let the orchestrator supply the runtime.

How it works:

  1. The orchestrator starts a container (via Docker or Podman) from the AEGIS-managed Python base image.
  2. It injects bootstrap.py into the container automatically.
  3. It renders the final LLM prompt by substituting Handlebars variables in spec.task.prompt_template — replacing {{instruction}} with the manifest's spec.task.instruction text and {{input}} with the JSON passed at execution time.
  4. The rendered prompt is passed to bootstrap.py as argv[1].
  5. bootstrap.py calls the LLM proxy at /v1/dispatch-gateway and streams back the response.
  6. If validation fails, {{previous_error}} is populated with the failure output and the next iteration begins automatically.

No Python file to write. No Docker or Podman build. No image registry.

Example Manifest

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"
    isolation: docker

  task:
    instruction: |
      Review the provided code diff and return structured feedback covering:
      - Security vulnerabilities or concerns
      - Performance issues or opportunities
      - Code quality and maintainability
      - Idiomatic patterns and best practices
      Provide specific line references where relevant. Be concise and actionable.
    prompt_template: |
      {{instruction}}

      User: {{input}}
      Reviewer:

  execution:
    mode: iterative
    max_iterations: 5

  security:
    network:
      mode: allow
      allowlist:
        - api.github.com
    filesystem:
      read:
        - /workspace
      write:
        - /workspace/output
    resources:
      cpu: 1000
      memory: "1Gi"
      timeout: "300s"

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

Deploy it:

aegis agent deploy ./pr-reviewer.yaml

Run an execution, passing the diff as the {{input}} context:

aegis task execute <AGENT_ID> \
  --input '{"diff": "<git diff output>", "repo": "my-org/my-repo", "pr": 42}' \
  --follow

The full contents of the --input JSON string become the {{input}} value the LLM sees. Structure it however is useful for your agent's instruction.

Prompt Template Variables

VariablePopulated With
{{instruction}}spec.task.instruction text from the manifest.
{{input}}JSON string passed via --input at execution time.
{{iteration_number}}Current iteration number (1-based).
{{previous_error}}Validator failure output or error from the previous iteration. Empty on iteration 1; injected automatically on retries.

Use {{previous_error}} in the prompt template to give the LLM explicit feedback about what went wrong in earlier attempts:

task:
  prompt_template: |
    {{instruction}}

    User: {{input}}
    {% if previous_error %}
    Your previous attempt failed with the following error. Fix it:
    {{previous_error}}
    {% endif %}
    Reviewer:

Setting a Specific Model

By default the agent uses the default alias defined in aegis-config.yaml. Override per-agent with spec.runtime.model:

spec:
  runtime:
    language: python
    version: "3.11"
    model: reasoning          # maps to an alias in aegis-config.yaml llm.aliases
    isolation: docker

Agent Lifecycle Commands

Deploy an Agent

aegis agent deploy ./my-agent/agent.yaml

On success, the agent is registered with status: deployed and assigned a UUID. The manifest is validated before acceptance — invalid manifests are rejected with a specific error.

Deployed agent "python-coder" (id: a1b2c3d4-0000-0000-0000-000000000001)

To deploy and validate only (without persisting):

aegis agent deploy ./my-agent/agent.yaml --validate-only

List Agents

# Table format (default)
aegis agent list

# Structured output for automation
aegis agent list --output json

Example table output:

ID                                    NAME           STATUS     RUNTIME  LABELS
a1b2c3d4-0000-...                     python-coder   deployed   docker   type=developer
b2c3d4e5-0000-...                     code-reviewer  paused     docker
c3d4e5f6-0000-...                     security-scan  deployed   docker   team=security

Use --output json and a JSON filter when you need status-based automation.

Inspect an Agent

# By UUID
aegis agent show a1b2c3d4-0000-0000-0000-000000000001

Outputs the full agent manifest as YAML.

Update an Agent

aegis agent deploy ./my-agent/agent.yaml --force

If an agent with the same metadata.name and metadata.version is already deployed, the CLI requires --force to overwrite that exact definition. Running executions are not affected — they continue using the manifest version that was active when they started.

Remove an Agent

Remove deletes the agent registration. Historical execution records are retained.

aegis agent remove a1b2c3d4-0000-0000-0000-000000000001

Running Executions

Start an Execution

aegis task execute <AGENT_ID> \
  --input '{"task": "Write a function that reverses a linked list."}'

Returns the execution ID immediately:

Execution started: a1b2c3d4-1111-0000-0000-000000000001

Stream Execution Output

Use --follow to stream iteration events to the terminal:

aegis task execute <AGENT_ID> \
  --input '{"task": "Write a function that reverses a linked list."}' \
  --follow

Example output:

[2026-02-23T10:00:01Z] Execution a1b2c3d4-1111-... Started
[2026-02-23T10:00:01Z] Iteration 1 Started
[2026-02-23T10:00:03Z] Tool: fs.write /workspace/solution.py (234 bytes)
[2026-02-23T10:00:04Z] Tool: cmd.run python /workspace/solution.py
[2026-02-23T10:00:05Z] Tool: fs.write /workspace/result.json (89 bytes)
[2026-02-23T10:00:06Z] Iteration 1 Completed
[2026-02-23T10:00:06Z] Validation: exit_code=PASS json_schema=PASS (score=1.0)
[2026-02-23T10:00:06Z] Execution a1b2c3d4-1111-... Completed (1 iteration, 5.2s)

Inspecting Executions

List Executions

# All recent executions
aegis task list

# Filter by agent
aegis task list --agent-id <AGENT_ID>

# Limit results
aegis task list --limit 20

Get Execution Details

aegis task status a1b2c3d4-1111-0000-0000-000000000001
aegis task status a1b2c3d4-1111-0000-0000-000000000001 --output json

Returns the execution record, including status, start/end timestamps, total iterations, and each iteration's status and validation scores.

Get Iteration Logs

# All iterations
aegis task logs a1b2c3d4-1111-0000-0000-000000000001

# Follow live output
aegis task logs a1b2c3d4-1111-0000-0000-000000000001 --follow

# Errors only
aegis task logs a1b2c3d4-1111-0000-0000-000000000001 --errors-only

Cancel a Running Execution

aegis task cancel a1b2c3d4-1111-0000-0000-000000000001

Cancellation stops the current iteration's container, releases any held locks, and marks the execution as cancelled.

Scripting with CLI Output

Use structured output for automation instead of scraping UUIDs from human-readable text. Commands that return bounded results now support --output json or --output yaml.

# Deploy and capture the agent ID from structured output
AGENT_ID=$(aegis agent deploy ./agent.yaml --output json | jq -r '.id')

# Start an execution and capture the execution ID
EXEC_ID=$(aegis task execute "$AGENT_ID" \
  --input '{"task": "..."}' \
  --output json | jq -r '.execution_id')

# Poll until complete
while true; do
  STATUS=$(aegis task status "$EXEC_ID" --output json | jq -r '.status')
  echo "Status: $STATUS"
  if [[ "$STATUS" == "completed" || "$STATUS" == "failed" || "$STATUS" == "cancelled" ]]; then
    break
  fi
  sleep 5
done

echo "Final status: $STATUS"

Agent Visibility and Tenant Scope

Deployed agents are tenant-scoped by default — they are only visible and accessible within your tenant. Other tenants cannot discover or invoke your agents.

Platform agents are global — they appear in agent list and search results for all tenants and are always available without any configuration.

When an agent invokes another agent by name (for example, via tool calls in a swarm), resolution follows the same narrowest-first logic: your tenant's agents are checked first, then global platform agents. This means a tenant agent named reviewer will shadow a hypothetical global agent of the same name within your tenant.

CRUD operations (update, delete) are always tenant-scoped. You cannot update or remove a global platform agent regardless of your role.

Configuration and Flags

FlagDescription
--config <path>Path to aegis-config.yaml. Defaults to ./aegis-config.yaml.
--host <host>Target daemon hostname. Defaults to 127.0.0.1.
--port <port>Target daemon port. Defaults to 8088.
--log-level <level>Log verbosity: trace, debug, info, warn, error.

Creating Agents via the UI

Step-by-step guide to creating, editing, and deleting agents using the Zaru web interface.

Importing Community Skills

Use the built-in skill-import workflow to convert community SKILL.md definitions into AEGIS agent baselines

On this page

Deploying & Running AgentsAuthoring ApproachesGeneric AEGIS Runtime (No Custom Container)Example ManifestPrompt Template VariablesSetting a Specific ModelAgent Lifecycle CommandsDeploy an AgentList AgentsInspect an AgentUpdate an AgentRemove an AgentRunning ExecutionsStart an ExecutionStream Execution OutputInspecting ExecutionsList ExecutionsGet Execution DetailsGet Iteration LogsCancel a Running ExecutionScripting with CLI OutputAgent Visibility and Tenant ScopeConfiguration and Flags