0
# Containers
1

2
Manage isolated execution containers for code interpreter and other tools. Containers provide sandboxed environments with file system access, allowing you to create, manage, and execute code in isolated contexts with full file management capabilities.
3

4
## Capabilities
5

6
### Container Management
7

8
Create and manage isolated execution containers.
9

10
```typescript { .api }
11
/**
12
 * Create a new container
13
 * @param params - Container creation parameters
14
 * @returns Container object with unique identifier
15
 */
16
function create(params: ContainerCreateParams): Promise<ContainerCreateResponse>;
17

18
/**
19
 * Retrieve container information
20
 * @param containerID - Unique identifier for the container
21
 * @returns Container object with current status
22
 */
23
function retrieve(containerID: string): Promise<ContainerRetrieveResponse>;
24

25
/**
26
 * List all containers
27
 * @param params - List parameters for pagination and sorting
28
 * @returns Paginated list of containers
29
 */
30
function list(params?: ContainerListParams): Promise<ContainerListResponsesPage>;
31

32
/**
33
 * Delete a container
34
 * @param containerID - Unique identifier for the container
35
 * @returns Void on successful deletion
36
 */
37
function delete(containerID: string): Promise<void>;
38

39
interface ContainerCreateParams {
40
  /** Name of the container to create */
41
  name: string;
42
  /** IDs of files to copy to the container */
43
  file_ids?: Array<string>;
44
  /** Container expiration time relative to the 'anchor' time */
45
  expires_after?: ExpiresAfterCreate;
46
}
47

48
/**
49
 * Expiration configuration for container creation.
50
 * When creating a container, the anchor field is required.
51
 * Note: This is accessed as ContainerCreateParams.ExpiresAfter in TypeScript.
52
 */
53
interface ExpiresAfterCreate {
54
  /** Time anchor for the expiration time. Currently only 'last_active_at' is supported */
55
  anchor: "last_active_at";
56
  /** Number of minutes after the anchor before the container expires */
57
  minutes: number;
58
}
59

60
/**
61
 * Expiration configuration in container responses.
62
 * In response objects, the anchor field is optional.
63
 * Note: This is accessed as nested interface (e.g., ContainerRetrieveResponse.ExpiresAfter) in TypeScript.
64
 */
65
interface ExpiresAfter {
66
  /** Time anchor for the expiration time. Currently only 'last_active_at' is supported */
67
  anchor?: "last_active_at";
68
  /** Number of minutes after the anchor before the container expires */
69
  minutes: number;
70
}
71

72
interface ContainerListParams {
73
  /** Sort order by the created_at timestamp */
74
  order?: "asc" | "desc";
75
  /** Maximum number of items to return */
76
  limit?: number;
77
  /** Cursor for fetching the next page of results */
78
  after?: string;
79
  /** Cursor for fetching the previous page of results */
80
  before?: string;
81
}
82
```
83

84
**Usage Examples:**
85

86
```typescript
87
import OpenAI from "openai";
88

89
const client = new OpenAI();
90

91
// Create a new container
92
const container = await client.containers.create({
93
  name: "python-executor",
94
  expires_after: {
95
    anchor: "last_active_at",
96
    minutes: 60, // Expires 60 minutes after last activity
97
  },
98
});
99

100
console.log(`Container created: ${container.id}`);
101

102
// Retrieve container details
103
const retrieved = await client.containers.retrieve(container.id);
104
console.log(`Container status: ${retrieved.status}`);
105

106
// List all containers
107
for await (const container of client.containers.list({ order: "desc" })) {
108
  console.log(`${container.id}: ${container.name} (${container.status})`);
109
}
110

111
// Delete a container
112
await client.containers.delete(container.id);
113
console.log("Container deleted");
114
```
115

116
### File Management
117

118
Manage files within containers for code execution and data processing.
119

