Use Azure Sandboxes

Once an administrator has set up Azure sandboxes, 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.

Analyze data from Snowflake

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.

Run a script

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.

Install packages

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.

Produce files

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.

Keep a sandbox for a working session

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.

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.

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.

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.

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

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

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

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

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

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 for how these work together, and Sandbox Sessions for managing sessions from the Genesis UI.

Getting Started

Getting to Know Genesis

Creating A Mission

User Guide

Blueprint

Genesis Data Agents

Genesis Prover

Genesis Apps

Genesis REST API

Genesis Agent Security Controls

Genesis Data Agent's Toolkit

Setup

Slack and Teams

Data Connections

Deployment Options

Prompts to try

What to expect

Images

Private registries

Size

Region

Run inside your virtual network

Options reference

Lifecycle

​Prompts to try

​What to expect

​Images

​Private registries

​Size

​Region

​Run inside your virtual network

​Options reference

​Lifecycle

Prompts to try

What to expect

Images

Private registries

Size

Region

Run inside your virtual network

Options reference

Lifecycle