Standard Runtime Registry

When an agent manifest specifies spec.runtime.language and spec.runtime.version, the AEGIS orchestrator resolves them to a deterministic, pinned Docker image at execution time. The canonical mapping is defined in runtime-registry.yaml, which is committed to the orchestrator repository and loaded at daemon startup.

Using StandardRuntime means you never specify a Docker image directly — AEGIS selects a vetted, pinned image on your behalf.

Registry YAML Example

The registry is stored as a single YAML document. The canonical full file lives in aegis-orchestrator/runtime-registry.yaml.

apiVersion: aegis.ai/v1
kind: RuntimeRegistry
metadata:
  name: standard-runtime-registry
  namespace: aegis-system
spec:
  registry_url: "docker.io"
  runtimes:
    python:
      "3.11":
        image: "python:3.11-slim"
        description: "Python 3.11 with slim Debian base"
    javascript:
      "20":
        image: "node:20-alpine"
        description: "Node.js 20 with Alpine base"
    typescript:
      "5.1":
        image: "node:20-alpine"
        bootstrap_env:
          TYPESCRIPT_VERSION: "5.1"
        description: "TypeScript 5.1 via Node.js 20 with Alpine base; global install required"

Runtime Matrix

Programmatic Runtime Discovery

Agents that create or update other agent manifests can enumerate the registry at execution time by calling the built-in aegis.runtime.list tool. This prevents hallucinated language-version combinations from being written into manifests.

Tool call — list all runtimes:

{}

Tool call — filter by language:

{ "language": "python" }

Response shape:

{
  "tool": "aegis.runtime.list",
  "runtimes": [
    { "language": "python", "version": "3.11", "image": "python:3.11-slim", "description": "Python 3.11 with slim Debian base", "deprecated": false },
    { "language": "python", "version": "3.10", "image": "python:3.10-slim", "description": "Python 3.10 with slim Debian base", "deprecated": false },
    { "language": "python", "version": "3.9",  "image": "python:3.9-slim",  "description": "Python 3.9 with slim Debian base",  "deprecated": true  }
  ],
  "custom_runtime_supported": true
}

The deprecated: true flag indicates versions that are past upstream EOL. Manifests using deprecated versions still execute but emit a warning in the execution log — prefer a supported version.

aegis.runtime.list is available in the aegis-system-agent-runtime security context with no additional configuration. See the Management Tools reference for the full parameter and response schema.

Manifest Usage

spec:
  runtime:
    language: "python"   # Required (StandardRuntime)
    version: "3.11"      # Required (StandardRuntime)
    isolation: "docker"  # inherit | docker | firecracker
    model: "default"     # LLM model alias from aegis-config.yaml

Specifying an unsupported language+version combination is rejected at execution validation time with a descriptive error. There is no fallback to a default version.

Pre-Installed Toolchains

Each StandardRuntime image includes the language's standard package toolchain. You can install additional dependencies inside your agent's bootstrap or using cmd.run tools.

Python (python:3.x-slim, Debian 12)

• pip (Python package manager)
• apt (Debian package manager, for OS-level packages)

# Install a Python package inside the agent
pip install requests numpy

# Install an OS package
apt-get install -y libssl-dev

Tip: If you need more than a few OS packages, consider a Custom Runtime to avoid repeated installs at execution time.

JavaScript / TypeScript (node:x-alpine, Alpine 3.18)

• npm (Node.js package manager)
• apk (Alpine package manager)

For TypeScript (5.1), the orchestrator sets the TYPESCRIPT_VERSION=5.1 environment variable. Your bootstrap or Dockerfile should install the TypeScript toolchain:

npm install -g typescript ts-node

Go (golang:1.x-alpine, Alpine 3.18)

• go binary and build toolchain
• apk (Alpine package manager)

# Install a Go dependency
go get github.com/some/library

Rust (rust:1.x-alpine, Alpine 3.18)

• cargo (Rust package manager and build tool)
• rustc (Rust compiler)
• Rust standard library

# Add a crate dependency
cargo add serde

Bootstrap Mechanism

For all StandardRuntime agents, the orchestrator:

1. Resolves language+version → Docker image via the registry
2. Creates the container: docker run -d --name aegis-<execution_id> <image> tail -f /dev/null
3. Checks whether /usr/local/bin/aegis-bootstrap already exists inside the container
4. If absent, uploads the orchestrator's assets/bootstrap.py to /usr/local/bin/aegis-bootstrap
5. Executes python /usr/local/bin/aegis-bootstrap <prompt>

The bootstrap script connects to AEGIS_ORCHESTRATOR_URL → /v1/dispatch-gateway and runs the 100monkeys iteration loop (generate → execute → validate → refine).

Daemon Configuration

The orchestrator loads the registry from disk at startup via spec.runtime.runtime_registry_path in aegis-config.yaml. The default value is "runtime-registry.yaml" (relative to the daemon's working directory), which matches the file committed to the orchestrator repository root — no configuration is needed for the common case.

# aegis-config.yaml
spec:
  runtime:
    # Path to the StandardRuntime registry YAML.
    # Default: "runtime-registry.yaml" (relative to daemon working directory)
    runtime_registry_path: "runtime-registry.yaml"

Startup behaviour: If the file is missing or contains a parse error, the daemon hard-fails at boot with a descriptive error message. It does not fall back silently, because a missing registry makes every StandardRuntime agent execution impossible.

Custom path: Set runtime_registry_path to an absolute path (e.g., "/etc/aegis/runtime-registry.yaml") when running the daemon from a directory other than the repository root, or when deploying via container images where the working directory differs from the source tree.

Version Support Lifecycle

Each language version in the registry follows a support lifecycle:

Version removals are announced two phases in advance: a deprecation warning phase (still functional) is followed by a removal phase. Agents using deprecated versions will see warnings in execution logs; migrate proactively.

Currently deprecated: python: "3.9" — official upstream EOL. Manifests using this version will execute but log deprecation warnings. Migrate to python: "3.10" or python: "3.11".

Choosing Between StandardRuntime and CustomRuntime

See Also

• Custom Runtime Agents — Using your own Docker image
• Container Registry & Image Management — ImagePullPolicy, private registry authentication, and image caching
• Agent Manifest Reference — spec.runtime field definitions