Running Commands in a Sandbox

Run shell commands, wait for output, stream events, and cancel work in a running sandbox.

Start with a sandbox in the RUNNING state. Set your session-authentication profile, region, and sandbox ID:

profile_name="DEFAULT"
region="us-chicago-1"
sandbox_id="SANDBOX_ID"

Running a Command and Waiting for Output

Use run-and-wait for a command whose result you want before continuing:

oci --profile "$profile_name" --auth security_token --region "$region" \
  generative-ai-sandbox sandbox-command run-and-wait \
  --sandbox-id "$sandbox_id" \
  --command "pwd && ls -la /workspace" \
  --timeout PT5M

Inspect the returned command ID, standard output, standard error, and exit code. A nonzero exit code indicates that the command reported an error.

Streaming Output

Use run-and-stream to read output as the command runs. This example prints three messages:

oci --profile "$profile_name" --auth security_token --region "$region" \
  generative-ai-sandbox sandbox-command run-and-stream \
  --sandbox-id "$sandbox_id" \
  --command "sh -lc 'for i in 1 2 3; do echo message-\$i; sleep 1; done'" \
  --timeout PT5M \
  --file -

Starting a Command Asynchronously

Use run to start a command and save its ID for output retrieval or cancellation:

command_id=$(oci --profile "$profile_name" --auth security_token --region "$region" \
  generative-ai-sandbox sandbox-command run \
  --sandbox-id "$sandbox_id" \
  --command "sleep 30" \
  --timeout PT2M \
  --query 'data.id' --raw-output)

Retrieve captured output:

oci --profile "$profile_name" --auth security_token --region "$region" \
  generative-ai-sandbox sandbox-command get-output \
  --sandbox-id "$sandbox_id" \
  --command-id "$command_id" \
  --from-seq 0

Or stream events for the existing command:

oci --profile "$profile_name" --auth security_token --region "$region" \
  generative-ai-sandbox sandbox-command stream \
  --sandbox-id "$sandbox_id" \
  --command-id "$command_id" \
  --from-seq 0

The sequence value 0 starts retrieval from the beginning.

Canceling a Command

To request termination of a running command, send SIGTERM:

oci --profile "$profile_name" --auth security_token --region "$region" \
  generative-ai-sandbox sandbox-command cancel \
  --sandbox-id "$sandbox_id" \
  --command-id "$command_id" \
  --signal SIGTERM

Canceling a command and stopping the sandbox are separate operations. See Stopping a Sandbox to end the runtime.

Running a Service on a Published Port

When creating the sandbox, use --publish-ports to expose the port your service needs. For example:

project_id="PROJECT_OCID"

sandbox_id=$(oci --profile "$profile_name" --auth security_token --region "$region" \
  generative-ai-sandbox sandbox create \
  --project-id "$project_id" \
  --display-name preview-sandbox \
  --runtime python-3.11 \
  --shape SMALL \
  --publish-ports '["8080"]' \
  --expiration-duration PT30M \
  --wait-for-state RUNNING \
  --query 'data.id' --raw-output)

Important

Published ports have no platform-provided application authentication. Anyone who obtains a published URL can reach that port while the sandbox runs unless your application restricts access. Add authentication when needed, and publish only the ports your workload requires.

For a temporary preview containing only non-sensitive files, start a server in a dedicated directory:

oci --profile "$profile_name" --auth security_token --region "$region" \
  generative-ai-sandbox sandbox-command run \
  --sandbox-id "$sandbox_id" \
  --command "mkdir -p /workspace/preview && python3 -m http.server 8080 --bind 0.0.0.0 --directory /workspace/preview" \
  --timeout PT30M

Get the sandbox and read the published-ports entry whose key is 8080. Its value is the URL for the service:

oci --profile "$profile_name" --auth security_token --region "$region" \
  generative-ai-sandbox sandbox get \
  --sandbox-id "$sandbox_id"