Runtime Architecture

Cluster (your dedicated cloud infrastructure)
|-- Zones (your deployed apps)
    |-- Pods (groups of containers that can communicate over localhost)
        |-- Containers
            |-- Nodes (Python apps built using the Autonomy Framework)
            |   |-- Agents (intelligent autonomous actors)
            |   |-- Workers (stateful actors that send and receive messages)
            |
            |-- Tool servers (MCP servers, or other tools)

​

Cluster

• It hosts all your zones.
• and has a unique identifier, like 19f138000c5dcc2eaa7d8f21594fc0c3.

# Enroll your workstation
autonomy cluster enroll --no-input

# View your cluster
autonomy cluster show

​

Zone

• Its name must be ≤ 10 characters, using only a to z and 0 to 9.
• It contains one or more pods.
• It can be public (web accessible) or private.
• Nodes in a Zone can communicate and securely delegate work to each other.

name: myapp
pods:
  - name: main-pod
    public: true
    containers:
      - name: main
        image: main

autonomy zone deploy              # Deploy or update th zone defined in autonomy.yaml
autonomy zone list                # List all zones
autonomy zone delete [ZONE_NAME]  # Delete the specified zone
autonomy zone delete              # Delete the zone defined in autonomy.yaml

​

Pod

• All containers in a pod share a network namespace (use localhost to communicate).
• Can be public (expose port 8000 to the Internet) or private.
• Can be cloned to create multiple instances.

pods:
  - name: main-pod
    public: true              # Expose HTTP on port 8000
    size: big                 # More resources (see specifications below)
    containers:
      - name: main
        image: main

• Regular pods are the default and suitable for most agents and workers.
• Big pods provide 16x more CPU and ~8x more memory for demanding workloads.

• Distribute work across multiple machines.
• Scale horizontally with clones.
• Isolate different services.

​

Container

• Built from images/${IMAGE_NAME}/Dockerfile.
• Can run an Autonomy Node or any service that a node needs (like MCP servers).
• Multiple containers in the same pod communicate via localhost.

containers:
  - name: main
    image: main
    env:
      - LOG_LEVEL: "INFO"
      - API_KEY: secrets.MY_KEY

containers:
  - name: brave
    image: ghcr.io/build-trust/mcp-proxy
    env:
      - BRAVE_API_KEY: secrets.BRAVE_API_KEY
    args:
      ["--sse-port", "8001", "--pass-environment", "--",
       "npx", "-y", "@modelcontextprotocol/server-brave-search"]

​

Node

• Created by calling Node.start(main) in Python.
• Runs HTTP server on port 8000.
• Can discover and communicate with other nodes.

from autonomy import Node

async def main(node):
    print(f"Node {node.name} is running")

Node.start(main)

from autonomy import Node, Zone

async def main(node):
    # Find all nodes in pods named "runner-pod"
    runners = await Zone.nodes(node, filter="runner")
    print(f"Found {len(runners)} runner nodes")

Node.start(main)