Machines and Browsers

Goal

Create machines and browser instances, and maintain browser runtime package versions for remote browser access, site login, and workspaces.

Prerequisites

• You are logged in to the admin console.
• Your account has browser management permissions.
• Available machine nodes or browser runtime environments are prepared.
• The admin service has app.keeperbase configured to store browser client and engine packages.

Steps

1. Go to "Browser Management > Machine List".

2. Click "Add Machine" and enter the machine address and port.

   • Machine address: enter the address of the keeper service. The keeper service normally runs on the installation server, so the server's default intranet address is usually enough.
   • Port: the default port is 7000.
   • Built-in version: when a machine is added or updated, the system calls the keeper bind interface to fetch and save this value automatically. It is not entered manually on the page.

3. Save and confirm the machine record exists and the keeper service is reachable and schedulable.

4. Go to "Browser Management > Browser List".

5. Create a browser instance, select a machine, enter a browser ID, and select a browser version.

   • Machine: the new browser runs on the selected machine.
   • Browser ID: use a unique, memorable value made of English letters or characters without spaces, for example chrome100.
   • Browser version: select a version provided by version management, or select "Built-in Version". When "Built-in Version" is selected, the system uses the built-in version saved on the selected machine.
   • Network mode:
     • Host Network: uses the regular browser network. It supports HTTP/SOCKS5 proxy configuration and is suitable for general scenarios.
     • Isolated Network: creates an independent network environment for the browser, takes over browser network traffic, and provides more complete isolation for DNS, UDP, WebRTC, and other network behavior. Use it for scenarios that require stronger network isolation.
   • Network Slot: required only for Isolated Network. Enter a unique number greater than 0.
   • DNS Config: required only for Isolated Network. Select tcp or udp, enter the DNS IP address and port, and choose whether DNS uses the proxy with direct or proxy. direct sends DNS requests directly; proxy sends DNS requests through the proxy.
   • Proxy Config: required only for Isolated Network. Select socks5 or http, then enter the proxy host and port. Username and password are optional.

6. After the browser is created, you can edit its network mode and isolated-network settings from the browser list.

7. Click "Start" to launch the browser until its status becomes running.

Browser Configuration

From the browser list, click the configuration action for a browser instance to adjust how that browser is launched and identified.

• Basic settings:
  • Kernel Version: select the Chromium runtime version used by the browser instance. Use "Edit" beside the field to maintain the available Chromium versions.
  • OS: select the operating system profile. Use "Edit" to maintain the OS list.
  • Brand and Brand Version: choose the browser brand, such as Google Chrome, Microsoft Edge, Opera, or Vivaldi, then select a matching brand version. Changing the brand clears the selected brand version.
  • Mobile Model: select a mobile device profile when the browser should emulate a mobile environment. Use "Edit" to maintain mobile model options.
  • Time Zone: search and select the browser time zone, or reset it to the local time zone.
• Advanced settings:
  • Boot Options: add, edit, or remove Chromium launch arguments as key-value pairs. Common defaults include disable-gpu, no-sandbox, ignore-certificate-errors, lang, and autoplay-policy. For more Chromium command-line switches, refer to List of Chromium Command Line Switches.
  • Temp Directory and Cache Directory: set where the browser writes temporary files and cache data.
  • Image Max Size: set the maximum image size, in pixels, used during browser image fetching.
  • Hardware Acceleration: enable it only when the runtime environment supports stable GPU acceleration.
  • Clear User Data: clear browser user data when a clean session is required.

Click "Save" after changing browser configuration. Restart the browser instance if the changes need to take effect in a new browser process.

Browser Version Management

From "Browser Management > Browser List", click "Version Management" to open the browser version management page.

The page shows the version name, engine status, client status, and download action. Status values mean:

Status	Meaning
Not downloaded	The license service returned this version, but no package of this type exists in the local app.keeperbase directory
Update available	A local package exists, but the license service has a higher build version
Latest	The local build version is greater than or equal to the license service build version, or the local version is not returned by the license service

Downloads run in a background thread and the page displays progress. Downloads support resume by range requests. Temporary files are written to a temporary directory first; after completion, the file is moved to app.keeperbase/<version>/. Before moving the new file, old packages of the same type in that version directory are removed.

Package names follow this format:

client_<version>_<buildVersion>.tar.gz
engine_<version>_<buildVersion>.tar.gz

version is the browser version name and buildVersion is the build number. The prefix identifies the package type: client for browser client packages and engine for browser engine packages.

Keeper Internal APIs

The admin service exposes keeper version query and download APIs for engine and client nodes to update automatically. These APIs require the internal JWT token.

API	Description
GET /internal/navi/keepers	Collects local packages from app.keeperbase and returns version, type, build version, and file name
GET /internal/navi/downKeeper?version=<version>&type=<type>	Downloads a local package for the specified version and type, with HTTP Range resume support

Engine nodes periodically call /internal/navi/keepers and read the BUILD file under the matching version directory in keeperBag.config.enginePath. If the local build is lower than the returned engine build, or the version does not exist locally, the node calls /internal/navi/downKeeper to download the engine package and extract it into the engine directory.

Client nodes periodically call /internal/navi/keepers and read the BUILD file under the matching version directory in /var/sa/caddy/client. If the local build is lower than the returned client build, or the version does not exist locally, the node calls /internal/navi/downKeeper to download the client package and extract it into the client directory.

Verification

• The new machine appears in the machine list.
• The machine list shows the machine's built-in version, fetched from the keeper bind interface.
• The new browser instance appears in the browser list.
• The browser list shows the browser version. If "Built-in Version" is selected, it also shows the built-in version of the related machine.
• The browser list shows the network mode and network slot. For isolated-network browsers, click "Network Details" to inspect DNS, whether DNS uses the proxy, and proxy details.
• The browser version management page shows client and engine status after comparing local packages with the license service.
• Users can be assigned an available browser environment when opening a site or workspace.

FAQ

• Browser instances must match available machine nodes. Unavailable machine nodes or keeper services affect remote access.
• Browser version, brand version, and operating system settings affect compatibility and site detection. If you select "Built-in Version" when creating a browser, confirm that the machine list has fetched the built-in version correctly.
• If the version management page keeps showing "Not downloaded", check app.keeperbase directory permissions, license service connectivity, and download task status.
• If automatic updates do not take effect, check that nodes can access /internal/navi/keepers and /internal/navi/downKeeper, and confirm the JWT token is configured correctly.
• The window list helps inspect active remote browser windows.