Skip to main content
The Autonomy Computer uses a hierarchical architecture that lets you build everything from simple single-agent apps to distributed systems with thousands of parallel collaborating agents. Your apps can create deep work agents that work on long and complex tasks, running as stateful concurrent actors that asynchronously send and receive messages.

​
Architecture Overview

Your applications run in this hierarchy: 
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

Your dedicated cloud infrastructure. This infrastructure is geographically distributed across regions and clouds. Key points:
  • One cluster per account.
  • Has a unique cluster ID (like 19f138000c5dcc2eaa7d8f21594fc0c3).
  • Hosts all your zones.
Setup: 
# Enroll your workstation
autonomy cluster enroll --no-input

# View your cluster
autonomy cluster show
Your apps are accessible at: https://${CLUSTER}-${ZONE}.cluster.autonomy.computer/.

​
Zone

A deployed application with autonomous agents. Each zone is defined by an autonomy.yaml file. Key points:
  • Name must be ≤ 10 characters, using only a to z and 0 to 9.
  • Contains one or more pods.
  • Can be public (web accessible) or private.
  • Nodes in a Zone can communicate and securely delegate work to each other.
Example: 
name: myapp
pods:
  - name: main-pod
    public: true
    containers:
      - name: main
        image: main
Commands: 
autonomy zone deploy              # Deploy or update
autonomy zone list                # List all zones
autonomy zone delete --yes        # Delete zone

​
Pod

A group of containers that run together. Key points:
  • 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.
Options: 
pods:
  - name: main-pod
    public: true              # Expose HTTP on port 8000
    size: big                 # More resources (see specifications below)
    containers:
      - name: main
        image: main
Pod Size Specifications:
SizeCPUMemoryUse Case
Regular (default)0.25256MiLightweight agents, simple workers
Big (size: big)42GiCompute-intensive tasks, distributed processing
  • 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.
Use multiple pods to:
  • Distribute work across multiple machines.
  • Scale horizontally with clones.
  • Isolate different services.

​
Container

A container running inside a pod. Key points:
  • 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.
Autonomy Node container: 
containers:
  - name: main
    image: main
    env:
      - LOG_LEVEL: "INFO"
      - API_KEY: secrets.MY_KEY
Non-Node container (like MCP server): 
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

The Autonomy actor runtime that executes inside a container. It hosts agents as stateful concurrent actors that can send and asynchronously receive message. This enables them to collaborate with and delegate work to other agents. Key points:
  • Created by calling Node.start(main) in Python.
  • Runs HTTP server on port 8000.
  • Can discover and communicate with other nodes.
Basic node: 
from autonomy import Node

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

Node.start(main)
Discovering other nodes: 
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)