Azure Container Apps dynamic sessions overview

Azure Container Apps dynamic sessions provide fast access to secure sandboxed environments that are ideal for running code or applications that require strong isolation from other workloads.

Sessions have the following attributes:

• Strong isolation: Sessions are isolated from each other and from the host environment. Each session runs in its own Hyper-V sandbox, providing enterprise-grade security and isolation. Optionally, you can enable network isolation to further enhance security.

• Simple access: Sessions are accessed through a REST API. A unique identifier marks each session. If a session with a given identifier doesn't exist, a new session is automatically allocated.

• Fully managed: The platform fully manages a session's lifecycle. Sessions are automatically cleaned up when no longer in use.

• Fast startup: A new session is allocated in milliseconds. Rapid start-ups are achieved by automatically maintaining a pool of ready but unallocated sessions.

• Scalable: Sessions can run at a high scale. You can run hundreds or thousands of sessions concurrently.

Note

Azure Container Apps dynamic sessions is currently in preview.

Session types

Azure Container Apps supports two types of sessions:

Type	Description	Billing model
Code interpreter	Fully managed code interpreter	Per session (consumption)
Custom container	Bring your own container	Container Apps Dedicated Plan

Code interpreter

Code interpreter sessions allow you to run code in a sandbox that is preinstalled with popular libraries. They're ideal for running untrusted code, such as code provided by users of your application or code generated by a large language model (LLM). Learn more about code interpreter sessions.

Custom container

Custom container sessions allow you to run your own container images in secure, isolated sandboxes. You can use them to run a custom code interpreter for a language that isn't supported out of the box, or to run workloads that require strong isolation. Learn more about custom container sessions.

Concepts

The key concepts in Azure Container Apps dynamic sessions are session pools and sessions.

Session pools

To provide sub-second session allocation times, Azure Container Apps maintains a pool of ready but unallocated sessions. When you submit a request to a new session, the platform allocates a session from the pool to you. As sessions are allocated, the platform automatically replenishes the pool to maintain a constant number of ready sessions.

You can configure pools to set the maximum number of sessions that can be allocated concurrently via the maxConcurrentSessions property. You can set the wait duration from the last request before a session is deleted the cooldownPeriodInSeconds property. For custom container sessions, you can also specify the container image and settings to use for the sessions in the pool, including the target number of sessions to keep ready in the pool via readySessionInstances.

Sessions

A session is a sandboxed environment that runs your code or application. Each session is isolated from other sessions and from the host environment with a Hyper-V sandbox. Optionally, you can enable network isolation to further enhance security.

Session identifiers

When you interact with sessions in a pool, you must define a session identifier to manage each session. The session identifier is a free-form string, meaning you can define it in any way that suits your application's needs. This identifier is a key element in determining the behavior of the session:

• Reuse of existing sessions: This session is reused if there's already a running session that matches the identifier.
• Allocation of new sessions: If no running session matches the identifier, a new session is automatically allocated from the pool.

The session identifier is a string that you define that is unique within the session pool. If you're building a web application, you can use the user's ID. If you're building a chatbot, you can use the conversation ID.

The identifier must be a string that is 4 to 128 characters long and can contain only alphanumeric characters and special characters from this list: |, -, &, ^, %, $, #, (, ), {, }, [, ], ;, <, and >.

You pass the session identifier in a query parameter named identifier in the URL when you make a request to a session.

For code interpreter sessions, you can also use an integration with an LLM framework. The framework handles the token generation and management for you. Ensure that the application is configured with a managed identity that has the necessary role assignments on the session pool.

Protecting session identifiers

The session identifier is sensitive information which requires a secure process as you create and manage its value. To protect this value, your application must ensure each user or tenant only has access to their own sessions.

The specific strategies that prevent misuse of session identifiers differ depending on the design and architecture of your app. However, your app must always have complete control over the creation and use of session identifiers so that a malicious user can't access another user's session.

Example strategies include:

