Oracle Cloud Infrastructure Documentation

Sandboxes in OCI Generative AI

Use a sandbox to run code and shell commands in a managed, temporary Linux workspace with its own files, processes, and network environment.

A sandbox gives your application or AI agent an execution environment that it can create on demand and address by ID. Upload inputs, run commands, inspect the results, and download output files. Oracle manages the underlying infrastructure.

Use sandboxes for tasks such as testing generated code, transforming data, producing reports, and running temporary application previews. Set the resources, network access, and lifetime needed for each task.

How Sandboxes Work

  1. Create a Generative AI project with sandboxes enabled, or enable sandboxes in an existing project.
  2. Select the project's outbound networking configuration and, optionally, configure warm pools.
  3. Create a sandbox through the OCI CLI or SDK. Select its runtime, compute shape, and expiration duration.
  4. Wait for the sandbox to reach RUNNING, then upload files and run commands.
  5. Download results or save a filesystem snapshot before stopping the sandbox or allowing it to expire.

You can reuse a running sandbox's ID across multiple calls to work in the same workspace. Each sandbox has its own lifetime. The service ends execution when the sandbox expires. Use a snapshot to create a new sandbox from saved files; snapshots don't preserve running processes or memory.

Projects and Warm Pools

A project holds shared configuration for its sandboxes. Sandboxes in the same project use the project's network configuration and the OCI access granted to sandbox principals from that project. Use separate projects or scoped permissions for different access requirements.

A warm pool prepares idle capacity for new sandbox requests. Warm pools are optional. They have their own configuration within a project.

Related Agent Capabilities

A hosted application can coordinate a workflow, create sandboxes for individual tasks, collect their outputs, and stop the sandboxes. Keep workflow state and final results in durable storage when they must outlive a runtime.

Capability Use it to
Hosted applications Run a deployed application, agent, API, or tool service.
Sandboxes Directly control a temporary execution workspace through command, file, snapshot, and lifecycle operations.
Containers API Manage execution resources used by tools in OCI Responses API interactions.

Working with Sandboxes