Oracle Cloud Infrastructure Documentation

Creating and Using a Sandbox

Create a sandbox in an active Generative AI project, run a command, and stop the runtime when finished.

Use the OCI CLI or SDK to create sandboxes. The Console provides project configuration, sandbox details, monitoring, and lifecycle actions.

Before You Begin

The examples use a shell that supports the shown variable syntax and OCI session authentication. Run oci session authenticate, then set profile_name to the profile you created. See Token-based Authentication for the CLI.

To check that your CLI includes the commands, run:

oci generative-ai-sandbox --help

Using the CLI

Replace COMPARTMENT_OCID and PROJECT_OCID with your resource identifiers.

  1. Prepare a project with sandboxes enabled.

    Follow Sandbox Configuration or run the following command. This example explicitly permits outbound network access with ALLOW_ALL. Select the policy required by your workload. See Networking for Sandboxes.

    profile_name="DEFAULT"
region="us-chicago-1"
compartment_id="COMPARTMENT_OCID"

oci --profile "$profile_name" --auth security_token --region "$region" \
  generative-ai generative-ai-project create \
  --compartment-id "$compartment_id" \
  --display-name sandbox-project \
  --sandbox-config '{"isEnabled":true,"sandboxOutboundNetworkingConfig":{"networkMode":"MANAGED","networkPolicy":{"mode":"ALLOW_ALL"}}}'
  2. Record the project OCID and wait for the project to become ACTIVE. 
    project_id="PROJECT_OCID"

oci --profile "$profile_name" --auth security_token --region "$region" \
  generative-ai generative-ai-project get \
  --generative-ai-project-id "$project_id"

    Check lifecycle-state in the response. For custom networking, creation includes provisioning the project network path.

  3. Create a sandbox and wait for it to reach RUNNING. 
    sandbox_id=$(oci --profile "$profile_name" --auth security_token --region "$region" \
  generative-ai-sandbox sandbox create \
  --project-id "$project_id" \
  --display-name my-sandbox \
  --runtime python-3.11 \
  --shape SMALL \
  --expiration-duration PT30M \
  --wait-for-state RUNNING \
  --query 'data.id' --raw-output)

printf '%s\n' "$sandbox_id"

    This example requests a 30-minute sandbox. Record the returned sandbox ID for later operations. See Sandbox Runtimes and Resource Limits for shapes and durations.

  4. Run a command to verify the sandbox. 
    oci --profile "$profile_name" --auth security_token --region "$region" \
  generative-ai-sandbox sandbox-command run-and-wait \
  --sandbox-id "$sandbox_id" \
  --command "python3 --version" \
  --timeout PT1M

    Review the output and exit code. You can now upload files and run commands.

  5. When finished, save required files and stop the sandbox. 
    oci --profile "$profile_name" --auth security_token --region "$region" \
  generative-ai-sandbox sandbox stop \
  --sandbox-id "$sandbox_id" \
  --is-force false

    Download files or create a snapshot before stopping. See Managing Sandboxes for lifecycle operations.

Using the Python SDK

This example uses an existing active project with sandboxes enabled and the session-authentication profile prepared earlier. It creates a sandbox, waits for it, runs a command, and requests a stop when finished.

from pathlib import Path
import time
import warnings

import oci
from oci.generative_ai_sandbox import GenerativeAiSandboxClient
from oci.generative_ai_sandbox.models import (
    CreateSandboxDetails,
    RunSandboxCommandDetails,
    StopSandboxDetails,
)

profile_name = "DEFAULT"
project_id = "PROJECT_OCID"
region = "us-chicago-1"
config = oci.config.from_file(profile_name=profile_name)
key = oci.signer.load_private_key_from_file(config["key_file"])
token = Path(config["security_token_file"]).expanduser().read_text().strip()
signer = oci.auth.signers.SecurityTokenSigner(token, key)
client = GenerativeAiSandboxClient(
    config=config,
    signer=signer,
    service_endpoint=f"https://inference.generativeai.{region}.oci.oraclecloud.com",
)

created = client.create_sandbox(
    project_id,
    CreateSandboxDetails(
        display_name="my-sandbox",
        runtime="python-3.11",
        shape="SMALL",
        expiration_duration="PT30M",
    ),
).data
sandbox_id = created.id
print(sandbox_id)

state = created.lifecycle_state
try:
    # This example waits up to five minutes for creation.
    deadline = time.monotonic() + 300
    while time.monotonic() < deadline:
        sandbox = client.get_sandbox(sandbox_id).data
        state = sandbox.lifecycle_state
        if state == "RUNNING":
            break
        if state in {"FAILED", "STOPPING", "STOPPED", "DELETING", "DELETED"}:
            raise RuntimeError(f"Sandbox state: {sandbox.lifecycle_state}")
        time.sleep(2)
    else:
        raise TimeoutError("Sandbox didn't reach RUNNING within five minutes")

    result = client.run_sandbox_command_and_wait(
        sandbox_id,
        RunSandboxCommandDetails(command="python3 --version", timeout="PT1M"),
    ).data
    print(result.output.stdout)
    print(result.output.stderr)
    print(result.output.exit_code)
finally:
    # Attempt cleanup without masking an earlier error.
    if state not in {"FAILED", "STOPPING", "STOPPED", "DELETING", "DELETED"}:
        try:
            client.stop_sandbox(sandbox_id, StopSandboxDetails(is_force=False))
        except Exception as cleanup_error:
            warnings.warn(f"Check sandbox {sandbox_id}: stop failed: {cleanup_error}")