THE NABILBROWSER HANDBOOK

A workspace you can run yourself.

Build the Java application, open the dashboard, and give every browser profile its own home. These instructions describe the included version 1.0.0 source.

Quick start

You need a Java 17 or newer JDK, Maven 3.8+, and a local Chrome or Chromium installation. The application has no third-party runtime dependencies. The first Maven build needs access to Maven Central for build plugins.

  1. Download and extract the source.

    Open a terminal in the NabilBrowserManager folder, alongside pom.xml.

  2. Build and verify.
    mvn verify

    The build creates target/NabilBrowserManager-1.0.0.jar. The included scripts/build.sh also builds using a JDK without Maven.

  3. Start the manager.
    java -jar target/NabilBrowserManager-1.0.0.jar
  4. Open your workspace.

    Visit http://127.0.0.1:8080/app/. Choose New profile, enter a name, save it, and select Launch. Headless mode is available in the profile form for environments without a desktop.

Just looking around? Open the demo to try organizing profile settings. It does not connect to the Java backend or launch browsers.

Working with profiles

Create and organize

Give profiles a name, color, comma-separated tags, and notes. Search names, tags, proxies, or notes. Select a tag in the sidebar and use the status selector to narrow the list.

Configure the browser

Set a start URL, browser language, window dimensions, optional user agent, and proxy. The locale is passed as a browser language flag; it does not change the timezone, and website language negotiation is not guaranteed. Supported proxy formats are http://host:port, https://host:port, and socks5://host:port. Proxy credentials are not supported.

Launch and stop

A profile launches your configured browser in its own data directory. Stop it from the dashboard before editing its settings, resetting its browser data, or deleting it. Closing the browser also releases its running status.

Duplicate, import, and export

Duplication copies settings into a fresh profile. JSON export includes settings only; it does not include browser sessions, cookies, history, or passwords. Import validates the whole file and assigns new profile IDs.

Reset or delete

Reset removes a stopped profile’s browser data while keeping its settings. Delete removes both. The dashboard asks for confirmation before either action.

Use developer tools

For a running profile, choose the CDP action to copy its loopback debugging URL. Tools compatible with Chrome DevTools Protocol can attach to the same browser session. Debugging ports are local and must not be published.

Configuration

Set these environment variables before starting the JAR. Restart the application after changing them. Browser detection searches common installation locations; set an absolute executable path if automatic detection does not find yours.

VariableDefaultPurpose
NABIL_HOST127.0.0.1Listening address. Remote binding requires a token.
NABIL_PORT8080HTTP port.
NABIL_DATA_DIR./dataProfile settings and browser data.
NABIL_BROWSER_PATHAuto-detectAbsolute Chrome or Chromium executable path.
NABIL_AUTH_TOKENUnsetShared access token for the UI and API.
NABIL_MAX_RUNNING5Maximum concurrent browser profiles.

Linux / macOS example

export NABIL_DATA_DIR="$HOME/nabilbrowser-data"
export NABIL_BROWSER_PATH="/path/to/chrome"
java -jar target/NabilBrowserManager-1.0.0.jar

Windows PowerShell example

$env:NABIL_BROWSER_PATH = "C:\Program Files\Google\Chrome\Application\chrome.exe"
$env:NABIL_DATA_DIR = "$HOME\nabilbrowser-data"
java -jar target/NabilBrowserManager-1.0.0.jar

Access protection

With NABIL_AUTH_TOKEN set, the dashboard prompts for that token and keeps it only in the current browser tab’s session storage. API clients send Authorization: Bearer <token>. The health route remains public. For remote operation, configure HTTPS at your reverse proxy and keep browser debug ports private.

API reference

The JSON API is available under /api. Send Content-Type: application/json on requests with JSON bodies. Errors return {"error":"message"} with an appropriate HTTP status. When enabled, authentication applies to every route except health.

MethodEndpointBehavior
GET/api/healthHealth and version.
GET/api/statusBrowser availability, environment, and profile counts.
GET / POST/api/profilesList or create profiles.
GET / PUT / DELETE/api/profiles/{id}Read, update, or delete one profile.
POST/api/profiles/{id}/launchLaunch and wait for browser readiness.
POST/api/profiles/{id}/stopStop an owned browser session.
POST/api/profiles/{id}/duplicateCopy settings to a new profile.
POST/api/profiles/{id}/resetClear browser data for a stopped profile.
GET/api/profiles/{id}/cdpGet a running profile’s local debugging endpoints.
GET/api/exportExport metadata in schema version 1.
POST/api/importValidate and import metadata as new profiles.

Create a profile

curl -X POST http://127.0.0.1:8080/api/profiles \
  -H 'Content-Type: application/json' \
  -d '{"name":"Research","startUrl":"https://example.com","tags":["Work"]}'

Launch it

curl -X POST http://127.0.0.1:8080/api/profiles/PROFILE_ID/launch \
  -H 'Content-Type: application/json' \
  -d '{}'

Import format

{
  "schemaVersion": 1,
  "profiles": [
    {
      "name": "Research",
      "notes": "A focused workspace",
      "tags": ["Work"],
      "color": "#7555f8",
      "startUrl": "https://example.com",
      "proxy": "",
      "locale": "en-US",
      "userAgent": "",
      "width": 1440,
      "height": 900,
      "headless": false
    }
  ]
}

Deploying the website

The website/ directory is a complete static website. Upload its contents to your host’s document root, then configure your domain with that host. It includes the landing page, documentation, app interface, and local assets. No Node.js build step is required.

The Java build also packages these pages and serves them from the same origin as the API. On a static host, use /app/?demo=1 for the demo. For real profile control, open /app/ on the machine running the Java manager. A remote website cannot start browsers on a visitor’s computer.

The NabilBrowser.com branding does not configure or verify domain ownership. Pointing that domain to a host is a separate deployment step.

Troubleshooting

The browser was not found.

Install Chrome or Chromium and restart, or set NABIL_BROWSER_PATH to the absolute executable path. A path to an application folder is not enough. On macOS, use the executable inside the .app bundle.

The app says it cannot connect.

Start the JAR and open its own http://127.0.0.1:8080/app/ URL. A static website has no Java API. Check that another app is not using the same port. The dashboard never changes to demo mode automatically.

Launching a browser fails on Linux.

Windowed mode needs a graphical desktop and a working display. Try headless mode on a server. Run as an ordinary user and keep the Chromium sandbox enabled. The manager does not disable the browser sandbox to work around root-user restrictions.

The data folder is locked.

Only one manager process may own a data directory at a time. Stop the earlier manager, or choose a separate NABIL_DATA_DIR for a second instance. Do not remove a live process’s lock.

Can I use a proxy with a username and password?

This version accepts credential-free proxy URLs only. It does not implement an authentication extension or credential forwarding. Configure an appropriate local proxy externally if your workflow needs authenticated upstream access.

Scope & attribution

NabilBrowserManager is an independent Java implementation inspired by CloakBrowser Manager. It includes profile management and Chrome/Chromium process control. It does not include CloakBrowser, a browser-fingerprint engine, a remote VNC viewer, browser-state cloning, proxy geolocation, or a cloud account service.

The source package includes the project license and attribution notices. Chrome, Chromium, and any separately installed software retain their respective licenses.