The sandbox client communicates with a sandbox-enabled run through the streams proxy. To attach to an existing run, provide its owner, project, and run UUID. You can omit the run UUID when you intend to call create() first. The client uses the normal Polyaxon authentication path.

The functionality is split into sub-clients:

• process: one-shot, streaming, and background command execution.
• fs: filesystem reads, writes, transfers, and management.
• pty: interactive PTY sessions over WebSocket.

SandboxClient

polyaxon._client.sandbox.SandboxClient(owner=None, project=None, run_uuid=None, client=None, is_offline=None, no_op=None, manual_exceptions_handling=False, *, log_context=False)

SandboxClient is a client to interact with a run's sandbox service.

The sandbox service exposes process execution, filesystem access, and interactive PTY sessions inside the run's main container. Sandbox operations require a valid owner, project, and run uuid. To create a new sandbox-enabled service run, initialize the client with owner/project and call create().

If no values are passed to this class, Polyaxon will try to resolve the owner, project, and run uuid from the environment:

• If you have a configured CLI, Polyaxon will use the configuration of the cli.
• If you have a cached run using the CLI, the client will default to that cached run unless you override the values.
• If you use this client in the context of a job or a service managed by Polyaxon, a configuration will be available to resolve the values based on that run.

When an online client uses a cached run UUID, accessing run_uuid raises PolyaxonClientException if the cached owner or project is known and conflicts with the client's target. The check happens before a request using that UUID, not during construction, so create() can still create a new sandbox run. A successful create() replaces the cached identity with the new run. This also applies to AsyncSandboxClient.

Context logging is disabled by default. Set log_context=True to log cached owner and project values with their cache paths at construction. After validation succeeds, the first access to a cached run_uuid logs its UUID and cache path once per client. Notices use INFO through the polyaxon.cli logger, or WARNING when cached run ownership metadata is incomplete. An explicit run_uuid produces no run-cache notice. Logging uses your existing configuration. Set client.log_context=False to suppress further notices; cached ownership is still checked on every run UUID access.

To attach to an existing run explicitly, construct a client with owner, project, and run_uuid. Changing cache files does not update an existing client's identity. See conflicting cached run context for cache recovery and the limits of this check.

The functionality is split into sub-clients:

• process: one-shot, streaming, and background command execution.
• fs: filesystem reads, writes, transfers, and management.
• pty: interactive PTY sessions over WebSocket.

• Example:

from polyaxon.client import SandboxClient
client = SandboxClient(owner="acme", project="proj", run_uuid=run_uuid)
client.ping()
result = client.process.exec(command=["python", "-V"])
print(result.exit_code, result.stdout)

• Properties:

  • project: str.
  • owner: str.
  • run_uuid: str.
  • run_data: V1Run.
  • namespace: str.
  • settings: V1RunSettings.
  • client: PolyaxonClient
  • process: the process execution sub-client.
  • fs: the filesystem sub-client.
  • pty: the PTY sub-client.

• Args:

  • owner: str, optional, the owner is the username or the organization name owning this project.
  • project: str, optional, project name owning the run(s).
  • run_uuid: str, optional, run uuid.
  • client: PolyaxonClient, optional, an instance of a configured client, if not passed, a new instance will be created based on the available environment.
  • is_offline: bool, optional, To trigger the offline mode manually instead of depending on POLYAXON_IS_OFFLINE.
  • no_op: bool, optional, To set the NO_OP mode manually instead of depending on POLYAXON_NO_OP.
  • log_context: bool, optional, default: False, Log cached context through the Python logger. Can also be changed on the client instance.

• Raises:

  • PolyaxonClientException: If the owner and/or project are not passed and Polyaxon cannot resolve the values from the environment.

AsyncSandboxClient

polyaxon._client.sandbox.AsyncSandboxClient(owner=None, project=None, run_uuid=None, client=None, is_offline=None, no_op=None, manual_exceptions_handling=False, *, log_context=False)

AsyncSandboxClient is the async variant of the SandboxClient.

It exposes the same API surface with coroutine methods and async iterators:

• process.exec_stream returns an async context manager / async iterator.
• Background exec handles expose awaitable methods and async for log iteration.
• pty.attach returns an async WebSocket client.

• Example:

from polyaxon.client import AsyncSandboxClient
client = AsyncSandboxClient(owner="acme", project="proj", run_uuid=run_uuid)
result = await client.process.exec(command=["python", "-V"])

create

client.create(name=None, description=None, tags=None, content=None, managed_by=None, is_managed=None, pending=None, meta_info=None)

Creates a new sandbox-enabled service run.

A sandbox is not a separate Polyaxon resource. This method creates a regular kind: service run with plugins.sandbox enabled, then mutates this client to point at the returned run. After the run is approved, scheduled, and running, the same client can use process, fs, and pty.

If content is not provided, the method builds a minimal service operation with plugins.sandbox: true. If content is provided, it must be inline service operation content so the client can verify the run kind and merge the sandbox plugin before submission.

• Example:

from polyaxon.client import SandboxClient
client = SandboxClient(owner="acme", project="proj")
run = client.create(name="debug-sandbox")
print(run.uuid)
result = client.process.exec(command=["ls"])

create() submits the service run but does not approve it, schedule it, or wait for readiness. After the run reaches running, call client.ping() before using the process, filesystem, or PTY sub-clients.

• Args:

  • name: str, optional, run name.
  • description: str, optional, run description.
  • tags: str or List[str], optional, list of tags.
  • content: str or Dict or V1Operation, optional, inline service operation content. When provided, it must define a service component.
  • is_managed: bool, flag to create a managed run.
  • managed_by: ManagedBy, optional, service that manages the operation.
  • pending: str, optional, pending state.
  • meta_info: dict, optional, meta info to create the run with.

• Returns: V1Run, run instance from the response.

ping

client.ping()

Checks that the sandbox service is reachable and healthy.

• Example:

response = client.ping()
print(response.status, response.version)

• Returns: V1PingResponse, with status, version, uptime_ms, last_activity, execs_running, ptys_running, ptys_attached.

get_namespace

client.get_namespace()

Fetches the run namespace.

• Returns: str, the namespace where the run is scheduled.