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

# Use Azure Sandboxes

> Ask Genesis agents to run code in Azure: prompts to try, what to expect, images, sizes, networking and lifecycle options.

Once an administrator has [set up Azure sandboxes](/docs/Setup/Azure-Sandboxes-Setup), you use
them by asking a Genesis agent in plain language. The agent starts the sandbox, moves data in,
runs the code, brings the results back and stops the sandbox. You do not need to know Azure or
write any code yourself.

## Prompts to try

Say **Azure sandbox** in your request so the agent uses Azure rather than another sandbox type.
If you have more than one Azure connection, name the one to use.

<AccordionGroup>
  <Accordion title="Analyze data from Snowflake">
    ```text theme={null}
    Start an Azure sandbox with our Azure connection. Pull last month's and this month's order
    totals by store from Snowflake, compute month-over-month growth by store in pandas, rank the
    stores, write the result to a CSV and give it to me. Then stop the sandbox.
    ```

    The agent queries Snowflake with Genesis's own Snowflake connection, uploads the result into
    the sandbox as a file, runs the analysis there and downloads the CSV. In testing, a run like
    this moved about 196,000 transactions into the sandbox, produced a 99-row CSV, and its grand
    total matched a separate Snowflake query to the cent.
  </Accordion>

  <Accordion title="Run a script">
    ```text theme={null}
    In an Azure sandbox, run this Python script against the attached CSV and show me the output.
    ```

    Attach the script and the data to the chat, or point the agent at a file in a Genesis
    repository. The agent uploads both and runs the script.
  </Accordion>

  <Accordion title="Install packages">
    ```text theme={null}
    Start an Azure sandbox, install scikit-learn and statsmodels, and fit a linear trend to the
    weekly sales numbers I pasted above.
    ```

    The agent installs packages with `pip install` inside the sandbox. They stay installed until
    the sandbox stops.
  </Accordion>

  <Accordion title="Produce files">
    ```text theme={null}
    Use an Azure sandbox to turn this table into a bar chart PNG and an Excel workbook with one
    sheet per region, and save both to our analysis repository.
    ```

    The agent writes the files in the sandbox, then downloads them and saves them where you ask,
    for example a Genesis repository, or shows their contents in the chat.
  </Accordion>

  <Accordion title="Keep a sandbox for a working session">
    ```text theme={null}
    Start an Azure sandbox with 2 CPUs and 4 GB of memory and keep it running while we work
    through this dataset. I'll tell you when to stop it.
    ```

    Files and packages persist between commands, so you can build on earlier steps. Stop it when
    you are done, or it stops on its own after its idle timeout.
  </Accordion>
</AccordionGroup>

## What to expect

| | |
| - | - |
| **Start** | About 25 to 30 seconds with the default image. Larger custom images take longer. |
| **Each command** | About two seconds of overhead, plus the command's own run time. The agent can combine steps into one script to save time. |
| **Files and packages** | Persist inside the sandbox between commands until it stops. When it stops, everything in it is deleted, so ask the agent to download what you want to keep first. |
| **Output** | Each command's output, and its exit status, come back to the agent checked for integrity. Large outputs work; 4 MB of output took about 7 seconds in testing. |
| **Time limit per command** | Five minutes unless the agent sets a longer limit. A command that runs out of time is stopped and reported as timed out. |

## Images

By default a sandbox runs **Python 3.11** on a slim Debian Linux image (`python:3.11-slim`).
Genesis pulls it from Microsoft's mirror at
`mcr.microsoft.com/mirror/docker/library/python:3.11-slim` rather than from Docker Hub, because
Docker Hub limits anonymous downloads from the shared addresses Azure Container Instances uses.
Asking for `python:3.11-slim` by name also uses the mirror.

To use another image, such as one your team builds with your own tools and packages already
installed, ask the agent to start the sandbox with it. Any image other than `python:3.11-slim` is
used exactly as given. It must be a **Linux** image that includes `/bin/sh` and these standard
tools, which every image based on coreutils or BusyBox has: `base64`, `sha256sum`, `cat`, `cut`,
`wc`, `cp`, `dd`, `tr`, `mkdir` and `rm`. Genesis also uses `stty` when the image has it.

<Tip>
  Prefer images from Microsoft Container Registry (`mcr.microsoft.com`) or your own Azure Container
  Registry. Images pulled anonymously from Docker Hub can fail with
  `An error response is received from the docker registry 'index.docker.io'. Please retry later.`
</Tip>

### Private registries

To pull an image from a private registry, such as your own Azure Container Registry, the agent
passes the registry's address and credentials when it starts the sandbox:

| `backend_options` key | Example |
| - | - |
| `registry_server` | `myregistry.azurecr.io` |
| `registry_username` | A registry user name, token name or service principal ID with pull access |
| `registry_password` | Its password or token |

Use credentials that can only pull images, and only from the repositories the sandbox needs.

<Note>
  Private registry support is in place but was not tested end to end at launch. Try it in a
  non-production resource group first.
</Note>

## Size

