/containers

Manage OpenAI and Azure OpenAI code interpreter containers (sessions) for executing code in isolated environments.

tip

Looking for how to use Code Interpreter? See the Code Interpreter Guide.

Feature	Supported
Cost Tracking	✅
Logging	✅ (Full request/response logging)
Load Balancing	✅
Proxy Server Support	✅ Full proxy integration with virtual keys
Spend Management	✅ Budget tracking and rate limiting
Supported Providers	`openai`, `azure`

tip

Containers provide isolated execution environments for code interpreter sessions. You can create, list, retrieve, and delete containers.

LiteLLM Python SDK Usage

Quick Start

Create a Container

import litellm
import os 

# setup env
os.environ["OPENAI_API_KEY"] = "sk-.."

container = litellm.create_container(
    name="My Code Interpreter Container",
    custom_llm_provider="openai",
    expires_after={
        "anchor": "last_active_at",
        "minutes": 20
    }
)

print(f"Container ID: {container.id}")
print(f"Container Name: {container.name}")

Async Usage

from litellm import acreate_container
import os 

os.environ["OPENAI_API_KEY"] = "sk-.."

container = await acreate_container(
    name="My Code Interpreter Container",
    custom_llm_provider="openai",
    expires_after={
        "anchor": "last_active_at",
        "minutes": 20
    }
)

print(f"Container ID: {container.id}")
print(f"Container Name: {container.name}")

List Containers

from litellm import list_containers
import os 

os.environ["OPENAI_API_KEY"] = "sk-.."

containers = list_containers(
    custom_llm_provider="openai",
    limit=20,
    order="desc"
)

print(f"Found {len(containers.data)} containers")
for container in containers.data:
    print(f"  - {container.id}: {container.name}")

Async Usage:

from litellm import alist_containers

containers = await alist_containers(
    custom_llm_provider="openai",
    limit=20,
    order="desc"
)

print(f"Found {len(containers.data)} containers")
for container in containers.data:
    print(f"  - {container.id}: {container.name}")

Retrieve a Container

from litellm import retrieve_container
import os 

os.environ["OPENAI_API_KEY"] = "sk-.."

container = retrieve_container(
    container_id="cntr_123...",
    custom_llm_provider="openai"
)

print(f"Container: {container.name}")
print(f"Status: {container.status}")
print(f"Created: {container.created_at}")

Async Usage:

from litellm import aretrieve_container

container = await aretrieve_container(
    container_id="cntr_123...",
    custom_llm_provider="openai"
)

print(f"Container: {container.name}")
print(f"Status: {container.status}")
print(f"Created: {container.created_at}")

Delete a Container

from litellm import delete_container
import os 

os.environ["OPENAI_API_KEY"] = "sk-.."

result = delete_container(
    container_id="cntr_123...",
    custom_llm_provider="openai"
)

print(f"Deleted: {result.deleted}")
print(f"Container ID: {result.id}")

Async Usage:

from litellm import adelete_container

result = await adelete_container(
    container_id="cntr_123...",
    custom_llm_provider="openai"
)

print(f"Deleted: {result.deleted}")
print(f"Container ID: {result.id}")

LiteLLM Proxy Usage

LiteLLM provides OpenAI API compatible container endpoints for managing code interpreter sessions:

/v1/containers - Create and list containers
/v1/containers/{container_id} - Retrieve and delete containers

Setup

$ export OPENAI_API_KEY="sk-..."

$ litellm

# RUNNING on http://0.0.0.0:4000

The OpenAI key can also live in model_list instead of the environment. Pass that deployment's model in the create body or as a model query param on list, and the proxy calls OpenAI with the deployment's api_key and api_base. Retrieve, delete, and container file calls need no model: the ID a routed create returns encodes the deployment, so they route on their own

model_list:
  - model_name: gpt-5.6
    litellm_params:
      model: openai/gpt-5.6
      api_key: os.environ/OPENAI_API_KEY_TEAM_A

$ litellm --config config.yaml

Custom Provider Specification

You can specify the custom LLM provider in multiple ways (priority order):

Header: -H "custom-llm-provider: openai"
Query param: ?custom_llm_provider=openai
Request body: {"custom_llm_provider": "openai", ...}
Defaults to "openai" if not specified

Create a Container

