Code Interpreter

Purpose and Scope

Code Interpreter is a hosted tool that lets a model write and run Python code in a sandboxed environment. In OpenAI application workflows, it is useful when a plain text response is not enough: the model may need to inspect files, transform data, create charts, solve math problems iteratively, or process images as part of a reasoning task. In the TypeScript and JavaScript SDK, the user-facing invocation usually happens through tool-enabled model APIs such as Responses or Assistants, while the repository evidence for this page shows the administrative control plane that enables or disables hosted tools at the project level.

This page focuses on how to think about Code Interpreter inside an SDK-backed application. There are two distinct layers. The runtime layer is the model request that includes a tool declaration such as type: "code_interpreter" and, for Responses workflows, container configuration like automatic container creation and memory limits. The governance layer is the organization project setting that determines whether a hosted tool is allowed for a project. The SDK source included here represents that governance layer through client.admin.organization.projects.hostedToolPermissions, where code_interpreter is one of several hosted tool permission fields.

Sources: src/resources/admin/organization/projects/hosted-tool-permissions.ts, tests/api-resources/admin/organization/projects/hosted-tool-permissions.test.ts

Relevant Source Files

• src/resources/admin/organization/projects/hosted-tool-permissions.ts - Defines the generated HostedToolPermissions resource, its retrieve and update methods, the ProjectHostedToolPermissions response shape, and the HostedToolPermissionUpdateParams request body that includes code_interpreter.
• tests/api-resources/admin/organization/projects/hosted-tool-permissions.test.ts - Verifies that the generated resource methods are reachable through client.admin.organization.projects.hostedToolPermissions, return SDK promises, expose raw Response access, and require an admin API key in the test client setup.

Core Primitives

A hosted tool is an OpenAI-managed capability that a model can call during a workflow rather than code that your application executes locally. Code Interpreter is one such hosted tool, alongside hosted capabilities represented in the SDK permission model such as file search, image generation, MCP, and web search. That distinction matters for application design. Local tools require your server to implement function execution, validation, retries, and side effects. Hosted tools are declared in the model request, and OpenAI operates the tool execution environment subject to product limits, permissions, and the project’s configured access.

For Code Interpreter specifically, the official workflow centers on a sandboxed Python environment. A model can write code, observe failures, revise the code, and continue until the task is solved or the workflow ends. In Responses examples, the tool entry uses type: "code_interpreter" and may include a container object such as { type: "auto", memory_limit: "4g" }. That container concept is important because it frames Code Interpreter as a stateful execution workspace for files and generated artifacts, not merely a text-generation mode. Your application still sends instructions and input; the model decides when code execution helps satisfy the request.

Files are part of the practical boundary of Code Interpreter workflows. The tool is designed for data analysis, spreadsheets, mixed-format files, generated files, and graph images. In SDK terms, files and uploads are separate resource families that prepare or retrieve file-like data, while Code Interpreter is the hosted execution tool that can use file context during a model run. Treat the file lifecycle and the model run lifecycle separately: upload or reference the input material first, declare the tool in the model request, then inspect response output items and generated artifacts according to the API surface you are using.

System-to-Code Mapping

The generated admin resource models hosted tool access as a project setting. HostedToolPermissions.retrieve(projectID, options?) issues a GET request to /organization/projects/${projectID}/hosted_tool_permissions and returns an APIPromise<ProjectHostedToolPermissions>. HostedToolPermissions.update(projectID, body, options?) issues a POST request to the same path with a HostedToolPermissionUpdateParams body. Both methods attach __security: { adminAPIKeyAuth: true }, which indicates that these operations use admin API key authentication rather than ordinary end-user model request authentication.

Sources: src/resources/admin/organization/projects/hosted-tool-permissions.ts

The returned ProjectHostedToolPermissions interface contains one property per hosted tool. For Code Interpreter, the property is code_interpreter, and its value is a ProjectHostedToolPermissions.CodeInterpreter object with an enabled: boolean field. The same response object also includes file_search, image_generation, mcp, and web_search, each with the same single permission-state shape. That uniform shape makes it straightforward for an admin console or deployment check to render all hosted tool switches from one response and highlight whether Code Interpreter is enabled before the application attempts tool-enabled model calls.

Sources: src/resources/admin/organization/projects/hosted-tool-permissions.ts

Updates are partial. HostedToolPermissionUpdateParams exposes optional nullable properties for code_interpreter, file_search, image_generation, mcp, and web_search. For the Code Interpreter case, the body can include a code_interpreter object when the application wants to change that one permission, without necessarily sending a full replacement for every hosted tool. Because the generated file is OpenAPI-derived, the SDK contract mirrors the REST API shape instead of inventing a separate convenience abstraction. This is useful for administrators who want predictable parity between platform API reference examples, direct REST calls, and TypeScript usage.

Tool-Enabled Response Workflow

