Sandboxes

Learn how administrators manage secure sandboxes: live sessions, sandbox configurations, classes, policies, container images, AKS node pools, and cluster defaults.

Overview

A sandbox is an isolated Kata VM pod on Azure Kubernetes Service (AKS) that an agent uses to run commands for a conversation. Administrators control sandboxes through three published resources:

Resource	Defines
Sandbox class	The container image and the capacity: CPU, memory, GPU, and storage limits
Sandbox policy	The security rules: persistence and storage, file transfer shielding and limits, package installation, command limits, command (seccomp) filter, and network access
Sandbox configuration	A class plus a policy, the node pool, the idle timeout and maximum lifetime, and secrets injected as environment variables

Agents reference a sandbox configuration. Classes and policies are versioned: editing one publishes a new immutable revision.

This page covers day-to-day administration in the Management Portal. To deploy the sandbox infrastructure, see Sandbox Deployment.

Prerequisites

The FoundationaLLM.ManagementPortal.Sandbox feature flag is enabled for you. Without it, Sandboxes does not appear in the sidebar and the agent editor has no Sandbox tab. See Configuration.
Sandbox infrastructure is deployed and the AKS defaults are configured.
Permissions on the FoundationaLLM.Platform sandbox resource types (sandboxes, sandboxConfigurations, sandboxClasses, sandboxPolicies, sandboxNodePools, sandboxContainerImages).

Open the Sandboxes Page

Sign in to the Management Portal.
In the sidebar, select Platform > Sandboxes.

The page has the tabs Sessions, Configurations, Classes, Policies, Container Images, Node pools, and AKS defaults. The selected tab is kept in the page URL.

Monitor Sessions

The Sessions tab lists sandboxes and refreshes automatically every few seconds.

Filters:

Filter	Description
Search box	Search sandboxes by name
Lifecycle	Active (default), Terminated, or All. Choosing Terminated prefills Created from with the last 30 days.
AKS cluster, Node pool, UPN	Narrow the list to one cluster, pool, or user
Created from / Created to	Creation date range

Select Clear filters to reset them.

Columns: Activity, AKS Pool, Name, UPN, Created, Image, and Actions.

The Activity indicator shows Executing (a command is running), Active (recent activity), Idle, Terminated, or Unknown. Hover over it to see the last activity and the time until idle reclaim. For terminated sandboxes, the tooltip shows when the sandbox ended, who deleted it, and the reason: Manual delete, Idle reclaim, or Max lifetime reclaim.

Actions:

View JSON definition — shows the sandbox resource.
View — opens View Sandbox with the session (agent, conversation ID, context, endpoint, UPN, created time), the Effective security snapshot (class, policy, image, capacity, filesystem, network, processes, command filter, persistence, shields, effective revision), the managed deployment, and its observed status. Use Access Control on this page to manage role assignments on the sandbox.
Delete — deletes a live sandbox after confirmation (Delete Sandbox). Select several rows and use the Delete bulk action to delete them together.

Terminated sandboxes stay in the list as history and cannot be selected or deleted.

Manage Sandbox Configurations

On the Configurations tab, the list shows Name, Revision, Class, Policy, Idle timeout, Max lifetime, and Node pool.

Select Create configuration, or the pencil icon to edit one.

Complete the dialog:

Field	Description
Name	Configuration name (cannot be changed after creation)
Revision	Read-only
Sandbox class	Class revision to use. A summary line shows CPU, memory, storage, and image.
Sandbox policy	Policy revision to use. A summary line shows persistence, network mode, destinations, and command timeout.
Node pool	AKS node pool. Empty means the cluster default.
Idle timeout (s)	Reclaims an idle sandbox after this many seconds. 0 disables idle reclaim (default 1800).
Max lifetime (s)	Maximum sandbox lifetime. 0 means no limit.

Under Secrets, select Add secret for each environment variable to inject when the pod is created:
- Environment variable — the variable name, for example ANTHROPIC_API_KEY.
- Source — New Value stores the value in Key Vault under an auto-generated configuration key; Existing Config references an existing App Configuration key (search with Search app configurations...).
- Commands — check to expose the variable to executor commands. Exposed variables need an UPPERCASE name.
Select Create or Save.

Lifecycle changes apply to sandboxes that use the configuration after caches refresh, usually within a few seconds.

Manage Sandbox Classes

The Classes tab shows one row per class (latest revision) with Name, Latest revision, Capacity, and Container image.

Select Create class, or the pencil icon to browse revisions of an existing class.

Set the fields:

Field	Description
Name	Class name
Revision	When editing, select an existing revision to view it. Existing revisions are immutable.
Container image	Image (by digest) from the sandbox registries
CPU, Memory, GPU	Pod capacity
Workspace (MB)	Maximum the sandbox may write under `/workspace`
Temporary (MB)	Memory-backed `/tmp` (maximum 1024 MB)
Private root (MB)	Disk for the writable image copy when the policy allows package installs (2048 MB if omitted)