# Default provider (openai)
curl -X POST "http://localhost:4000/v1/containers" \
    -H "Authorization: Bearer $LITELLM_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "name": "My Container",
        "expires_after": {
            "anchor": "last_active_at",
            "minutes": 20
        }
    }'

# Via header
curl -X POST "http://localhost:4000/v1/containers" \
    -H "Authorization: Bearer $LITELLM_API_KEY" \
    -H "custom-llm-provider: openai" \
    -H "Content-Type: application/json" \
    -d '{
        "name": "My Container"
    }'

# Via query parameter
curl -X POST "http://localhost:4000/v1/containers?custom_llm_provider=openai" \
    -H "Authorization: Bearer $LITELLM_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "name": "My Container"
    }'

# With model_list credentials: name the deployment
curl -X POST "http://localhost:4000/v1/containers" \
    -H "Authorization: Bearer $LITELLM_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "name": "My Container",
        "model": "gpt-5.6"
    }'

List Containers

curl "http://localhost:4000/v1/containers?limit=20&order=desc" \
    -H "Authorization: Bearer $LITELLM_API_KEY"

# With model_list credentials: name the deployment
curl "http://localhost:4000/v1/containers?model=gpt-5.6&limit=20&order=desc" \
    -H "Authorization: Bearer $LITELLM_API_KEY"

Retrieve a Container

curl "http://localhost:4000/v1/containers/cntr_123..." \
    -H "Authorization: Bearer $LITELLM_API_KEY"

Delete a Container

curl -X DELETE "http://localhost:4000/v1/containers/cntr_123..." \
    -H "Authorization: Bearer $LITELLM_API_KEY"

Using OpenAI Client with LiteLLM Proxy

You can use the standard OpenAI Python client to interact with LiteLLM's container endpoints. This provides a familiar interface while keeping LiteLLM's proxy features.

Setup

First, configure your OpenAI client to point to your LiteLLM proxy:

from openai import OpenAI

client = OpenAI(
    api_key="sk-<your-litellm-api-key>",  # Your LiteLLM proxy key
    base_url="http://localhost:4000"  # LiteLLM proxy URL
)

Create a Container

container = client.containers.create(
    name="test-container",
    expires_after={
        "anchor": "last_active_at",
        "minutes": 20
    },
    extra_body={"custom_llm_provider": "openai"}
)

print(f"Container ID: {container.id}")
print(f"Container Name: {container.name}")
print(f"Created at: {container.created_at}")

With model_list credentials, name the deployment in extra_body:

container = client.containers.create(
    name="test-container",
    extra_body={"model": "gpt-5.6"}
)

List Containers

containers = client.containers.list(
    limit=20,
    extra_body={"custom_llm_provider": "openai"}
)

print(f"Found {len(containers.data)} containers")
for container in containers.data:
    print(f"  - {container.id}: {container.name}")

With model_list credentials, name the deployment in extra_query, since list is a GET:

containers = client.containers.list(
    limit=20,
    extra_query={"model": "gpt-5.6"}
)

Retrieve a Container

container = client.containers.retrieve(
    container_id="cntr_6901d28b3c8881908b702815828a5bde0380b3408aeae8c7",
    extra_body={"custom_llm_provider": "openai"}
)

print(f"Container: {container.name}")
print(f"Status: {container.status}")
print(f"Last active: {container.last_active_at}")

Delete a Container

result = client.containers.delete(
    container_id="cntr_6901d28b3c8881908b702815828a5bde0380b3408aeae8c7",
    extra_body={"custom_llm_provider": "openai"}
)

print(f"Deleted: {result.deleted}")
print(f"Container ID: {result.id}")

Complete Workflow Example

Here's a complete example showing the full container management workflow:

from openai import OpenAI

# Initialize client
client = OpenAI(
    api_key="sk-<your-litellm-api-key>",
    base_url="http://localhost:4000"
)

# 1. Create a container
print("Creating container...")
container = client.containers.create(
    name="My Code Interpreter Session",
    expires_after={
        "anchor": "last_active_at",
        "minutes": 20
    },
    extra_body={"custom_llm_provider": "openai"}
)

container_id = container.id
print(f"Container created. ID: {container_id}")

# 2. List all containers
print("\nListing containers...")
containers = client.containers.list(
    extra_body={"custom_llm_provider": "openai"}
)

for c in containers.data:
    print(f"  - {c.id}: {c.name} (Status: {c.status})")