120
```typescript { .api }
121
/**
122
 * Create a file in a container
123
 * You can send either a multipart/form-data request with raw file content,
124
 * or a JSON request with a file ID
125
 * @param containerID - Unique identifier for the container
126
 * @param params - File creation parameters
127
 * @returns File object with path and metadata
128
 */
129
function containers.files.create(
130
  containerID: string,
131
  params: FileCreateParams
132
): Promise<FileCreateResponse>;
133

134
/**
135
 * Retrieve file information
136
 * @param fileID - Unique identifier for the file
137
 * @param params - Parameters including container_id
138
 * @returns File object with metadata
139
 */
140
function containers.files.retrieve(
141
  fileID: string,
142
  params: FileRetrieveParams
143
): Promise<FileRetrieveResponse>;
144

145
/**
146
 * List files in a container
147
 * @param containerID - Unique identifier for the container
148
 * @param params - List parameters for pagination and sorting
149
 * @returns Paginated list of files
150
 */
151
function containers.files.list(
152
  containerID: string,
153
  params?: FileListParams
154
): Promise<FileListResponsesPage>;
155

156
/**
157
 * Delete a file from a container
158
 * @param fileID - Unique identifier for the file
159
 * @param params - Parameters including container_id
160
 * @returns Void on successful deletion
161
 */
162
function containers.files.delete(
163
  fileID: string,
164
  params: FileDeleteParams
165
): Promise<void>;
166

167
interface FileCreateParams {
168
  /** The File object (not file name) to be uploaded */
169
  file?: Uploadable;
170
  /** ID of an existing file to copy into the container */
171
  file_id?: string;
172
}
173

174
interface FileRetrieveParams {
175
  container_id: string;
176
}
177

178
interface FileListParams {
179
  /** Sort order by the created_at timestamp */
180
  order?: "asc" | "desc";
181
  /** Maximum number of items to return */
182
  limit?: number;
183
  /** Cursor for fetching the next page of results */
184
  after?: string;
185
  /** Cursor for fetching the previous page of results */
186
  before?: string;
187
}
188

189
interface FileDeleteParams {
190
  container_id: string;
191
}
192
```
193

194
**Usage Examples:**
195

196
```typescript
197
import OpenAI, { toFile } from "openai";
198
import fs from "fs";
199

200
const client = new OpenAI();
201

202
// Create a container
203
const container = await client.containers.create({
204
  name: "data-processor",
205
});
206

207
// Upload a file to the container
208
const fileContent = fs.readFileSync("./data.csv");
209
const containerFile = await client.containers.files.create(container.id, {
210
  file: await toFile(fileContent, "data.csv"),
211
});
212

213
console.log(`File uploaded: ${containerFile.path}`);
214
console.log(`File size: ${containerFile.bytes} bytes`);
215

216
// Copy an existing file into the container
217
const existingFile = await client.files.create({
218
  file: await toFile(fs.readFileSync("./script.py"), "script.py"),
219
  purpose: "assistants",
220
});
221

222
await client.containers.files.create(container.id, {
223
  file_id: existingFile.id,
224
});
225

226
// List files in the container
227
for await (const file of client.containers.files.list(container.id)) {
228
  console.log(`${file.path}: ${file.bytes} bytes (${file.source})`);
229
}
230

231
// Retrieve file info
232
const fileInfo = await client.containers.files.retrieve(containerFile.id, {
233
  container_id: container.id,
234
});
235
console.log(`File created at: ${new Date(fileInfo.created_at * 1000)}`);
236

237
// Delete a file
238
await client.containers.files.delete(containerFile.id, {
239
  container_id: container.id,
240
});
241
```
242

243
### File Content Access
244

245
Download file content from containers.
246

247
```typescript { .api }
248
/**
249
 * Retrieve the raw content of a file in a container
250
 * @param fileID - Unique identifier for the file
251
 * @param params - Parameters including container_id
252
 * @returns Response object containing the binary file content
253
 */
254
function containers.files.content.retrieve(
255
  fileID: string,
256
  params: ContentRetrieveParams
257
): Promise<Response>;
258

259
interface ContentRetrieveParams {
260
  container_id: string;
261
}
262
```
263

264
**Usage Example:**
265

266
```typescript
267
// Download file content
268
const response = await client.containers.files.content.retrieve(fileId, {
269
  container_id: container.id,
270
});
271

272
// Read as text
273
const text = await response.text();
274
console.log(text);
275

276
// Or save to disk
277
const buffer = Buffer.from(await response.arrayBuffer());
278
fs.writeFileSync("downloaded-file.txt", buffer);
279
```
280

281
## Types
282

283
### Container Response Types
284

285
```typescript { .api }
286
interface ContainerCreateResponse {
287
  /** Unique identifier for the container */
288
  id: string;
289
  /** Unix timestamp (in seconds) when the container was created */
290
  created_at: number;
291
  /** Name of the container */
292
  name: string;
293
  /** Status of the container (e.g., active, deleted) */
294
  status: string;
295
  /** The type of this object */
296
  object: string;
297
  /** Container expiration configuration */
298
  expires_after?: ExpiresAfter;
299
}
300

301
interface ContainerRetrieveResponse {
302
  /** Unique identifier for the container */
303
  id: string;
304
  /** Unix timestamp (in seconds) when the container was created */
305
  created_at: number;
306
  /** Name of the container */
307
  name: string;
308
  /** Status of the container (e.g., active, deleted) */
309
  status: string;
310
  /** The type of this object */
311
  object: string;
312
  /** Container expiration configuration */
313
  expires_after?: ExpiresAfter;
314
}
315

316
interface ContainerListResponse {
317
  /** Unique identifier for the container */
318
  id: string;
319
  /** Unix timestamp (in seconds) when the container was created */
320
  created_at: number;
321
  /** Name of the container */
322
  name: string;
323
  /** Status of the container (e.g., active, deleted) */
324
  status: string;
325
  /** The type of this object */
326
  object: string;
327
  /** Container expiration configuration */
328
  expires_after?: ExpiresAfter;
329
}
330
```
331