A typical Code Interpreter workflow starts with an ordinary OpenAI client and a model request that includes instructions, user input, and a tools array. The official Responses example uses a math-tutor instruction, a user algebra question, and a Code Interpreter tool declaration with an automatically managed container. In JavaScript, that pattern looks like client.responses.create({ model, tools: [{ type: "code_interpreter", container: { type: "auto", memory_limit: "4g" } }], instructions, input }). The important SDK idea is that Code Interpreter is declared as request data; you do not call a local Python function from your Node.js process.

Before relying on that workflow in production, check whether the project has permission to use the hosted tool. A platform administrator can call client.admin.organization.projects.hostedToolPermissions.retrieve("project_id") and inspect permissions.code_interpreter.enabled. If the tool is disabled, the application should fail early with a clear deployment or configuration message rather than asking end users to retry a model request that cannot use the required capability. If the organization policy permits it, an admin path can update the project setting through hostedToolPermissions.update("project_id", { code_interpreter: { enabled: true } }).

Example permission check

import OpenAI from 'openai';
 
const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  adminAPIKey: process.env.OPENAI_ADMIN_API_KEY,
});
 
const permissions =
  await client.admin.organization.projects.hostedToolPermissions.retrieve('project_id');
 
if (!permissions.code_interpreter.enabled) {
  throw new Error('Code Interpreter is not enabled for this project.');
}

The permission check and the model request usually belong in different parts of an application. Deployment tooling, admin dashboards, or startup health checks can use the admin resource to validate the project configuration. Request handlers should focus on the user workflow: assemble instructions, attach files or file references when needed, declare the Code Interpreter tool, stream or await the response, and present generated output. Keeping those responsibilities separate avoids giving broad admin credentials to request-handling code that only needs to make model calls.

API Components Reference

Sources: src/resources/admin/organization/projects/hosted-tool-permissions.ts

The test file reinforces the public call path and the SDK promise behavior. It constructs new OpenAI({ apiKey: 'My API Key', adminAPIKey: 'My Admin API Key', baseURL: ... }), then calls client.admin.organization.projects.hostedToolPermissions.retrieve('project_id') and update('project_id', {}). Each test uses .asResponse() to access the raw Response, awaits the same promise for parsed data, and uses .withResponse() to receive both data and raw response together. That pattern is relevant for admin tooling because permission changes often benefit from logging status codes, headers, or request diagnostics alongside typed response data.

Sources: tests/api-resources/admin/organization/projects/hosted-tool-permissions.test.ts

Implementation Details and Operational Guidance

Because the permission resource is generated from the OpenAPI specification, its naming follows the REST API rather than a hand-written domain wrapper. The path segment is hosted_tool_permissions, while the JavaScript property is hostedToolPermissions. The Code Interpreter field is code_interpreter, preserving the API’s snake_case payload name. Developers should avoid renaming this field in request bodies unless they are intentionally building their own adapter layer. Passing the API-shaped object directly keeps TypeScript types, generated tests, and platform reference behavior aligned.

Code Interpreter also has operational constraints that are not represented as ordinary local dependency management. The official docs describe it as a sandboxed environment and, for Assistants, as a session-based hosted capability. That means capacity, pricing, persistence, and artifact behavior should be treated as platform concerns rather than Node.js process concerns. Your application can decide when to offer the feature, how to message users about analysis tasks, and how to manage uploaded files, but the actual Python runtime is not installed from package.json and is not controlled through npm dependencies.

When combining Code Interpreter with files, design the user experience around observable output. The model may produce textual reasoning summaries, generated files, images of graphs, or intermediate tool-call items depending on the API and options in use. Preserve the full response structure when you need to continue a conversation or audit what happened, especially in workflows that also use other hosted tools. A common mistake is to only keep final assistant text and discard tool-related output items that may be required to understand or continue the run.

Testing Signals

The generated tests do not execute a real Code Interpreter session. Instead, they verify that the hosted tool permission endpoints are wired through the SDK resource tree and that the response wrapper behavior is consistent with other generated resources. This is still valuable coverage for applications that automate project configuration, because it confirms the call shape, client nesting, and admin credential setup. For end-to-end validation of Code Interpreter itself, pair this permission-resource confidence with a separate model workflow test that sends a small deterministic prompt and checks for a successful tool-enabled response in an environment where the hosted tool is enabled.

Sources: tests/api-resources/admin/organization/projects/hosted-tool-permissions.test.ts

Next Steps

Use this page when you need to connect the product concept of Code Interpreter to SDK-controlled project permissions. Next, read the Responses API and Tools pages for request-time tool declaration patterns, the Files and Uploads pages for preparing user data, and the Admin and Organization reference for broader project governance. In production, add a deployment check that retrieves hosted tool permissions, fail clearly when code_interpreter.enabled is false, and keep admin API keys out of ordinary user request handlers.