Configure Polyaxon sandboxes for AI development and execution

Polyaxon sandboxes let you run commands, move files, and open terminals inside a running service. An ML engineer can inspect a failing dependency in the same image used by a workload; an agent application can upload a generated script, execute it, and retrieve the result through the Python client.

Both workflows use the platform's existing project, run, scheduling, and access model. Start with a service definition that makes the image, resources, files, and credentials explicit, then use the sandbox interfaces to work inside it.

Choose the service for the task

Consider an assistant that writes small Python programs to inspect a sanitized evaluation dataset. Its host application calls the model, while a Polyaxon service executes the resulting programs. The service needs Python, scratch space, and enough CPU and memory for the dataset. The model provider's API key can stay in the host application.

A GPU debugging session has different requirements. It needs a compatible framework image and a queue with accelerator capacity, as described in sandbox resources and GPUs. A notebook session may also need an HTTP port and notebook dependencies.

The sandbox plugin exposes access inside the service's main container. Container user, mounts, connections, and network policy determine what that access permits. Enabling the plugin does not create a separate kernel or VM.

Define an environment you can recreate

The following complete component provides a disposable Python workspace with a one-hour lifetime. Save it as sandbox.yaml. It assumes an existing Polyaxon project, a configured client, and a compute agent with sandbox support enabled.

kind: component
version: 1.1
name: python-analysis-sandbox

plugins:
  sandbox: true
  auth: false

termination:
  timeout: 3600

run:
  kind: service
  environment:
    securityContext:
      runAsUser: 1000
      runAsGroup: 1000
      runAsNonRoot: true
      fsGroup: 1000
  volumes:
    - name: workspace
      emptyDir: {}
  container:
    image: python:3.11
    workingDir: /workspace
    command: ["sleep", "infinity"]
    resources:
      requests:
        cpu: "1"
        memory: 1Gi
      limits:
        cpu: "2"
        memory: 2Gi
    volumeMounts:
      - name: workspace
        mountPath: /workspace

The image tag is suitable for demonstrating the configuration; use your team's reviewed image digest for a repeatable environment. Build recurring dependencies into that image instead of reinstalling them during every session.

Here, plugins.auth: false disables the automatic Polyaxon authentication context inside the workload because the analysis program does not need platform API access. The host still authenticates when accessing the sandbox. This setting does not remove separately mounted credentials, connections, or Kubernetes service-account tokens.

The emptyDir volume supplies scratch space for the Pod's lifetime. It is not durable artifact storage. See environment configuration for image and preset options.

Schedule and inspect the run

Launch the component into an existing project:

polyaxon run -p quick-start -f sandbox.yaml

Use the returned run UUID to locate the service in the project's runs dashboard. Inspect its resolved configuration, workload status, and logs. Wait for the run to reach running before attaching; a submitted run may still be pending approval, queued, or starting.

Use queues to route the same component to an appropriate compute agent. In Polyaxon terminology, a compute agent manages workloads on a cluster; it is separate from the LLM agent using the sandbox.

Platform administrators can supply presets for resource sizes, placement, connections, and security contexts. Review the final patched workload, since the effective configuration includes those defaults as well as the submitted file.

Attach an application to one run

This host-side example uses the installed Polyaxon client and a RUN_UUID environment variable containing the running service's UUID:

import os

from polyaxon.client import SandboxClient

with SandboxClient(
    project="quick-start",
    run_uuid=os.environ["RUN_UUID"],
) as sandbox:
    sandbox.ping()
    result = sandbox.process.exec(
        command=["python", "-V"],
        workdir="/workspace",
        timeout_ms=30_000,
    )
    print(result.exit_code, result.timed_out)
    print(result.stdout, end="")
    print(result.stderr, end="")

The process API returns an exit code, timeout status, duration, output, and truncation indicators. Use those fields to decide whether an execution completed successfully. The service can remain running after an individual command fails.

The Connect LLMs guide shows how to return command results to a model. Keep the target project and run in trusted host configuration; the model should not select a different user's environment.

Apply the deployment's access boundary

Use project permissions and RBAC for who can launch and access runs. Select only the connections needed by the workload. A connection supplies configured access; its underlying credential and external service determine that access's scope.

Outbound restrictions come from the cluster and network implementation, as covered in sandbox network access. For hostile generated code, the platform team must also select and enforce appropriate runtime isolation. Presets make configuration reusable; Kubernetes admission and runtime controls enforce restrictions against workloads that attempt to override them.

Preserve discoveries as platform assets

Download a useful scratch file through sandbox.fs before stopping the service. For programs that should log directly to Polyaxon, configure the required authentication, include the tracking library in the image, and follow Persist Outputs.

Move a successful script into source control, package its environment as a component version, and run it as a finite job when interactive access is no longer necessary. Its parameters, metrics, and artifacts can then participate in normal run comparison and orchestration. The sandbox becomes the place where the team develops a reusable workflow whose execution and results remain available across the platform.