# Isaac Automator (v4)
Isaac Automator allows quick deployment of Isaac Sim, Isaac Lab, and Isaac Lab Arena to public clouds (AWS, GCP, Azure, and Alibaba Cloud are currently supported).
The result is a fully configured deployed Isaac Workstation — a remote desktop cloud VM that you can use to develop and test robotic applications within minutes and on a budget. Isaac Automator supports a variety of GPU instances and stop/start functionality to save on cloud costs and provides tools to aid your workflow (uploading and downloading data, autorun, deployment management, etc.).
- [TLDR ;)](#tldr-)
- [Using with AI Agents](#using-with-ai-agents)
- [Installation](#installation)
- [Installing Docker](#installing-docker)
- [Building the Container](#building-the-container)
- [Linux/macOS](#linuxmacos)
- [Windows](#windows)
- [Usage](#usage)
- [Running Isaac Automator](#running-isaac-automator)
- [Linux/macOS](#linuxmacos-1)
- [Windows](#windows-1)
- [Deploying an Isaac Workstation](#deploying-an-isaac-workstation)
- [AWS](#aws)
- [GCP](#gcp)
- [Azure](#azure)
- [Alibaba Cloud](#alibaba-cloud)
- [Common Deploy Options](#common-deploy-options)
- [Complete Options Reference](#complete-options-reference)
- [Credential Management](#credential-management)
- [Connecting to Deployed Isaac Workstation](#connecting-to-deployed-isaac-workstation)
- [Running Applications](#running-applications)
- [Isaac Sim](#isaac-sim)
- [Isaac Lab](#isaac-lab)
- [Isaac Lab Arena](#isaac-lab-arena)
- [Demos](#demos)
- [Autorun Script](#autorun-script)
- [Standard Folders](#standard-folders)
- [Pausing and Resuming](#pausing-and-resuming)
- [Uploading Data](#uploading-data)
- [Downloading Data](#downloading-data)
- [Repairing](#repairing)
- [Destroying](#destroying)
- [Importing Existing Deployments](#importing-existing-deployments)
- [Speeding Up Deployment with Pre-Built Images](#speeding-up-deployment-with-pre-built-images)
- [Tips](#tips)
- [Persisting Modifications to the deployed Isaac Workstation](#persisting-modifications-to-the-deployed-isaac-workstation)
## TLDR ;)
```sh
./build # build the Isaac Automator container (one-time)
./run # enter the container
./deploy-aws # deploy an Isaac Workstation (follow the prompts)
./novnc <deployment-name> # open the remote desktop in your browser
./destroy <deployment-name> # tear down the deployment when done
./import --cloud aws ... # import existing cloud resources into state
```
Replace `deploy-aws` with `deploy-gcp`, `deploy-azure`, or `deploy-alicloud` for other clouds. See sections below for details.
## Using with AI Agents
Isaac Automator ships first-class instructions for AI agents that want to operate it.
- **To operate Isaac Automator** (deploy a workstation, connect, run demos, stop/start, destroy), start with
[`ai/automator.agent.md`](ai/automator.agent.md) and follow the step-by-step procedures in [`ai/skills/`](ai/skills/).
- Agent-aware tools auto-discover [`AGENTS.md`](AGENTS.md) (and [`CLAUDE.md`](CLAUDE.md) for Claude Code),
which route to that operator guide and summarize the cost/safety and non-interactive rules an agent must
follow.
These describe *using* Isaac Automator as an operator. To develop the tool itself, see the sections below and
[`CONTRIBUTING.md`](CONTRIBUTING.md).
## Installation
### Installing Docker
Docker should be installed on your system. Visit <https://docs.docker.com/engine/install/> for installation instructions.
### Building the Container
Please enter the following command in the project root directory to build the container:
#### Linux/macOS
```sh
./build
```
#### Windows
```sh
docker build --platform linux/x86_64 -t isaac_automator .
```
This will build the Isaac Automator container and tag it as `isaac_automator`.
## Usage
### Running Isaac Automator
#### Linux/macOS
On Linux and macOS there are two ways to run Isaac Automator commands:
1. First enter the Isaac Automator container and then run the command inside the container:
```sh
# enter Isaac Automator container
./run
# inside container:
./somecommand
```
2. Simply prepend the command with `./run`, like so:
```sh
./run ./somecommand <parameters>
```
for example:
```sh
./run ./deploy-aws
./run ./destroy my-deployment
```
#### Windows
On Windows, you can run Isaac Automator commands by entering the container first and then running the command inside the container, like so:
(enter Isaac Automator container)
```sh
docker run --platform linux/x86_64 -it --rm -v .:/app isaac_automator bash
```
(run the command inside the container)
```sh
./somecommand
```
### Deploying an Isaac Workstation
#### AWS
<details>
<a name="#aws-permissions"></a>
<summary>Enabling Access Permissions</summary>
You need _AmazonEC2FullAccess_ permissions enabled for your AWS user. You can enable those in the [Identity and Access Management (IAM) section](https://console.aws.amazon.com/iamv2/home#/home) of the AWS console, as follows:
1. Go to <https://console.aws.amazon.com/iamv2/home#/home>
2. Click "Access Management" \> "Users" in the left menu
3. Search for your user name
4. Under "Permissions" tab click "Add permissions"
5. Choose "Attach existing policies directly"
6. Search for _AmazonEC2FullAccess_, check the box next to it, click "Next"
7. Click "Add permissions"
</details>
<details>
<a name="#aws-access-creds"></a>
<summary>Getting Access Credentials</summary>
You will need an _AWS Access Key_ and _AWS Secret Key_ for an existing account. You can obtain those in the [Identity and Access Management (IAM) section](https://console.aws.amazon.com/iamv2/home#/home) of the AWS console.
</details>
If you have completed the above steps or already have your permissions and credentials set up, run the following command in the project root directory:
```sh
# enter Isaac Automator container
./run
# inside container:
./deploy-aws
```
On the first run (or when credentials expire), you will be prompted to sign in with AWS IAM Identity Center (via `aws configure sso` / `aws sso login`). The credentials are stored in `state/.aws/` and persist across Isaac Automator restarts.
By default the sign-in uses the AWS SSO **device-code flow** (open a URL and enter a code), which works on headless and remote (SSH) hosts where a local browser is not reachable. If you are on a machine with a local browser and prefer the browser-based flow, set `AWS_SSO_USE_DEVICE_CODE=0` on the host before running `./run`.
Tip: Run `./deploy-aws --help` to see more options.
#### GCP
<details>
<summary>Setting Up GCP Access</summary>
You will be prompted to log in with your Google account (`gcloud auth login`) during the first deployment. The credentials are stored in `state/.gcp/` and persist across container restarts.
Make sure you have a GCP project with Compute Engine API enabled and sufficient GPU quota in the target zone.
</details>
```sh
# enter Isaac Automator container
./run
# inside container:
./deploy-gcp
```
Tip: Run `./deploy-gcp --help` to see more options.
#### Azure
<details>
<summary>Setting Up Azure Access</summary>
You will be prompted to log in with your Azure account (`az login`) during the first deployment. The credentials are stored in `state/.azure/` and persist across container restarts.
If you have multiple subscriptions, select the desired one before deploying:
```sh
# inside container:
az login
az account show --output table # list subscriptions
az account set --subscription "<subscription_name>"
./deploy-azure --no-login
```
</details>
If you have a single subscription:
```sh
# enter Isaac Automator container
./run
# inside container:
./deploy-azure
```
Tip: Run `./deploy-azure --help` to see more options.
#### Alibaba Cloud
<details>
<a name="#alicloud-access-creds"></a>
<summary>Getting Access Credentials</summary>
You will need an _Access Key_ and _Secret Key_ for an existing Alibaba Cloud account. You can obtain those in the [AccessKey Management](https://usercenter.console.aliyun.com/#/manage/ak) section of the Alibaba Cloud console.
</details>
Once you have prepared the access credentials, run the following command in the project root directory:
```sh
# enter Isaac Automator container
./run
# inside container:
./deploy-alicloud
```
Tip: Run `./deploy-alicloud --help` to see more options.
GPU-accelerated instances with NVIDIA A100, A10, and T4 GPUs are supported. You can find the complete list of instance types, availability, and pricing at <https://www.alibabacloud.com/help/en/ecs/user-guide/gpu-accelerated-compute-optimized-and-vgpu-accelerated-instance-families-1>. Please note that vGPU instances are not supported.
#### Common Deploy Options
All `deploy-*` commands accept the deployment name as an optional positional argument:
```sh
./deploy-aws my-deployment
# equivalent to:
./deploy-aws --deployment-name my-deployment
```
Run `./deploy-<cloud> --help` to see the full list of options. Key options include:
- `--existing` — What to do if a deployment with the same name already exists. Choices:
- `ask` (default) — prompt interactively
- `repair` — fix a broken deployment without changing parameters
- `modify` — update parameters and attempt to update existing cloud resources
- `replace` — delete old cloud resources first, then redeploy
- `run_ansible` — re-run software configuration (Ansible) only
- `--instance-type` — Cloud VM instance type (each cloud has its own supported list and default).
- `--isaacsim` / `--isaaclab` / `--isaaclab-arena` — Git ref for Isaac Sim / Isaac Lab / Isaac Lab Arena version, or `no` to skip installation. To install from a fork or an internal repository, pass `<repo url>@<ref>` (e.g. `--isaacsim https://github.com/my-org/IsaacSim-Internal@v6.1.0`).
- `--isaacsim-git-repo` / `--isaaclab-git-repo` / `--isaaclab-arena-git-repo` — Repository to install each component from. Defaults to the public repo. A private repository must be reachable from the deployed instance (see [Installing from a fork or an internal repository](#installing-from-a-fork-or-an-internal-repository)).
- `--demos` — Comma-separated list of out-of-the-box demos to install as desktop shortcuts, or `no` (default). A demo automatically enables the apps it depends on (see [Demos](#demos)).
- `--from-image` — Deploy from a pre-built VM image to speed up provisioning (supported on AWS, Azure, and GCP; see [Speeding Up Deployment with Pre-Built Images](#speeding-up-deployment-with-pre-built-images)).
- `--in-china` — Use local mirrors for deployments in China. Choices: `auto` (default), `yes`, `no`.
- `--prefix` — Prefix for created cloud resource names (default: `isaacautomator`).
- `--ingress-cidrs` — CIDR blocks for allowed ingress traffic, comma-separated. Use `myip` for your current public IP, or `myip/16`, `myip/24` for subnets.
GCP additionally supports `--isaac-workstation-gpu-count` (choices: `1`, `2`, `4`, `8`; default: `1`) to control the number of GPUs attached to the instance:
- N1 instances: up to 4x NVIDIA T4
- G2 instances: up to 8x NVIDIA L4
- G4 instances: up to 8x NVIDIA RTX PRO 6000
<details>
<summary>deploy-aws options</summary>
#### Complete Options Reference
```
Options:
--debug / --no-debug Enable debug output. [default: no-debug]
--prefix TEXT Prefix for all cloud resources. [default: isaacautomator]
--from-image / --not-from-image
Deploy from pre-built image, from bare OS
otherwise. [default: not-from-image]
--in-china [auto|yes|no] Is deployment in China? (Local mirrors will be
used.) [default: auto]
--deployment-name TEXT Name of the deployment. [default: <random>]
--ingress-cidrs TEXT CIDR blocks for ingress traffic, comma
separated. "myip" for your public IP.
[default: 0.0.0.0/0]
--existing [ask|repair|modify|replace|run_ansible]
What to do if deployment already exists.
[default: ask]
--isaacsim TEXT Git ref at github.com/isaac-sim/IsaacSim, or
"no". [default: v6.0.0-dev2]
--isaaclab TEXT Git ref at github.com/isaac-sim/IsaacLab, or
"no". [default: v3.0.0-beta]
--isaaclab-arena TEXT Git ref at
github.com/isaac-sim/IsaacLab-Arena, or
"no". [default: release/0.1.1]
--vnc-password TEXT Password for VNC access. [default: <random>]
--system-user-password TEXT System user password. [default: <random>]
--ssh-port TEXT SSH port. [default: 22]
--ssh-user TEXT OS username on the deployed instances.
[default: ubuntu]
--upload / --no-upload Upload user data from "uploads/" to cloud
instances. [default: upload]
--instance-type TEXT Instance type (G4dn, G5, G6, G6e supported).
[default: g6e.2xlarge]
--region TEXT AWS Region. [default: us-east-1]
Note: AWS credentials are managed via `aws configure sso` / `aws sso login` and stored in
`state/.aws/`. You will be prompted to enter them on first run or when
they expire.
```
</details>
<details>
<summary>deploy-gcp options</summary>
```
Options:
--debug / --no-debug Enable debug output. [default: no-debug]
--prefix TEXT Prefix for all cloud resources. [default: isaacautomator]
--in-china [auto|yes|no] Is deployment in China? (Local mirrors will be
used.) [default: auto]
--deployment-name TEXT Name of the deployment. [default: <random>]
--zone TEXT GCP zone (see cloud.google.com/compute/docs/
gpus/gpu-regions-zones).
[default: us-central1-a]
--project TEXT GCP Project ID. [default: from gcloud config]
--ingress-cidrs TEXT CIDR blocks for ingress traffic, comma
separated. "myip" for your public IP.
[default: 0.0.0.0/0]
--existing [ask|repair|modify|replace|run_ansible]
What to do if deployment already exists.
[default: ask]
--isaacsim TEXT Git ref at github.com/isaac-sim/IsaacSim, or
"no". [default: v6.0.0-dev2]
--isaaclab TEXT Git ref at github.com/isaac-sim/IsaacLab, or
"no". [default: v3.0.0-beta]
--isaaclab-arena TEXT Git ref at
github.com/isaac-sim/IsaacLab-Arena, or
"no". [default: release/0.1.1]
--vnc-password TEXT Password for VNC access. [default: <random>]
--system-user-password TEXT System user password. [default: <random>]
--ssh-port TEXT SSH port. [default: 22]
--ssh-user TEXT OS username on the deployed instances.
[default: ubuntu]
--upload / --no-upload Upload user data from "uploads/" to cloud
instances. [default: upload]
--instance-type [g2-standard-4|g2-standard-8|...|n1-standard-4|...|g4-standard-48|...]
Instance type. [default: g2-standard-8]
--isaac-workstation-gpu-count [1|2|4|8]
Number of GPUs. N1: NVIDIA T4, G2: NVIDIA L4,
G4: NVIDIA RTX PRO 6000. [default: 1]
```
</details>
<details>
<summary>deploy-azure options</summary>
```
Options:
--debug / --no-debug Enable debug output. [default: no-debug]
--prefix TEXT Prefix for all cloud resources. [default: isaacautomator]
--from-image / --not-from-image
Deploy from pre-built image, from bare OS
otherwise. [default: not-from-image]
--in-china [auto|yes|no] Is deployment in China? (Local mirrors will be
used.) [default: auto]
--deployment-name TEXT Name of the deployment. [default: <random>]
--region TEXT Azure region. [default: westus3]
--ingress-cidrs TEXT CIDR blocks for ingress traffic, comma
separated. "myip" for your public IP.
[default: 0.0.0.0/0]
--existing [ask|repair|modify|replace|run_ansible]
What to do if deployment already exists.
[default: ask]
--isaacsim TEXT Git ref at github.com/isaac-sim/IsaacSim, or
"no". [default: v6.0.0-dev2]
--isaaclab TEXT Git ref at github.com/isaac-sim/IsaacLab, or
"no". [default: v3.0.0-beta]
--isaaclab-arena TEXT Git ref at
github.com/isaac-sim/IsaacLab-Arena, or
"no". [default: release/0.1.1]
--vnc-password TEXT Password for VNC access. [default: <random>]
--system-user-password TEXT System user password. [default: <random>]
--ssh-port TEXT SSH port. [default: 22]
--ssh-user TEXT OS username on the deployed instances.
[default: ubuntu]
--upload / --no-upload Upload user data from "uploads/" to cloud
instances. [default: upload]
--instance-type TEXT VM type (T4 and A10 supported).
[default: Standard_NV36ads_A10_v5]
--login / --no-login Login into Azure before deploying.
[default: login]
--resource-group TEXT Azure resource group (created if empty).
[default: ""]
```
</details>
<details>
<summary>deploy-alicloud options</summary>
```
Options:
--debug / --no-debug Enable debug output. [default: no-debug]
--prefix TEXT Prefix for all cloud resources. [default: isaacautomator]
--in-china [auto|yes|no] Is deployment in China? (Local mirrors will be
used.) [default: auto]
--deployment-name TEXT Name of the deployment. [default: <random>]
--ingress-cidrs TEXT CIDR blocks for ingress traffic, comma
separated. "myip" for your public IP.
[default: 0.0.0.0/0]
--existing [ask|repair|modify|replace|run_ansible]
What to do if deployment already exists.
[default: ask]
--isaacsim TEXT Git ref at github.com/isaac-sim/IsaacSim, or
"no". [default: v6.0.0-dev2]
--isaaclab TEXT Git ref at github.com/isaac-sim/IsaacLab, or
"no". [default: v3.0.0-beta]
--isaaclab-arena TEXT Git ref at
github.com/isaac-sim/IsaacLab-Arena, or
"no". [default: release/0.1.1]
--vnc-password TEXT Password for VNC access. [default: <random>]
--system-user-password TEXT System user password. [default: <random>]
--ssh-port TEXT SSH port. [default: 22]
--ssh-user TEXT OS username on the deployed instances.
[default: ubuntu]
--upload / --no-upload Upload user data from "uploads/" to cloud
instances. [default: upload]
--aliyun-access-key TEXT Alibaba Cloud Access Key.
[default: ALIYUN_ACCESS_KEY env var]
--aliyun-secret-key TEXT Alibaba Cloud Secret Key.
[default: ALIYUN_SECRET_KEY env var]
--region TEXT Alibaba Cloud Region ID.
[default: us-east-1]
--instance-type TEXT Instance type.
[default: ecs.gn7i-c16g1.4xlarge]
Note: --from-image is not supported on Alibaba Cloud.
```
</details>
### Credential Management
Each cloud provider's credentials are stored inside the `state/` directory so they persist across container restarts:
| Cloud | Storage Location | How Credentials Are Set |
| ------------- | --------------------- | -------------------------------------------------------------------------------- |
| AWS | `state/.aws/` or env | `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` env vars when set on the host; otherwise AWS IAM Identity Center via `aws configure sso` / `aws sso login` |
| GCP | `state/.gcp/` | `gcloud auth login` — prompted during the first deployment |
| Azure | `state/.azure/` | `az login` — prompted during the first deployment |
| Alibaba Cloud | Environment variables | `ALIYUN_ACCESS_KEY` and `ALIYUN_SECRET_KEY` — passed from the host via `./run` |
All commands that interact with cloud resources (`deploy-*`, `start`, `stop`, `destroy`, `repair`) validate credentials before proceeding and prompt you to re-authenticate if they are invalid or expired.
For AWS, if `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` are set on the host before invoking any command, they are forwarded into the container by `./run` and take precedence over the SSO flow. `AWS_SESSION_TOKEN` (for temporary credentials) and `AWS_DEFAULT_REGION` are forwarded too if set. Unset them to fall back to SSO login.
### Connecting to Deployed Isaac Workstation
Deployed Isaac Workstation can be accessed via:
- SSH
- noVNC (browser-based VNC client)
- NoMachine (remote desktop client)
Look for the connection instructions at the end of the deployment command output. Additionally, this information is saved in the `state/<deployment-name>/info.txt` file.
You can view available arguments with the `--help` switch for the start scripts. In most cases, you won't need to change the defaults.
Use `./ssh <deployment-name>` to connect to the deployed instance via SSH.
Use `./novnc <deployment-name>` to open the noVNC web client for the deployed instance.
### Running Applications
To use the installed applications, connect to the deployed Isaac Workstation using noVNC or NoMachine. You can find the connection instructions at the end of the deployment command output. Additionally, this information is saved in the `state/<deployment-name>/info.txt` file.
#### Isaac Sim
Isaac Sim is installed from source on the deployed Isaac Workstation. By default, it will automatically start when the instance is deployed. Alternatively, click the "Isaac Sim" icon on the desktop, or run the following command in a terminal on the deployed vm:
```sh
~/IsaacSim/isaac-sim.sh
```
To install a specific version of Isaac Sim, provide a valid Git reference from <https://github.com/isaac-sim/IsaacSim> as the value of the `--isaacsim` parameter to the deployment command. Use `--isaacsim no` to skip Isaac Sim installation.
##### Installing from a fork or an internal repository
By default each component is installed from its public repository. To use a fork or an internal
repository instead, either pass the repository explicitly:
```sh
./deploy-aws --isaacsim-git-repo https://github.com/my-org/IsaacSim-Internal --isaacsim v6.1.0
```
or give the repository and the ref together:
```sh
./deploy-aws --isaacsim https://github.com/my-org/IsaacSim-Internal@v6.1.0
```
The same applies to `--isaaclab` / `--isaaclab-git-repo` and `--isaaclab-arena` /
`--isaaclab-arena-git-repo`, and to the `image-*` commands. If the ref is omitted
(`--isaacsim <repo url>`), the newest release in that repository is used.
The repository and ref are checked before anything is provisioned. If that check cannot reach or
authenticate to the repository it fails immediately, saying so - it never stops to ask for a password.
**Inside the container** (the usual case - `./deploy-aws` and friends run there) neither the GitHub CLI
nor your SSH keys are available, so this check can only authenticate with credentials in the URL. An SSH
deploy key still works for the clone **on the instance**, but the check cannot use it - pass the ref
explicitly so nothing has to be auto-detected. When you run the CLI on the host instead and have the
[GitHub CLI](https://cli.github.com/) installed and logged in (`gh auth login`), the check uses it, so a
private repository verifies with the account you already use.
A private repository must also be reachable **from the deployed instance**, which is what actually
clones it. Being able to clone it on your own machine is not enough. Either:
- **Access token in the URL** (simplest), e.g.
`--isaacsim-git-repo https://<token>@github.com/my-org/IsaacSim-Internal --isaacsim <ref>`. This is
also what makes the pre-provisioning check pass inside the container. The token is masked in console
output and in the deployment's `meta.json`, but it is still sent to the instance. A ref may be appended
to the repository instead (`...IsaacSim-Internal@<ref>`) - the separator is the first `@` after the
host, so a token containing `@` has to be percent-encoded as `%40`.
- **SSH URL with a deploy key** already present on the instance, e.g.
`--isaacsim-git-repo git@github.com:my-org/IsaacSim-Internal.git`. Safer, since no credential
travels with the deployment.
A plain `https://github.com/...` URL for a private repository will fail on the instance, because it
has no credentials of its own.
#### Isaac Lab
[Isaac Lab](https://isaac-sim.github.io/IsaacLab/) is installed from source on the Isaac Workstation. To install a specific version of Isaac Lab, provide a valid Git reference from <https://github.com/isaac-sim/IsaacLab> as the value of the `--isaaclab` parameter to the deployment command. Use `--isaaclab no` to skip Isaac Lab installation.
To run Isaac Lab CLI, use the following command in the terminal on the deployed instance:
```sh
~/IsaacLab/isaaclab.sh [options]
```
#### Isaac Lab Arena
[Isaac Lab Arena](https://github.com/isaac-sim/IsaacLab-Arena) is an extension to Isaac Lab that provides multi-agent task environments and benchmarks. It is installed from source on the Isaac Workstation by default.
To install a specific version, provide a valid Git reference from <https://github.com/isaac-sim/IsaacLab-Arena> as the value of the `--isaaclab-arena` parameter to the deployment command. Use `--isaaclab-arena no` to skip installation.
Isaac Lab Arena is installed to `~/IsaacLab-Arena` on the deployed instance.
#### Demos
Isaac Automator can install ready-to-run demos on the Isaac Workstation, each exposed as a double-click shortcut on the remote desktop. Select them with the `--demos` option (comma-separated, or `no` to install none). A demo automatically enables the apps it depends on, so a single flag is enough to get a working setup.
Available demos:
- `quadruped-locomotion` — trains an ANYmal-D quadruped to walk using RSL-RL in Isaac Lab, rendered live in the Isaac Sim viewport. Depends on Isaac Sim and Isaac Lab (auto-enabled).
- `humanoid-locomotion` — trains a Unitree G1 humanoid to walk using RSL-RL in Isaac Lab. Depends on Isaac Sim and Isaac Lab (auto-enabled).
- `franka-manipulation` — trains a Franka arm to reach targets using RSL-RL in Isaac Lab. Depends on Isaac Sim and Isaac Lab (auto-enabled).
You can select several at once, e.g. `--demos quadruped-locomotion,humanoid-locomotion,franka-manipulation`.
For example, `--demos quadruped-locomotion` enables Isaac Sim and Isaac Lab automatically (using their default versions) if they were not requested. Launcher scripts are installed to `~/.local/share/isaac-automator-demos/` and can be tuned via environment variables (e.g. `HEADLESS=1`, `NUM_ENVS`, `MAX_ITERATIONS`).
### Autorun Script
By default, Isaac Sim will start when the cloud VM is deployed.
If you want to launch a custom application or script on startup, modify the [`uploads/autorun.sh`](uploads/autorun.sh) script (on your local machine). It will either be uploaded to the cloud VM automatically, or you can upload it manually using the `./upload` command.
Every time the cloud VM is deployed or started from a stopped state, the `autorun.sh` script will be executed.
This functionality can be useful for running batch jobs, generating data on startup, or preparing the environment for the user.
### Standard Folders
Two folders are used for exchanging data between your local machine and the deployed instance:
| Local (Isaac Automator) | Remote (Isaac Workstation) | Purpose |
| ----------------------- | -------------------------- | ------------------------------------------------------------------------------------------- |
| `uploads/` | `~/uploads` | Data you send to the instance. Synced automatically on deploy, or manually with `./upload`. |
| `results/` | `~/results` | Data you pull back from the instance with `./download`. |
### Pausing and Resuming
You can stop and restart instances to save on cloud costs. To do so, run the following commands:
```sh
# enter Isaac Automator container
./run
# inside container:
./stop <deployment-name>
./start <deployment-name>
```
By default, `./start` re-runs necessary Ansible steps (such as ECC disabling, etc) after starting the VM. If you're in a rush, use `--quick` to skip that and only run the autorun script:
```sh
./start <deployment-name> --quick
```
The public IP address is preserved across stop/start cycles on all supported clouds. AWS uses an Elastic IP, GCP reserves a static external address, and Azure VMs retain their public IP while the resource exists.
### Uploading Data
You can upload user data from the `uploads/` folder (in the project root) to the deployment by running the following command:
```sh
# enter Isaac Automator container
./run
# inside container:
./upload <deployment-name>
```
Data will be uploaded to the `/home/ubuntu/uploads` directory by default (the `ubuntu` part of the path depends on the configured `default_ssh_user`), on all deployed instances. You can change this by passing the `--remote-dir` argument to the command. By default, files deleted locally are also deleted on the remote side during sync; use `--no-delete` to keep remote files that no longer exist locally. Run `./upload --help` to see more options.
### Downloading Data
You can download user data to the `results/` folder (in the project root) from deployed instances by running the following command:
```sh
# enter Isaac Automator container
./run
# inside container:
./download <deployment-name>
```
Data will be downloaded from the `/home/ubuntu/results` directory by default (the `ubuntu` part of the path depends on the configured `default_ssh_user`). You can change this by passing the `--remote-dir` argument to the command. By default, local files not present on the remote side are deleted during sync; use `--no-delete` to keep them. Run `./download --help` to see more options.
### Repairing
If, for some reason, the deployment cloud resources or software configuration become corrupted, you can attempt to repair the deployment by running the following commands:
```sh
# run both terraform and ansible
./repair <deployment-name>
# just run terraform to try fixing the cloud resources
./repair <deployment-name> --no-ansible
# just run ansible to try fixing the software configuration
./repair <deployment-name> --no-terraform
```
You can also use `./repair` to update the ingress CIDR blocks (firewall rules) on an existing deployment:
```sh
# restrict access to your current IP
./repair <deployment-name> --ingress-cidrs myip
# allow a /16 subnet
./repair <deployment-name> --ingress-cidrs myip/16
# specify explicit CIDR blocks
./repair <deployment-name> --ingress-cidrs "10.0.0.0/8,192.168.1.0/24"
```
### Destroying
To destroy a deployment, run the following command:
```sh
# enter Isaac Automator container
./run
# inside container:
./destroy <deployment-name>
```
_Please note that information about the deployed cloud resources is stored in the `state/` directory. Do not delete this directory._
### Importing Existing Deployments
If you lose the `state/` directory but still have cloud resources running, you can import them back:
```sh
# enter Isaac Automator container
./run
# inside container:
./import --cloud aws --prefix isaacautomator --region us-east-1
```
The `./import` command discovers cloud resources by their name prefix, imports them into Terraform state, and reconstructs the deployment metadata. After import, `./stop`, `./start --quick`, and `./destroy` will work.
Deployments that already exist locally in `state/` are automatically skipped.
Key options:
- `--cloud` — Cloud provider: `aws`, `azure`, or `gcp`.
- `--prefix` — Resource name prefix used during deployment (default: `isaacautomator`).
- `--region` — Cloud region (or GCP zone) to search in.
- `--project` — GCP project ID (required for GCP, auto-detected from `gcloud config` if not provided).
- `--deployment-name` — Import only a specific deployment instead of all discovered ones.
- `--yes` — Skip confirmation prompts.
**Important:** The original SSH private key (`key.pem`) cannot be recovered from the cloud. After import, replace `state/<deployment-name>/key.pem` with your backed-up copy to restore SSH access.
### Speeding Up Deployment with Pre-Built Images
You can build pre-baked VM images so future deployments skip the lengthy software-install phase. Pass `--from-image` to `./deploy-<cloud>` to use the most recent image. Image builds wrap Packer and handle cloud credential management automatically.
| Command | Cloud | Image type |
| ------------- | ----- | ------------------------------------ |
| `./image-aws` | AWS | AMI in the active region |
| `./image-azure` | Azure | Managed image in a resource group |
| `./image-gcp` | GCP | Custom image in the active project |
All three commands share the same workflow:
```sh
# enter Isaac Automator container
./run
# inside container:
./image-aws # or ./image-azure / ./image-gcp
```
The image name defaults to the current date. The cloud-specific prefix is added automatically. When deploying with `--from-image`, Terraform picks the most recent image matching the prefix.
#### `./image-aws`
Builds an AMI prefixed with `isaacautomator.isaacworkstation.`.
Key options:
- The image name can be passed as a positional argument: `./image-aws my-image-name`
- `--instance-type` — Instance type for the Packer build (G4dn, G5, G6, G6e supported; default: `g6e.2xlarge`)
- `--region` — AWS Region, can be entered as `us-east-1` or `US East 1` (default: `us-east-1`)
- `--existing` — `overwrite` or `fail` if an AMI with the same name already exists (default: `fail`)
- `--isaacsim` / `--isaaclab` / `--isaaclab-arena` — Git refs to bake into the image
Tip: Run `./image-aws --help` to see all options.
#### `./image-azure`
Builds an Azure managed image prefixed with `isaac_automator.isaacworkstation.`. The image is stored in the resource group given by `--resource-group` (default: `isaac_automator.packer`, created automatically if missing).
Key options:
- The image name can be passed as a positional argument: `./image-azure my-image-name`
- `--instance-type` — VM size for the Packer build (T4/A10 series, see `./image-azure --help`; default: `Standard_NV36ads_A10_v5`)
- `--region` — Azure location (default: `westus3`)
- `--resource-group` — Resource group where the captured image is stored (default: `isaac_automator.packer`)
- `--existing` — `overwrite` or `fail` if an image with the same name already exists (default: `fail`)
- `--login` / `--no-login` — Whether to run `az login` first (default: `--login`)
- `--isaacsim` / `--isaaclab` / `--isaaclab-arena` — Git refs to bake into the image
Tip: Run `./image-azure --help` to see all options.
#### `./image-gcp`
Builds a GCP custom image prefixed with `isaac-automator-isaacworkstation-` (GCP image names are lowercase and use dashes).
Key options:
- The image name can be passed as a positional argument: `./image-gcp my-image-name`
- `--project` — GCP project ID (defaults to the active `gcloud` project)
- `--zone` — Zone for the Packer build instance (default: `us-central1-a`)
- `--instance-type` — Instance type for the Packer build (G2/N1/G4 supported; default: `g2-standard-8`)
- `--gpu-type` / `--gpu-count` — GPU accelerator to attach during build (defaults: `nvidia-l4`, `1`). Use `nvidia-tesla-t4` with `n1-*`, `nvidia-l4` with `g2-*`, `nvidia-rtx-pro-6000` with `g4-*`.
- `--existing` — `overwrite` or `fail` if an image with the same name already exists (default: `fail`)
- `--isaacsim` / `--isaaclab` / `--isaaclab-arena` — Git refs to bake into the image
Tip: Run `./image-gcp --help` to see all options.
## Tips
### Persisting Modifications to the deployed Isaac Workstation
Isaac Workstation local data is persistent and survives `./stop`/`.start` cycles.
For changes that need to be re-applied automatically on every deployment or `./start`, modify the [`uploads/autorun.sh`](uploads/autorun.sh) script. This script runs each time the instance is deployed or started (see [Autorun Script](#autorun-script)).
For example, you can use `autorun.sh` to install additional Python packages, apply patches, or run setup scripts:
```sh
#!/bin/sh
# This script is executed when
# 1. the VM is first deployed
# 2. the VM is started after being stopped
SELF_DIR="$(dirname $0)"
# example: install additional packages into the Isaac Lab environment
pip install torch
```