Set up a Polyaxon code execution workspace

A useful code-execution workspace needs a reproducible environment, a readiness check, a bounded command interface, and a cleanup path. This walkthrough connects those pieces using a Polyaxon sandbox-enabled service.

The example runs a fixed, harmless calculation. It establishes the execution plumbing before you connect an agent or allow generated programs.

Prepare the project and client

You need an existing quick-start project, a configured Polyaxon client, and compute that supports service workloads. Your deployment administrator must enable sandbox support.

Follow project creation and the sandbox quick start if those prerequisites are not already in place. The controller-side Python example requires the Polyaxon client installed in your local environment.

Do not use this minimal example as the complete security policy for hostile code. Review credentials, network policy, and the runtime boundary before expanding its scope.

Define a disposable workspace

Save this complete component as sandbox.yaml:

kind: component
version: 1.1
name: bounded-python-workspace

plugins:
  sandbox: true
  auth: false
  mountArtifactsStore: false

termination:
  timeout: 1800

run:
  kind: service
  volumes:
    - name: workspace
      emptyDir: {}
  container:
    image: python:3.11
    workingDir: /workspace
    command: ["sleep", "infinity"]
    resources:
      requests:
        cpu: "1"
        memory: 512Mi
      limits:
        cpu: "2"
        memory: 1Gi
    volumeMounts:
      - name: workspace
        mountPath: /workspace

The image tag is illustrative; use a reviewed digest in a repeatable production profile. The service stays alive to accept commands, with a 30-minute absolute timeout as a backstop.

The workspace uses emptyDir, so its files disappear when the Pod is replaced. Automatic Polyaxon authentication and artifact-store mounting are disabled because the calculation needs neither. Separately configured credentials and Kubernetes identity still require review.

Start, execute, and retrieve the result

Run this script from the directory containing sandbox.yaml:

from polyaxon.client import RunClient, SandboxClient
from polyaxon.schemas import LifeCycle, V1Statuses

run_client = RunClient(project="quick-start")
run = run_client.create_from_polyaxonfile(
    polyaxonfile="sandbox.yaml",
    approved=True,
)
print("Execution run:", run.uuid)

try:
    run_client.wait_for_condition(
        statuses={V1Statuses.RUNNING} | LifeCycle.DONE_VALUES,
        print_status=True,
    )
    if run_client.status != V1Statuses.RUNNING:
        raise RuntimeError("Workspace did not reach running")

    with SandboxClient(
        project="quick-start",
        run_uuid=run.uuid,
    ) as sandbox:
        sandbox.ping()
        result = sandbox.process.exec(
            command=[
                "python",
                "-c",
                (
                    "import json; from pathlib import Path; "
                    "Path('/workspace/report.json').write_text("
                    "json.dumps({'total': sum([2, 3, 5])}), "
                    "encoding='utf-8')"
                ),
            ],
            timeout_ms=10_000,
        )
        if result.timed_out or result.exit_code != 0:
            raise RuntimeError("Calculation did not complete successfully")

        sandbox.fs.download_file(
            path="/workspace/report.json",
            local_path="./workspace-report.json",
        )
        print("Saved workspace-report.json")
finally:
    if run_client.status not in LifeCycle.DONE_VALUES:
        run_client.stop()

The script waits for the workload lifecycle before checking sandbox health. If the health endpoint is still unavailable, this simple example fails and cleans up; a production controller can add a bounded readiness retry.

The command creates a small JSON report containing a total of 10. The controller downloads it before stopping the service. Closing the sandbox client alone would not stop the workload.

Turn the example into an application tool

Replace the fixed calculation with an approved operation or a controlled generated-code workflow. Validate input ownership and request size before dispatch, and check output schema and size before sharing results.

Use the process reference for streaming and background behavior, and the filesystem reference for file operations.

For durable platform evidence, persist approved reports through a trusted artifact workflow. This example downloads locally because the execution service has no artifact-store mount.

The same lifecycle applies as the application grows: provision deliberately, wait for readiness, execute within a budget, preserve useful outputs, and stop the environment.