> ## Documentation Index
> Fetch the complete documentation index at: https://autonomy.computer/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Runtime Architecture

> Understand how your applications run on the Autonomy Computer

The [Autonomy Computer](/what-is-autonomy#autonomy-computer) provides a scalable
and flexible architecture that lets you ship everything from simple single-agent
apps to distributed systems with thousands of parallel collaborating agents.

Your applications run in this hierarchy:

```text Runtime Architecture: theme={null}
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 in the [Autonomy Computer](/what-is-autonomy#autonomy-computer).

* It hosts all your [zones](#zone).
* and has a unique identifier, like `19f138000c5dcc2eaa7d8f21594fc0c3`.

```bash Commands: theme={null}
# Enroll your workstation
autonomy cluster enroll --no-input

# View your cluster
autonomy cluster show
```

Clusters are geographically distributed across regions and clouds.

## Zone

A deployed application. Each zone is defined by an `autonomy.yaml` file.

* 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.

```yaml autonomy.yaml theme={null}
name: myapp
pods:
  - name: main-pod
    public: true
    containers:
      - name: main
        image: main
```

```bash Commands: theme={null}
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
```

If `public: true` then port `8000` of the `main-pod` are served on this
public HTTPS url: `https://${CLUSTER}-${ZONE}.cluster.autonomy.computer`

## Pod

A group of containers that run together.

* 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:**

```yaml theme={null}
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:**

| Size              | CPU  | Memory | Use Case                                        |
| ----------------- | ---- | ------ | ----------------------------------------------- |
| Regular (default) | 0.25 | 256Mi  | Lightweight agents, simple workers              |
| Big (`size: big`) | 4    | 2Gi    | Compute-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.

* 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:**

```yaml theme={null}
containers:
  - name: main
    image: main
    env:
      - LOG_LEVEL: "INFO"
      - API_KEY: secrets.MY_KEY
```

**Non-Node container (like MCP server):**

```yaml theme={null}
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.

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

**Basic node:**

```python theme={null}
from autonomy import Node

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

Node.start(main)
```

**Discovering other nodes:**

```python theme={null}
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)
```