Select Create, or Create New Revision when editing.

Manage Sandbox Policies

The Policies tab shows one row per policy (latest revision) with Display name, Description, Latest revision, and Persistence.

Select Create policy, or the pencil icon to edit a policy.

Use the navigation on the left of the editor to move between domains:

Domain	Settings
Policy Overview	Display name, Revision, Name (derived from the display name), Description, Based on revision
Persistence	Storage Mode: Ephemeral or Persistent workspace. For persistent workspaces, choose how `/workspace` is stored: Standard file share, Shared SSD, Dedicated SSD file share (with provisioned size), or Dedicated managed disk (Premium SSD, Premium SSD v2, or Ultra disk with size, IOPS, and throughput).
Pod Input & Output	Shield uploads, Shield downloads, and transfer limits (Max upload per transfer (MB), Max download per transfer (MB), Max single file (MB))
Outer Layer	Read-only summary of the Kubernetes and Kata VM isolation
Inner Layer > Package Installation	APT packages, Require repository signatures, Block unauthenticated packages, Approved APT repositories, Python PIP, Node NPM
Inner Layer > Runtime	Command timeout (seconds), Max processes, Output cap (MB), /proc visibility, and read-only details about mounts and process isolation
Inner Layer > Command Filter	Tunable seccomp groups (outbound sockets, extended file attributes, advanced IPC, scheduling, clock adjustment) and syscall exceptions with a justification
Inner Layer > Network	Mode (outbound): No network (no Internet) or Proxy allowlist (listed hosts); allowed destinations (host, protocol, port); Package download limit (MB)

Select Create, or Create New Revision when editing.

When editing, you can also select Compare with selected to see the differences between this revision and its parent, or Delete revision to delete the selected revision. The trash icon in the list deletes all revisions of a policy. Revisions referenced by a sandbox configuration cannot be deleted.

Idle timeout and maximum lifetime are set on the sandbox configuration, not on the policy.

Review Container Images

The Container Images tab lists images from the configured sandbox registries, newest first, with Repository, Registry, Tag, Digest, Created, and Updated. Filter by repository with All repositories.

Select the eye icon to open View Container Image Details:

Overview — repository, tag, digest, image reference, dates, and whether an SBOM, Trivy results, and a signature were found.
Contents — the SBOM inventory grouped as Python, System, Runtime, and Files, and View complete SBOM (CycloneDX).
Signature — Cosign signature details.

Manage Node Pools

The Node pools tab shows a card per AKS node pool with badges (Default, System, Kata, Ultra) and metrics: Role, VM, Zones, Status, Nodes, Sandboxes, CPU free, Memory free, Headroom, and Autoscaler. Select a class in Headroom for to see roughly how many more sandboxes of that class fit on each pool.

Create a pool:

Select Create pool. New pools are User mode, Azure Linux, and Kata VM isolation.
Choose a Preset: General sandbox, Ultra-capable sandbox, or Custom.
Enter the Name (1–12 lowercase letters or digits, starting with a letter), VM size, Node count, and Availability zone (required for Ultra SSD and Premium SSD v2).
Optionally select Enable Ultra SSD and Set as the cluster-wide default fallback pool.
Select Create.

Edit a pool: select the pencil icon (not available for system pools). Turn Cluster autoscaler on and set Minimum nodes and Maximum nodes, or turn it off and set Node count. Select Save.

Edit AKS Defaults

The AKS defaults tab edits the cluster-wide defaults for sandbox pods, stored in the App Configuration key FoundationaLLM:APIEndpoints:ContextAPI:Configuration:SandboxCodeSessionService:AKSSandboxDefaults.

Section	Settings
Cluster and scheduling	AKS cluster resource ID, Namespace, Default node pool, tolerations (Add toleration)
Session container	Container image, Extra container registry login server, Port, CPU, Memory
Sidecars	Files sidecar image, Files sidecar port, Workspace quota image
Readiness	Poll interval (seconds), Timeout (seconds)
Workspace storage	Storage classes for each workspace storage option, and the Workspace service account
Gateway and networking	Hostname, Gateway name, TLS certificate secret name, external and private IP options, Path prefix, Path rewrite prefix

Select Save and confirm Save AKS defaults, or Reset to discard changes.

Important

Restart the Context API (and the Management API for image catalog and node pool defaults) before the new values take effect.

Assign a Sandbox Configuration to an Agent

Open the agent in the agent editor (Agents > Agents, then the pencil icon). The Sandbox tab is available only when editing an existing agent.
Select the Sandbox tab.
In Sandbox Configuration, select a configuration, or No sandbox capability to remove sandbox access.
Review Effective published references (configuration, class, and policy revisions).
Select Save Changes.

New sandboxes use the selected configuration. Existing sandboxes keep their configuration snapshot.

Table of Contents