332
### File Response Types
333

334
```typescript { .api }
335
interface FileCreateResponse {
336
  /** Unique identifier for the file */
337
  id: string;
338
  /** Size of the file in bytes */
339
  bytes: number;
340
  /** The container this file belongs to */
341
  container_id: string;
342
  /** Unix timestamp (in seconds) when the file was created */
343
  created_at: number;
344
  /** Path of the file in the container */
345
  path: string;
346
  /** Source of the file (e.g., 'user', 'assistant') */
347
  source: string;
348
  /** The type of this object ('container.file') */
349
  object: "container.file";
350
}
351

352
interface FileRetrieveResponse {
353
  /** Unique identifier for the file */
354
  id: string;
355
  /** Size of the file in bytes */
356
  bytes: number;
357
  /** The container this file belongs to */
358
  container_id: string;
359
  /** Unix timestamp (in seconds) when the file was created */
360
  created_at: number;
361
  /** Path of the file in the container */
362
  path: string;
363
  /** Source of the file (e.g., 'user', 'assistant') */
364
  source: string;
365
  /** The type of this object ('container.file') */
366
  object: "container.file";
367
}
368

369
interface FileListResponse {
370
  /** Unique identifier for the file */
371
  id: string;
372
  /** Size of the file in bytes */
373
  bytes: number;
374
  /** The container this file belongs to */
375
  container_id: string;
376
  /** Unix timestamp (in seconds) when the file was created */
377
  created_at: number;
378
  /** Path of the file in the container */
379
  path: string;
380
  /** Source of the file (e.g., 'user', 'assistant') */
381
  source: string;
382
  /** The type of this object ('container.file') */
383
  object: "container.file";
384
}
385
```
386

387
## Complete Workflow Example
388

389
```typescript
390
import OpenAI, { toFile } from "openai";
391
import fs from "fs";
392

393
const client = new OpenAI();
394

395
async function processDataInContainer() {
396
  // 1. Create a container with 2-hour expiration
397
  const container = await client.containers.create({
398
    name: "data-analysis-env",
399
    expires_after: {
400
      anchor: "last_active_at",
401
      minutes: 120,
402
    },
403
  });
404

405
  console.log(`Container created: ${container.id}`);
406

407
  // 2. Upload data files
408
  const dataFile = await client.containers.files.create(container.id, {
409
    file: await toFile(
410
      fs.readFileSync("./data.csv"),
411
      "data.csv",
412
      { type: "text/csv" }
413
    ),
414
  });
415

416
  console.log(`Data file uploaded: ${dataFile.path}`);
417

418
  // 3. Upload processing script
419
  const scriptFile = await client.containers.files.create(container.id, {
420
    file: await toFile(
421
      fs.readFileSync("./process.py"),
422
      "process.py",
423
      { type: "text/x-python" }
424
    ),
425
  });
426

427
  console.log(`Script uploaded: ${scriptFile.path}`);
428

429
  // 4. List all files in container
430
  console.log("\nFiles in container:");
431
  for await (const file of client.containers.files.list(container.id)) {
432
    console.log(`- ${file.path} (${file.bytes} bytes)`);
433
  }
434

435
  // 5. Execute code in container (via Assistants API or other tools)
436
  // ... execution logic here ...
437

438
  // 6. Download results
439
  const resultFiles = [];
440
  for await (const file of client.containers.files.list(container.id)) {
441
    if (file.path.startsWith("output_")) {
442
      const content = await client.containers.files.content.retrieve(file.id, {
443
        container_id: container.id,
444
      });
445
      resultFiles.push({
446
        path: file.path,
447
        content: await content.text(),
448
      });
449
    }
450
  }
451

452
  console.log(`\nDownloaded ${resultFiles.length} result files`);
453

454
  // 7. Clean up - delete container when done
455
  await client.containers.delete(container.id);
456
  console.log("Container deleted");
457

458
  return resultFiles;
459
}
460

461
processDataInContainer();
462
```
463

464
## Notes
465

466
- Containers provide isolated file systems for code execution
467
- Files can be uploaded directly or copied from existing OpenAI file objects
468
- Containers automatically expire based on the `expires_after` configuration
469
- The `last_active_at` anchor tracks the last time the container was accessed
470
- File sources indicate whether files were uploaded by users or generated by assistants
471
- Container files are separate from the main Files API and only accessible within their container
472
- Deleting a container does not delete files in the main Files API that were copied to it
473