• One session per user: If your app uses one session per user, each user must be securely authenticated, and your app must use a unique session identifier for each logged in user.
• One session per agent conversation: If your app uses one session per AI agent conversation, ensure your app uses a unique session identifier for each conversation that can't be modified by the end user.

Important

Failure to secure access to sessions may result in misuse or unauthorized access to data stored in your users' sessions.

Authentication

Authentication is handled using Microsoft Entra (formerly Azure Active Directory) tokens. Valid Microsoft Entra tokens are generated by an identity belonging to the Azure ContainerApps Session Executor and Contributor roles on the session pool.

To assign the roles to an identity, use the following Azure CLI commands:

az role assignment create \
    --role "Azure ContainerApps Session Executor" \
    --assignee <PRINCIPAL_ID> \
    --scope <SESSION_POOL_RESOURCE_ID>

az role assignment create \
    --role "Contributor" \
    --assignee <PRINCIPAL_ID> \
    --scope <SESSION_POOL_RESOURCE_ID>

If you're using an LLM framework integration, the framework handles the token generation and management for you. Ensure that the application is configured with a managed identity with the necessary role assignments on the session pool.

If you're using the pool's management API endpoints directly, you must generate a token and include it in the Authorization header of your HTTP requests. In addition to the role assignments previously mentioned, token needs to contain an audience (aud) claim with the value https://dynamicsessions.io.

Azure CLI

To generate a token using the Azure CLI, run the following command:

az account get-access-token --resource https://dynamicsessions.io

C#

In C#, you can use the Azure.Identity library to generate a token. First, install the library:

dotnet add package Azure.Identity

Then, use the following code to generate a token:

using Azure.Identity;

var credential = new DefaultAzureCredential();
var token = credential.GetToken(new TokenRequestContext(new[] { "https://dynamicsessions.io/.default" }));
var accessToken = token.Token;

JavaScript

In JavaScript, you can use the @azure/identity library to generate a token. First, install the library:

npm install @azure/identity

Then, use the following code to generate a token:

const { DefaultAzureCredential } = require("@azure/identity");
const { TokenCredential } = require("@azure/core-auth");

const credential = new DefaultAzureCredential();
const token = await credential.getToken("https://dynamicsessions.io/.default");
const accessToken = token.token;

Python

In Python, you can use the azure-identity library to generate a token. First, install the library:

pip install azure-identity

Then, use the following code to generate a token:

from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
token = credential.get_token("https://dynamicsessions.io/.default")
access_token = token.token

Important

A valid token can be used to create and access any session in the pool. Keep your tokens secure and don't share them with untrusted parties. End users should access sessions through your application, not directly.

Lifecycle

The Container Apps runtime automatically manages the lifecycle for each session in a session pool.

• Pending: When a session is starting up, it's in the pending state. The amount of time a session spends in the pending state depends on the container image and settings you specify for the session pool. A pending session isn't added to the pool of ready sessions.

• Ready: When a session is done starting up and is ready, it's added to the pool. The session is available at this state for allocation. For custom container sessions, you can specify the target number of ready sessions to keep in the pool. Increase this number if sessions are allocated faster than the pool is being replenished.

• Allocated: When you send a request to a non-running session, the pool provides a new session and placed it in an allocated state. Subsequent requests with the same session identifier are routed to the same session.

• Deleting: When a session stop receiving requests during the time defined by the cooldownPeriodInSeconds setting, the session and its Hyper-V sandbox are completely and securely deleted.

Security

Azure Container Apps dynamic sessions are built to run untrusted code and applications in a secure and isolated environment. While sessions are isolated from one another, anything within a single session, including files and environment variables, is accessible by users of the session. You should only configure or upload sensitive data to a session if you trust the users of the session.

Preview limitations

Azure Container Apps dynamic sessions is currently in preview. The following limitations apply:

• It's only available in the following regions:

  Region	Code interpreter	Custom container
  East Asia	✔	✔
  East US	✔	✔
  West US 2	✔	✔
  North Central US	✔	-
  North Europe	✔	-

• Logging isn't supported. Your application can log requests to the session pool management API and its responses.

Next steps

Code interpreter sessions