Sandbox
Purpose and Scope
A sandbox is an isolated execution environment for agent-directed work: a Unix-like workspace with files, commands, packages, mounted data, exposed services, snapshots, and restricted external access. In the agent architecture described by the first-party docs, the important boundary is between the harness and compute. The harness owns orchestration, model calls, tool routing, approvals, tracing, recovery, and run state. Compute is the execution plane where code runs, files change, dependencies install, and artifacts appear. This page explains how that concept connects to this SDK: openai-node exposes the platform control surfaces that let administrators govern hosted tools used by agent and Responses workflows.
Sources: src/resources/admin/organization/projects/hosted-tool-permissions.ts
The SDK file in scope is not a local container runner. It is the generated REST resource for project-level hosted tool permissions under the admin organization namespace. That distinction matters when designing sandbox agents. Your application may run the harness in trusted infrastructure, while hosted tools such as Code Interpreter, file search, MCP, web search, and image generation execute behind platform-managed boundaries. The permissions API is therefore a deployment and governance primitive: it answers whether a project is allowed to use each hosted tool, and it updates that allow-list at the project boundary.
Sources: src/resources/admin/organization/projects/hosted-tool-permissions.ts
Relevant Source Files
src/resources/admin/organization/projects/hosted-tool-permissions.ts- Defines the generatedHostedToolPermissionsresource, itsretrieveandupdatemethods, theProjectHostedToolPermissionsresponse shape, and the update parameter types for hosted tools.tests/api-resources/admin/organization/projects/hosted-tool-permissions.test.ts- Exercises the generated resource through anOpenAIclient configured with both a regular API key and an admin API key, validating raw response, parsed response, and combined data/response access.
Core Primitives
Sandbox-agent designs usually combine three primitives. The harness is the application-level runner that controls the loop and decides when to call a model, run a tool, pause for approval, or return a final result. Hosted tools are platform capabilities that the model can invoke as part of a tool-enabled workflow. Project permissions are administrative switches that decide which hosted tools are enabled for a specific OpenAI project. In openai-node, the project permissions primitive is represented by client.admin.organization.projects.hostedToolPermissions, which sits under the admin organization project namespace rather than under a model-generation namespace.
Sources: src/resources/admin/organization/projects/hosted-tool-permissions.ts, tests/api-resources/admin/organization/projects/hosted-tool-permissions.test.ts
The response type names the hosted capabilities that are relevant to many sandbox-style workflows: code_interpreter, file_search, image_generation, mcp, and web_search. Each capability has a single permission state with an enabled boolean. The update parameters mirror those fields and make each capability optional and nullable, so callers can patch only the permissions they intend to change. This shape is intentionally simple for policy automation: a deployment script can read the current state, compare it with an approved baseline, and update only the hosted tool gates that should change for that project.
Sources: src/resources/admin/organization/projects/hosted-tool-permissions.ts
System-to-Code Mapping
| Sandbox or agent concept | SDK surface | What it controls |
|---|---|---|
| Project-level hosted tool policy | HostedToolPermissions | Access to hosted tools for one organization project |
| Inspect current policy | retrieve(projectID, options?) | Sends a GET request for /organization/projects/${projectID}/hosted_tool_permissions |
| Change current policy | update(projectID, body, options?) | Sends a POST request with HostedToolPermissionUpdateParams |
| Admin authentication boundary | __security: { adminAPIKeyAuth: true } | Requires admin API key authentication for both methods |
| Tool-specific switches | code_interpreter, file_search, image_generation, mcp, web_search | Indicates whether each hosted tool is enabled |
The generated implementation maps directly to REST endpoints. retrieve calls the client GET helper with a path template that includes the project ID and marks the request with admin API key security. update calls the client POST helper against the same path, passes a body typed as HostedToolPermissionUpdateParams, and applies the same admin security metadata. For developers, this means hosted tool permissions are not configured on a per-model request. They are project policy managed through the admin API, then consumed indirectly by the workflows that attempt to use hosted tools.
Sources: src/resources/admin/organization/projects/hosted-tool-permissions.ts
Execution Flow
A typical rollout starts outside the model loop. First, decide which hosted tools a project should allow for the agent workload. A document-heavy agent may need file_search; an analysis or artifact-generation agent may need code_interpreter; an integration-heavy workflow may need mcp; a research assistant may need web_search; and a creative workflow may need image_generation. Next, an administrator uses the admin client with an admin API key to retrieve the current permission state. The application compares that state with the intended policy and posts an update only when the project needs a change.
Sources: src/resources/admin/organization/projects/hosted-tool-permissions.ts, tests/api-resources/admin/organization/projects/hosted-tool-permissions.test.ts
The test demonstrates the operational calling pattern. 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', {}). The assertions check that the SDK promise can be consumed as a raw Response, as parsed data, or as withResponse() data plus raw response. That matters for admin automation because permission changes often need audit logging: callers can inspect headers and status while still using typed response data.
Sources: tests/api-resources/admin/organization/projects/hosted-tool-permissions.test.ts
API Reference
| Entry point | Signature | Result |
|---|---|---|
client.admin.organization.projects.hostedToolPermissions.retrieve | retrieve(projectID: string, options?: RequestOptions) | APIPromise<ProjectHostedToolPermissions> |
client.admin.organization.projects.hostedToolPermissions.update | update(projectID: string, body: HostedToolPermissionUpdateParams, options?: RequestOptions) | APIPromise<ProjectHostedToolPermissions> |
ProjectHostedToolPermissions contains one field per hosted tool: code_interpreter, file_search, image_generation, mcp, and web_search. Each field is an object with enabled: boolean. HostedToolPermissionUpdateParams exposes the same field names as optional update entries. Each update entry can be the matching tool-specific object or null, allowing generated clients to represent partial updates according to the OpenAPI schema. Both methods accept RequestOptions, so standard SDK request-level behavior such as custom headers or other request options can be applied around the admin call.
Sources: src/resources/admin/organization/projects/hosted-tool-permissions.ts
Implementation and Testing Signals
The implementation is generated from the OpenAPI specification by Stainless, which is why the class, interfaces, request paths, response type, parameter type, examples, and security metadata are colocated in one resource file. The test file is also generated and focuses on client-contract behavior rather than business policy. It verifies that retrieve and update return the SDK's APIPromise abstraction correctly, preserving access to raw HTTP responses while resolving to parsed resource data for normal application code.
Sources: src/resources/admin/organization/projects/hosted-tool-permissions.ts, tests/api-resources/admin/organization/projects/hosted-tool-permissions.test.ts
For sandbox-agent builders, the main design takeaway is to keep permissions separate from run-time prompting. Do not rely on an instruction such as “do not use the shell” as the only safety boundary. Use project-level hosted tool permissions to express which hosted capabilities a project may access, use the harness to route tool calls and approvals, and use request or workflow configuration to decide when the model should be offered those tools. Read the related tools, MCP, Code Interpreter, and admin-organization pages next when moving from conceptual sandbox design to a production policy model.