Each sandbox gets **1 vCPU and 1.5 GB of memory** by default. Ask for more when the work needs
it, for example "start an Azure sandbox with 2 CPUs and 8 GB of memory". The agent passes
`cpu_cores` and `memory_gb`. The largest size you can get depends on what Azure Container
Instances offers in your region and on your subscription's quota; see
[Azure Container Instances resource availability](https://learn.microsoft.com/azure/container-instances/container-instances-resource-and-quota-limits).
Azure bills for the size you ask for while the sandbox runs.

## Region

Sandboxes run in the **Region** set on the Azure connection, or `eastus` when it is empty. The
connection's approved network access covers that region's command endpoint only, so Genesis
refuses a request to start a sandbox through the connection in a different region. To use a
second region, ask an administrator to create a second Azure connection for it.

## Run inside your virtual network

By default the sandbox can reach the internet, which is what lets it install packages. To control
what it can reach, or to let it reach private resources in your network, attach it to a subnet in
your own Azure virtual network with the `subnet_id` option, set to the subnet's full resource ID:

```text theme={null}
/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<network-rg>/providers/Microsoft.Network/virtualNetworks/<vnet>/subnets/<subnet>
```

Azure requires:

* The subnet is **delegated** to `Microsoft.ContainerInstance/containerGroups`.
* The subnet is in the **same region** as the sandbox.
* The service principal may join that subnet, for example through **Network Contributor** on the
  virtual network, or a role that includes `Microsoft.Network/virtualNetworks/subnets/join/action`
  on the subnet.

The sandbox's outbound traffic then follows your virtual network's routes, network security groups
and firewall. A sandbox in a subnet reaches the internet only through an outbound path you provide,
such as a **NAT gateway** on the subnet or a route through your firewall. If the agent should still
install packages, give the subnet that path and allow `pypi.org` and `files.pythonhosted.org` on
port 443, or point `pip` at your own package mirror.

Attaching a subnet changes only the sandbox's own traffic. Genesis still reaches the sandbox
through Azure's management and command endpoints as described in
[Allow Genesis to reach Azure](/docs/Setup/Azure-Sandboxes-Setup#allow-genesis-to-reach-azure).

<Note>
  Virtual network support is in place but was not tested end to end at launch. Try it in a
  non-production resource group first.
</Note>

## Options reference

Agents start an Azure sandbox with the `sandbox_action` tool, `action="start"` and
`backend="azure_aci"`. You do not need these names to use the feature, but they help when you
write instructions for an agent, a skill or a flow.

| `backend_options` key | Default | Description |
| - | - | - |
| `credential_name` | Your default Azure connection | The Genesis Azure connection to use. |
| `subscription_id` | The connection's | Run in another subscription the service principal has access to. |
| `resource_group` | The connection's | Run in another resource group the service principal has access to. |
| `location` | The connection's Region, or `eastus` | Must name the connection's Region; see [Region](#region). |
| `cpu_cores` | `1` | vCPUs for the container. |
| `memory_gb` | `1.5` | Memory in GB. |
| `subnet_id` | None | Subnet resource ID to attach the sandbox to. See [Run inside your virtual network](#run-inside-your-virtual-network). |
| `registry_server` | None | Private registry host, for example `myregistry.azurecr.io`. |
| `registry_username` | None | User name for the private registry. |
| `registry_password` | None | Password or token for the private registry. |

Other `start` parameters that matter for Azure:

| Parameter | Default | Description |
| - | - | - |
| `image` | `python:3.11-slim` (from Microsoft's mirror) | The container image. See [Images](#images). |
| `idle_timeout_minutes` | `30` | Stop the sandbox after this long with no activity. |
| `max_lifetime_minutes` | `480` (8 hours) | The container exits after this long, whatever it is doing. |

Agents cannot pass Azure credentials (`tenant_id`, `client_id`, `client_secret`) in
`backend_options`. Genesis refuses such a start and asks for a saved connection instead.

Before starting, an agent can run `action="check_backend_connection"` with
`backend="azure_aci"` to confirm the setup, and `action="list_backend_connections"` to list the
Azure connections you can use. The full tool reference is in
[Sandbox tools](/docs/Genbot-Toolkit/Additional-Tool-Groups#azure-container-instances).

## Lifecycle

| Event | What happens |
| - | - |
| **Stop** | Genesis deletes the container group, with everything in it. The agent stops the sandbox when the task is done; you can also stop it from **Sandbox Sessions**. |
| **Idle timeout** | Genesis's sandbox monitor stops a sandbox with no activity for its idle timeout (30 minutes by default). The monitor runs every few minutes, so the stop can come a few minutes after the limit. |
| **Maximum lifetime** | The container exits at the end of its maximum lifetime (8 hours by default), even if Genesis is unavailable, and Azure compute billing for it stops. Genesis then deletes the container group. |
| **Genesis restarts** | Running sandboxes are reattached and keep working. Sandboxes that ended while Genesis was down are deleted. |

See [Lifecycle and cost safety](/docs/Setup/Azure-Sandboxes-Overview#lifecycle-and-cost-safety) for
how these work together, and [Sandbox Sessions](/docs/User-Guide/Sandbox-Sessions) for managing
sessions from the Genesis UI.