Automatic Container Download

Overview

The Automatic Container Download feature enables downloads without user intervention for VNC containers, without requiring the user to manually start or confirm the download.

Download requests are intercepted by the Chrome extension, checked against a backend approval service, and allowed or blocked according to the defined organizational policy.

---

How It Works

1. A container download starts in the browser.
2. The Chrome extension intercepts the download request.
3. The extension sends an approval request to the endpoint configured in the backend.
4. If approved by the backend, the download starts automatically.
5. If this capability is enabled, the container is automatically launched after approval.
6. During long downloads, a heartbeat mechanism monitors backend health and keeps the process active.

If the backend is unavailable, the system's behavior is determined by the defined policy:

Strict mode — failOpenOnError: false Downloads are blocked if approval cannot be obtained.

Fail-Open mode — failOpenOnError: true Downloads are allowed if the backend is unavailable.

---

Configuration

All behaviors of this feature are controlled via Chrome Enterprise Policy.

Policy file path:

/etc/sball/container/chrome/policies/chrome-policies-guestagent.json

Policy Settings

Key	Type	Default	Description
endpoint	string	http://localhost:5800	Backend address for download approval
autoStartOnApproval	boolean	true	Automatically start the download after approval
failOpenOnError	boolean	false	Allow the download if the backend is unavailable
heartbeatIntervalMs	int	10000	Interval for checking backend health (milliseconds)
requestTimeoutMs	int	10000	HTTP request timeout (milliseconds)
maxRetries	int	2	Number of retry attempts on failure
retryBackoffMs	int	600	Interval between retry attempts (milliseconds)
showNotifications	boolean	true	Show desktop notifications for download events
showToastInPage	boolean	true	Show an in-page toast message
toastDurationMs	int	6000	Duration the toast is displayed (milliseconds)
progressPollIntervalMs	int	500	Interval for polling download progress (milliseconds)
popupRefreshIntervalMs	int	1000	Interval for refreshing the popup UI (milliseconds)
badgeErrorColor	hex	#ef4444	Badge color for the error state
badgePendingColor	hex	#f59e0b	Badge color for the pending-approval state
downloadConflictAction	enum	uniquify	How to handle filename conflicts: uniquify, overwrite, or prompt

Note: Do not change the endpoint value unless a documented change to the deployment configuration requires it.

Sample Policy File

{
  "endpoint": "http://localhost:5800",
  "autoStartOnApproval": true,
  "failOpenOnError": false,
  "heartbeatIntervalMs": 10000,
  "requestTimeoutMs": 10000,
  "maxRetries": 2,
  "retryBackoffMs": 600,
  "showNotifications": true,
  "showToastInPage": true,
  "toastDurationMs": 6000,
  "progressPollIntervalMs": 500,
  "popupRefreshIntervalMs": 1000,
  "badgeErrorColor": "#ef4444",
  "badgePendingColor": "#f59e0b",
  "downloadConflictAction": "uniquify"
}

---

Key Capabilities

• Every download is approved by the backend before it starts
• Downloads start automatically with no user interaction required after approval
• Support for Strict or Fail-Open modes based on organizational policy
• Heartbeat monitoring for long downloads, including large containers (over 1 GB)
• Error handling with retry and backoff for temporary network or backend failures
• Desktop and in-page notifications showing download status
• Unified, organization-wide deployment through managed Chrome policies, with no need to modify the extension's code

---

Operational Modes

Strict Mode

In this mode:

• Backend approval is mandatory
• If the backend is unavailable, the download is blocked
• Recommended for environments with high security requirements

"failOpenOnError": false

Fail-Open Mode

In this mode:

• The extension attempts to obtain backend approval
• If the backend is unavailable or times out, the download is allowed
• Better suited to environments where service continuity is the priority

"failOpenOnError": true

---

Notes

• Heartbeat monitoring is especially important for large containers with significant download times.
• All core behaviors can be configured without modifying the extension's code.
• Using a managed policy makes this feature suitable for enterprise-scale deployment.
• Do not change the endpoint value without documented reason. This value is a managed integration point and must stay aligned with the backend service's configuration.

---

Summary

The Automatic Container Download feature provides a clickless, backend-approved, policy-driven download flow for VNC containers.

This feature combines four elements:

• Backend authorization — every download is approved before it starts
• Automatic execution — no user intervention required
• Health monitoring for long downloads — via the heartbeat mechanism
• Centralized, organization-wide configuration — via Chrome Enterprise Policy