Run browser automation in Polyaxon sandboxes

Polyaxon can host the browser environment used by an AI agent and connect that environment to the team's existing run records, compute queues, artifacts, and evaluation jobs. A browser agent can inspect a staging application, collect screenshots, and return structured results while the browser's dependencies stay inside a repeatable container image.

A useful first workflow is a release check for an internal model-review application. The browser opens approved staging pages, verifies that evaluation results appear, and saves a report for a reviewer. Start with a fixed browser runner, then evaluate whether model-directed navigation improves coverage.

Package the browser runner in a service

Build an image containing your browser, its system dependencies, and a reviewed automation harness. Polyaxon's sandbox process API executes programs in that image; it does not supply a browser driver or navigation policy.

This component assumes your team has built your-registry/browser-review:approved and included /opt/browser/run_case.py. Replace the illustrative image reference with your own digest. Configure a non-root browser user and preserve the browser's supported sandbox settings when building the image.

kind: component
version: 1.1
name: browser-review-session

plugins:
  sandbox: true
  auth: false

termination:
  timeout: 1800

run:
  kind: service
  volumes:
    - name: workspace
      emptyDir: {}
  container:
    image: your-registry/browser-review:approved
    workingDir: /workspace
    command: ["sleep", "infinity"]
    resources:
      requests:
        cpu: "1"
        memory: 2Gi
      limits:
        cpu: "2"
        memory: 4Gi
    volumeMounts:
      - name: workspace
        mountPath: /workspace

Save it as browser-session.yaml and launch it into an existing project with polyaxon run -p quick-start -f browser-session.yaml. The selected compute agent must support sandbox services. Verify that its volume permissions allow the image's browser user to write to /workspace.

A headless browser that makes outbound requests does not need a public service port. If the image also serves a review application, declare the application's HTTP port under run.ports; Polyaxon exposes declared HTTP services through its authenticated service proxy. See Network Access for this distinction.

Give the runner an explicit case contract

For the staging review, a case file can identify a page, expected visible content, and output filenames. Define those fields in your own runner and validate them before navigation. Select the staging origin from trusted runner configuration.

The browser harness should create a fresh browser context for each independent case and close it after collecting results. Cookies, downloads, and local storage belong to that context. A separate context reduces accidental session reuse; tenant separation also depends on the service's credentials, storage, and network controls.

Keep screenshots and reports free of live customer data where possible. The Secrets and Connections guide explains how to attach access required by a service. Use a staging-only identity when authentication is needed.

Execute a case through the Python client

The following complete host script assumes the service is already running, the host has a configured Polyaxon client, and RUN_UUID identifies that service. Supply a local browser-case.json accepted by your runner. The runner in this example must accept --case and --output-dir and write report.json and screenshot.png.

import os

from polyaxon.client import SandboxClient

with SandboxClient(
    project="quick-start",
    run_uuid=os.environ["RUN_UUID"],
) as sandbox:
    sandbox.ping()
    sandbox.fs.upload_file(
        local_path="browser-case.json",
        path="/workspace/browser-case.json",
    )
    result = sandbox.process.exec(
        command=[
            "python",
            "/opt/browser/run_case.py",
            "--case",
            "/workspace/browser-case.json",
            "--output-dir",
            "/workspace",
        ],
        workdir="/workspace",
        timeout_ms=120_000,
    )
    print(result.stdout, end="")
    print(result.stderr, end="")
    if result.timed_out or result.exit_code != 0:
        raise RuntimeError("Browser case did not complete successfully")

    sandbox.fs.download_file(
        path="/workspace/report.json",
        local_path="browser-report.json",
    )
    sandbox.fs.download_file(
        path="/workspace/screenshot.png",
        local_path="browser-screenshot.png",
    )

This uses the documented process and filesystem interfaces. The runner must write explicit success or failure details into its report; an exit code alone cannot establish whether a page displayed the correct model result.

For longer investigations, use streaming output or a background execution handle. Closing a host client or output stream does not establish that the service has stopped.

Connect a model through a browser-specific tool

Keep the model client and provider credentials in the host application, following Connect LLMs. Expose operations such as inspect_evaluation_page or capture_review_state that invoke your reviewed runner with validated arguments.

Page text is evidence the agent observes. The host application still controls the target Polyaxon run, approved staging origins, and any permission to submit a form. Browser-process isolation and model-action authorization address different risks.

Keep model-generated URLs and selectors subject to the runner's validation. Redirects and subresources also require the cluster's outbound policy. Polyaxon routes authenticated access to the service; the browser harness and network deployment govern the websites it can reach.

Turn browser sessions into repeatable evaluations

Once a case is stable, run the harness as a finite job. Use a versioned case manifest and compare application revisions or agent policies with the same expected outcomes.

Record case completion, incorrect page interpretation, unexpected navigation, latency, and reviewer acceptance through tracking. Retain sanitized screenshots and reports under the run's outputs path. A download through sandbox.fs saves a local file; it does not register a Polyaxon artifact.

In the comparison dashboard, select baseline and candidate runs, compare aggregate metrics, and inspect reports for changed cases. Register the reusable harness as a component version so the next application release can use the same procedure.

End the review session

Preserve required outputs before stopping the service with polyaxon ops stop -p quick-start -uid "$RUN_UUID". Scratch space can disappear when its Pod is replaced, and the running service continues to consume its allocated resources while idle.

The resulting workflow connects interactive browser investigation to Polyaxon's experiment and release process: a known environment, an identifiable execution, reviewable artifacts, and a repeatable comparison for the next change.