Configure Environments

A sandbox runs inside the container image and environment you define for the workload. The most reproducible setup is to build dependencies into the image or apply them through organization presets.

This page continues from the Sandbox Quick Start and uses its quick-start project, sandbox.yaml, and RUN_UUID variable.

Choose an Image

Start with an image that already has the tools required by your workflow:

run:
  kind: service
  container:
    image: python:3.11
    command: ["sleep", "infinity"]

For notebook workflows, use a notebook image. For GPU workflows, use an image with compatible CUDA, framework, and driver expectations.

Install Temporary Packages

Temporary installs are useful while debugging:

polyaxon sandbox exec -p quick-start -uid $RUN_UUID --stream -- pip install rich

Promote repeated package changes into a Docker image or preset once the workflow stabilizes.

Set Environment Values

Set environment variables under run.container.env:

run:
  kind: service
  container:
    image: python:3.11
    env:
      - name: EDITOR
        value: vim
    command: ["sleep", "infinity"]

For temporary values in an interactive shell:

polyaxon ops shell -p quick-start -uid $RUN_UUID
export EDITOR=vim
export DEBUG=1

These values belong to that shell. With plugins.tmux enabled, they remain available when you detach and reconnect to the same session. They disappear when the shell exits, the pod restarts, or the run stops, and they do not affect separate polyaxon sandbox exec commands. Use run.container.env for values that every process needs or that should be reproducible.

For a value needed by one command, prefix the remote command with env:

polyaxon sandbox exec \
  -p quick-start \
  -uid $RUN_UUID \
  -- env EDITOR=vim printenv EDITOR

The CLI has no --env option. This value is available only to that command and its child processes.

Use the Polyaxonfile environment specification for pod settings such as node selectors, service accounts, security contexts, and DNS. Presets can supply these settings.

Use Presets

Presets let platform teams provide reusable defaults for queues, resources, connections, security, and environment settings:

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

This command starts a new service. To use subsequent sandbox commands with it, replace the current value of RUN_UUID with the new run UUID.

See scheduling presets for details.