Quick Start

This guide continues from Create a project and starts a sandbox-enabled service in the same quick-start project. Run these commands from the working directory created there.

Prerequisites

Before you start, make sure you have:

• The quick-start project and initialized working directory from Create a project.
• A queue or agent (compute cluster) that can run service workloads.
• Sandbox support enabled by your Polyaxon deployment or agent administrator.

Create a Sandbox Component

The quick-start repository includes sandbox/sandbox.yaml:

kind: component
version: 1.1
name: sandbox-dev

plugins:
  sandbox: true
  ssh: true
  tmux: true

run:
  kind: service
  volumes:
    - name: workspace
      emptyDir: {}
  container:
    image: python:3.11
    workingDir: /workspace
    command: ["sleep", "infinity"]
    volumeMounts:
      - name: workspace
        mountPath: /workspace

The emptyDir volume creates /workspace as writable scratch space for the lifetime of the pod. Its contents are lost when the pod is replaced. Save durable results to the run's outputs path before cleanup.

Start the Run

The Python and CLI examples below are alternatives. Use one of them to create the run, not both.

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/sandbox.yaml",
    approved=True,
)
run_client.wait_for_condition(
    statuses={V1Statuses.RUNNING} | LifeCycle.DONE_VALUES,
    print_status=True,
)
if run_client.status != V1Statuses.RUNNING:
    raise RuntimeError(f"Run reached {run_client.status} before it started")

run_uuid = run.uuid
sandbox = SandboxClient(project="quick-start", run_uuid=run_uuid)

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

export RUN_UUID=PASTE_RUN_UUID_HERE

Check Sandbox Health

health = sandbox.ping()
print(health.status, health.version)

polyaxon sandbox ping -p quick-start -uid $RUN_UUID

Execute a Command

result = sandbox.process.exec(
    command=["python", "-V"],
    timeout_ms=30_000,
)
print(result.stdout, end="")
print(result.stderr, end="")

polyaxon sandbox exec -p quick-start -uid $RUN_UUID -- python -V

Stream command output when the command may take longer:

with sandbox.process.exec_stream(
    command=["sh", "-lc", "python -V && pwd"],
) as events:
    for event in events:
        print(event)

polyaxon sandbox exec -p quick-start -uid $RUN_UUID --stream -- sh -lc 'python -V && pwd'

Open an Interactive Shell

For applications and agents, use the PTY API when you need terminal behavior. It exposes raw terminal frames, so process execution is simpler when you only need to run a command and collect its output.

Python

pty = sandbox.pty.create(command=["sh"], workdir="/workspace")
try:
    with sandbox.pty.attach(pty.pty_id, replay_bytes=1024) as terminal:
        terminal.send_stdin(b"python -V\n")
        print(terminal.recv())
finally:
    sandbox.pty.delete(pty.pty_id)

CLI

polyaxon sandbox shell -p quick-start -uid $RUN_UUID

For a reconnectable terminal session, use the tmux-based CLI command:

polyaxon ops shell -p quick-start -uid $RUN_UUID

Keep or Stop the Run

Keep the service running while you work through the remaining sandbox guides. When you are finished, stop it to release CPU, memory, and GPU resources.

run_client.stop()

polyaxon ops stop -p quick-start -uid $RUN_UUID

For the Python interface, see the run client, sandbox client, process, and PTY references. For exact command options, see the sandbox CLI reference.

Next, continue to Connect with SSH.