Skip to main content

​
Sandbox Jobs and Browser Runtime

Sandbox Jobs run browser rendering, PDF/PPTX export, and document conversion in short-lived, resource-bounded environments. Chromium comes from Xpert’s shared Browser Runtime—not the API image or the current interactive agent sandbox. Presentation Studio PDF/PPTX export is the first product feature using this capability.

​
Export experience

  1. A user requests an export from the Workbench or an agent.
  2. The plugin creates its export record and queues a browser-pool job.
  3. Xpert starts a one-use Browser Runtime sandbox when capacity is available.
  4. The plugin’s Presentation Action runs with platform Playwright/Chromium.
  5. Xpert validates the PDF/PPTX and writes it to the current Project or Xpert Workspace.
  6. The export record exposes the download and the temporary container is reclaimed.
The original conversation need not remain active. System export can also remain enabled when interactive agent sandboxes are disabled.

​
Interactive sandbox versus Sandbox Job

Plugins do not receive arbitrary shell access. A run request names only an Action and version; it cannot supply an image, command, entrypoint, environment, Docker option, or host path.

​
Shared Runtime, plugin-owned behavior

Plugins therefore do not maintain a Docker image for common browser work. Future Agent, Office, Python, or GPU images can use the same Runtime Suite release system as separate image families.

​
Presentation Studio availability

HTML remains browser-free. PDF/PPTX expose structured Action health: Do not download Chrome into API containers as an incident workaround; disable PDF/PPTX and preserve HTML instead.

​
How an export request is accepted

Workbench and server-side export endpoints combine two independent readiness checks before creating a browser export record or queue job:
  1. Sandbox Jobs getActionHealth() verifies the Action, Runtime Definition, API-local Binding, immutable artifact, Provider, and Runtime manifest.
  2. Managed Queue getExecutionPoolHealth({ executionPool: 'sandbox-browser' }) verifies that the browser execution pool has a live consumer.
PDF/PPTX is available only when both checks pass. The menu shows the most specific warning when either one fails, and the server repeats the check to prevent stale UI state from creating a permanently queued export. These checks are capability discovery, not settings users must configure. After acceptance, the export can move through queued, capacity waiting, starting, running, and a terminal succeeded, failed, or cancelled state. Capacity waiting does not consume a retry. An idempotent retry returns an earlier success or reattaches to active work; only a new attempt may select another healthy Runtime Binding.

​
Default enablement and production deployment

  1. Publish a Sandbox Runtime Suite through the Xpert version release.
  2. In Pro, register both the dedicated DockerSandboxRuntimeProvider and the separate interactive DockerSandboxProvider in the API process. OSS may install another public-SPI Provider distribution.
  3. Let Provider release CI supply its immutable Runtime Suite lock; users do not configure image/profile/provider settings.
  4. Verify Runtime, Action, API-local Provider health, and execution-pool health.
PDF/PPTX capability detection is enabled by default; there is no tenant feature switch. If any prerequisite is missing, the Workbench displays its structured warning, does not enqueue browser work, and keeps HTML available. The OSS Compose files do not mount the Docker socket or pull Browser Runtime artifacts. Its API consumes the browser queue but has no production Binding, so health reports RUNTIME_UNBOUND. Pro keeps DockerSandboxProvider and DockerSandboxRuntimeProvider as separate strategy classes in the same Docker Sandbox module and registers both in API; they share the Docker engine layer, not lifecycle contracts. xpert-plugins contains no second Docker implementation package. The Pro module’s runtime-suite.lock.json pins production artifacts as repository@sha256:<digest>; mutable tags and a SANDBOX_BROWSER_RUNTIME_IMAGE override are not accepted.

​
Open source and Pro

Xpert does not substitute an unsafe local-process production Provider. OSS API containers do not receive Docker access; a Pro or community API receives only the engine access required by its installed Provider. Browser export is health-driven by default: unmet conditions display an actionable warning instead of a silently disabled menu. RUNTIME_UNBOUND means the API executor cannot supply a compatible Binding. Sandbox Action bundle hash mismatch is not a missing deployment setting. It means the installed Action files differ from the hash recorded in its manifest. Action-owned dependencies must live in an ordinary directory such as bundle/runtime-modules, never nested node_modules, and release CI must run a real npm pack, extract the tarball, and recompute the hash from extracted content. Operators should upgrade or reinstall the fixed Presentation Studio package and restart the API to refresh the Action Registry; no image, profile, Provider, or CHROME_PATH environment variable is needed.

​
Isolation, capacity, and files

The default Browser Runtime profile uses 2 CPU, 4 GiB memory, 1 GiB shared memory, 4 GiB temporary storage, a 300-second task timeout, and a 360-second hard deadline. Containers run non-root with a read-only root, dropped capabilities, no-new-privileges, and no public network by default. Only the current Job workspace is writable; plugin directories and host node_modules are never mounted. Capacity defaults to 20 global, 4 per tenant, and 2 per user. Quota saturation remains waiting without creating a partial container or consuming a business retry. Queue messages carry business identifiers. Handlers load immutable snapshots and pass persisted Workspace Files references with size and SHA-256. Xpert validates tenant and paths, persists validated output as portable references, and keeps buffers/base64 out of queue state.

​
Retry, cancellation, and boundaries

Stable business IDs plus immutable checksums reuse prior success or reattach to active work. Capacity-service, Provider startup, browser launch, timeout, and OOM failures are retryable. Action/Profile/version, invalid input, and invalid output are deterministic and are not retried. Cancellation stops both the Managed Queue work and an active Sandbox Job. Success, failure, and cancellation reclaim containers and Job volumes; orphan cleanup handles platform crashes. Current boundaries: v1 actions are system-plugin only, every export gets a fresh container, aggregate input and output are limited to 350 MiB each, runtime dependency installation is forbidden, and CHROME_PATH/local backend remain development-test compatibility only. Plugin developers should use the Sandbox Action Bundle reference in the Xpert Plugin Development skill.