# 3. Retrieve specific container
print(f"\nRetrieving container {container_id}...")
retrieved = client.containers.retrieve(
    container_id=container_id,
    extra_body={"custom_llm_provider": "openai"}
)

print(f"Container: {retrieved.name}")
print(f"Status: {retrieved.status}")
print(f"Last active: {retrieved.last_active_at}")

# 4. Delete container
print(f"\nDeleting container {container_id}...")
result = client.containers.delete(
    container_id=container_id,
    extra_body={"custom_llm_provider": "openai"}
)

print(f"Deleted: {result.deleted}")

Container Parameters

Create Container Parameters

Parameter	Type	Required	Description
`name`	string	Yes	Name of the container
`expires_after`	object	No	Container expiration settings
`expires_after.anchor`	string	No	Anchor point for expiration (e.g., "last_active_at")
`expires_after.minutes`	integer	No	Minutes until expiration from anchor
`file_ids`	array	No	List of file IDs to include in the container
`custom_llm_provider`	string	No	LLM provider to use (default: "openai")

List Container Parameters

Parameter	Type	Required	Description
`after`	string	No	Cursor for pagination
`limit`	integer	No	Number of items to return (1-100, default: 20)
`order`	string	No	Sort order: "asc" or "desc" (default: "desc")
`custom_llm_provider`	string	No	LLM provider to use (default: "openai")

Retrieve/Delete Container Parameters

Parameter	Type	Required	Description
`container_id`	string	Yes	ID of the container to retrieve/delete
`custom_llm_provider`	string	No	LLM provider to use (default: "openai")

Response Objects

ContainerObject

{
  "id": "cntr_123...",
  "object": "container",
  "created_at": 1234567890,
  "name": "My Container",
  "status": "active",
  "last_active_at": 1234567890,
  "expires_at": 1234569090,
  "file_ids": []
}

ContainerListResponse

{
  "object": "list",
  "data": [
    {
      "id": "cntr_123...",
      "object": "container",
      "created_at": 1234567890,
      "name": "My Container",
      "status": "active"
    }
  ],
  "first_id": "cntr_123...",
  "last_id": "cntr_456...",
  "has_more": false
}

DeleteContainerResult

{
  "id": "cntr_123...",
  "object": "container.deleted",
  "deleted": true
}

Supported Providers

Provider	Support Status	Notes
OpenAI	✅ Supported	Full support for all container operations
Azure OpenAI	✅ Supported	Set `custom_llm_provider="azure"`. Requests go to `{api_base}/openai/v1/containers` with the `api-key` header

For Azure OpenAI, pass the resource endpoint as api_base and the key as api_key, or set AZURE_API_BASE and AZURE_API_KEY

container = litellm.create_container(
    name="My Code Interpreter Container",
    custom_llm_provider="azure",
    api_base="https://<your-resource>.openai.azure.com",
    api_key=os.environ["AZURE_API_KEY"],
)

On the proxy, send -H "custom-llm-provider: azure" to use the AZURE_API_BASE and AZURE_API_KEY environment variables, or pass the model of an azure/ deployment in model_list to use that deployment's api_base and api_key

Container Files API - Manage files within containers
Code Interpreter Guide - Using Code Interpreter with LiteLLM

LiteLLM Python SDK Usage​

Quick Start​

Async Usage​

List Containers​

Retrieve a Container​

Delete a Container​

LiteLLM Proxy Usage​

Using OpenAI Client with LiteLLM Proxy​

Setup​

Create a Container​

List Containers​

Retrieve a Container​

Delete a Container​

Complete Workflow Example​

Container Parameters​

Create Container Parameters​

List Container Parameters​

Retrieve/Delete Container Parameters​

Response Objects​

ContainerObject​

ContainerListResponse​

DeleteContainerResult​

Supported Providers​

Related​

LiteLLM Python SDK Usage

Quick Start

Async Usage

List Containers

Retrieve a Container

Delete a Container

LiteLLM Proxy Usage

Using OpenAI Client with LiteLLM Proxy

Setup

Create a Container

List Containers

Retrieve a Container

Delete a Container

Complete Workflow Example

Container Parameters

Create Container Parameters

List Container Parameters

Retrieve/Delete Container Parameters

Response Objects

ContainerObject

ContainerListResponse

DeleteContainerResult

Supported Providers

Related