# boredengineering/isaacautomator architecture

> Architecture diagram of the GitHub repository boredengineering/isaacautomator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/boredengineering/isaacautomator
- Repository: https://github.com/boredengineering/isaacautomator

## Overview

Isaac Automator is a CLI for provisioning and managing remote Isaac Workstations on AWS, GCP, Azure, and Alibaba Cloud. The operator selects deployment options; deployment orchestration prepares infrastructure and configures the VM, after which operators connect, run robotics applications, and manage data and lifecycle. The graph also preserves documented import, repair, image, and workflow capabilities. Deployment orchestration and utility calls are supported by excerpts; several command and infrastructure relationships are documented only at a high level, so those edges are dashed.

Main entry points: [`src/python/deployer.py`](https://github.com/boredengineering/isaacautomator/blob/main/src/python/deployer.py) (Deployment orchestration), [`src/python/deploy_command.py`](https://github.com/boredengineering/isaacautomator/blob/main/src/python/deploy_command.py) (Deploy options), [`deploy-aws`](https://github.com/boredengineering/isaacautomator/blob/main/deploy-aws) (Deploy command), [`src/python/utils.py`](https://github.com/boredengineering/isaacautomator/blob/main/src/python/utils.py) (CLI utilities)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operator["Operator CLI"]
  node_deploy["Deploy command"]
  node_deployopts["Deploy options<br/>[deploy_command.py]"]
  node_orchestrator["Deployment orchestration<br/>[deployer.py]"]
  node_shared["CLI utilities<br/>[utils.py]"]
end

subgraph group_provision["Cloud Provisioning"]
  node_aws["AWS adapter<br/>[aws.py]"]
  node_azure["Azure adapter<br/>[azure.py]"]
  node_alicloud["Alibaba adapter<br/>[alicloud.py]"]
  node_terraform["Cloud infrastructure"]
end

subgraph group_workstation["Workstation Setup"]
  node_ansible["VM configuration"]
  node_demos["Robotics demos"]
end

subgraph group_workflow["Workstation Workflow"]
  node_lifecycle["Lifecycle commands"]
  node_connect["Remote desktop"]
  node_transfer["Data transfer"]
  node_results["Results retrieval"]
  node_import["Import deployment"]
  node_repair["Repair deployment"]
  node_image["Prebuilt images"]
end

subgraph group_state["Deployment State"]
  node_state[("Deployment state")]
  node_config["Defaults and registry<br/>[config.py]"]
end

node_operator(("Operator"))
node_cloud{{"Cloud providers"}}
node_workstation{{"Isaac Workstation"}}

node_operator -->|"runs"| node_deploy
node_deploy -.->|"parses options"| node_deployopts
node_deployopts -.->|"configures"| node_orchestrator
node_deployopts -->|"reads defaults"| node_config
node_orchestrator -->|"uses helpers"| node_shared
node_orchestrator -.->|"provisions"| node_terraform
node_orchestrator -->|"runs playbook"| node_ansible
node_terraform -.->|"creates resources"| node_cloud
node_aws -->|"manages instances"| node_cloud
node_azure -->|"manages instances"| node_cloud
node_alicloud -->|"manages instances"| node_cloud
node_ansible -.->|"configures VM"| node_workstation
node_demos -->|"installs demos"| node_workstation
node_operator -->|"opens desktop"| node_connect
node_operator -->|"pauses or resumes"| node_lifecycle
node_operator -->|"uploads data"| node_transfer
node_operator -->|"downloads data"| node_results
node_operator -->|"imports resources"| node_import
node_operator -->|"repairs deployment"| node_repair
node_operator -->|"selects image"| node_image
node_orchestrator -->|"writes metadata"| node_state
node_shared -->|"reads deployment data"| node_state
node_transfer -.->|"moves files"| node_workstation
node_results -.->|"retrieves files"| node_workstation

click node_deploy "https://github.com/boredengineering/isaacautomator/blob/main/deploy-aws"
click node_deployopts "https://github.com/boredengineering/isaacautomator/blob/main/src/python/deploy_command.py"
click node_orchestrator "https://github.com/boredengineering/isaacautomator/blob/main/src/python/deployer.py"
click node_shared "https://github.com/boredengineering/isaacautomator/blob/main/src/python/utils.py"
click node_aws "https://github.com/boredengineering/isaacautomator/blob/main/src/python/aws.py"
click node_azure "https://github.com/boredengineering/isaacautomator/blob/main/src/python/azure.py"
click node_alicloud "https://github.com/boredengineering/isaacautomator/blob/main/src/python/alicloud.py"
click node_terraform "https://github.com/boredengineering/isaacautomator/tree/main/src/terraform"
click node_ansible "https://github.com/boredengineering/isaacautomator/tree/main/src/ansible"
click node_demos "https://github.com/boredengineering/isaacautomator/tree/main/src/ansible/roles/demos"
click node_lifecycle "https://github.com/boredengineering/isaacautomator/blob/main/stop"
click node_connect "https://github.com/boredengineering/isaacautomator/blob/main/novnc"
click node_transfer "https://github.com/boredengineering/isaacautomator/blob/main/upload"
click node_results "https://github.com/boredengineering/isaacautomator/blob/main/download"
click node_import "https://github.com/boredengineering/isaacautomator/blob/main/import"
click node_repair "https://github.com/boredengineering/isaacautomator/blob/main/repair"
click node_image "https://github.com/boredengineering/isaacautomator/blob/main/image-aws"
click node_state "https://github.com/boredengineering/isaacautomator/tree/main/state"
click node_config "https://github.com/boredengineering/isaacautomator/blob/main/src/python/config.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_deploy,node_deployopts,node_orchestrator,node_shared toneBlue
class node_aws,node_azure,node_alicloud,node_terraform toneAmber
class node_ansible,node_demos toneMint
class node_lifecycle,node_connect,node_transfer,node_results,node_import,node_repair,node_image toneRose
class node_state,node_config,node_operator,node_cloud,node_workstation toneIndigo
```

## Components

### Operator CLI

- [Deploy command](https://github.com/boredengineering/isaacautomator/blob/main/deploy-aws): `deploy-aws`
- [Deploy options](https://github.com/boredengineering/isaacautomator/blob/main/src/python/deploy_command.py): `src/python/deploy_command.py`
- [Deployment orchestration](https://github.com/boredengineering/isaacautomator/blob/main/src/python/deployer.py): `src/python/deployer.py`
- [CLI utilities](https://github.com/boredengineering/isaacautomator/blob/main/src/python/utils.py): `src/python/utils.py`

### Cloud Provisioning

- [AWS adapter](https://github.com/boredengineering/isaacautomator/blob/main/src/python/aws.py): `src/python/aws.py`
- [Azure adapter](https://github.com/boredengineering/isaacautomator/blob/main/src/python/azure.py): `src/python/azure.py`
- [Alibaba adapter](https://github.com/boredengineering/isaacautomator/blob/main/src/python/alicloud.py): `src/python/alicloud.py`
- [Cloud infrastructure](https://github.com/boredengineering/isaacautomator/tree/main/src/terraform): `src/terraform`

### Workstation Setup

- [VM configuration](https://github.com/boredengineering/isaacautomator/tree/main/src/ansible): `src/ansible`
- [Robotics demos](https://github.com/boredengineering/isaacautomator/tree/main/src/ansible/roles/demos): `src/ansible/roles/demos`

### Workstation Workflow

- [Lifecycle commands](https://github.com/boredengineering/isaacautomator/blob/main/stop): `stop`
- [Remote desktop](https://github.com/boredengineering/isaacautomator/blob/main/novnc): `novnc`
- [Data transfer](https://github.com/boredengineering/isaacautomator/blob/main/upload): `upload`
- [Results retrieval](https://github.com/boredengineering/isaacautomator/blob/main/download): `download`
- [Import deployment](https://github.com/boredengineering/isaacautomator/blob/main/import): `import`
- [Repair deployment](https://github.com/boredengineering/isaacautomator/blob/main/repair): `repair`
- [Prebuilt images](https://github.com/boredengineering/isaacautomator/blob/main/image-aws): `image-aws`

### Deployment State

- [Deployment state](https://github.com/boredengineering/isaacautomator/tree/main/state): `state`
- [Defaults and registry](https://github.com/boredengineering/isaacautomator/blob/main/src/python/config.py): `src/python/config.py`

### Other components

- **Operator**
- **Cloud providers**
- **Isaac Workstation**

## Connections

- Operator → Deploy command: runs (evidence: `README.md`)
- Deploy command → Deploy options: parses options
- Deploy options → Deployment orchestration: configures
- Deploy options → Defaults and registry: reads defaults (evidence: `src/python/deploy_command.py`)
- Deployment orchestration → CLI utilities: uses helpers (evidence: `src/python/deployer.py`)
- Deployment orchestration → Cloud infrastructure: provisions
- Deployment orchestration → VM configuration: runs playbook (evidence: `src/python/deployer.py`)
- Cloud infrastructure → Cloud providers: creates resources
- AWS adapter → Cloud providers: manages instances (evidence: `src/python/aws.py`)
- Azure adapter → Cloud providers: manages instances (evidence: `src/python/azure.py`)
- Alibaba adapter → Cloud providers: manages instances (evidence: `src/python/alicloud.py`)
- VM configuration → Isaac Workstation: configures VM
- Robotics demos → Isaac Workstation: installs demos
- Operator → Remote desktop: opens desktop (evidence: `README.md`)
- Operator → Lifecycle commands: pauses or resumes (evidence: `README.md`)
- Operator → Data transfer: uploads data (evidence: `README.md`)
- Operator → Results retrieval: downloads data (evidence: `README.md`)
- Operator → Import deployment: imports resources (evidence: `README.md`)
- Operator → Repair deployment: repairs deployment (evidence: `README.md`)
- Operator → Prebuilt images: selects image (evidence: `README.md`)
- Deployment orchestration → Deployment state: writes metadata (evidence: `src/python/deployer.py`)
- CLI utilities → Deployment state: reads deployment data (evidence: `src/python/utils.py`)
- Data transfer → Isaac Workstation: moves files
- Results retrieval → Isaac Workstation: retrieves files
