Install Hunt Web on Linux Desktop

This guide covers installation from a downloaded Hunt Web package, local Dashboard setup, model configuration, and a visible Chromium session for Greybox Browser testing. The Desktop installation includes the CLI, Dashboard, Hermes, scanner tools, Chromium, and PDF report components. Once setup is complete, the same installation supports Blackbox, Greybox Environment, and Greybox Browser.

1. Check the Requirements

The supported installer platform is Ubuntu 24.04 x86_64 with Python 3.12. Use a terminal inside an active graphical Desktop session and a regular user account with sudo access.

Check the architecture, Python version, and available home-directory space from the terminal:

uname -m
python3 --version
df -h "$HOME"

Use one user account and a fixed installation location throughout this guide. The installer manages its own Node/pnpm, Hermes, tools, and Chromium. A separate global Hermes or browser runtime installation is not required beforehand.

2. Verify and Extract the Release Package

Obtain the release archive and its published checksum from the official Hunt Web release channel. This example assumes the file is saved as ~/Downloads/hunt-web-2.0.tar.gz.

sha256sum "$HOME/Downloads/hunt-web-2.0.tar.gz"

Compare the output with the checksum published for that release. Once it matches, extract into a new application directory:

mkdir "$HOME/hunt-web-v2" &&
tar -xzf "$HOME/Downloads/hunt-web-2.0.tar.gz" --strip-components=1 -C "$HOME/hunt-web-v2" &&
cd "$HOME/hunt-web-v2"

If the directory already contains an installation, use the package's upgrade guide instead of extracting over it. The examples use these locations:

Keep application and data directories separate. Use paths without spaces or symlinks, and keep the chosen directories in place after installation. Custom data paths and ports can be selected during the first install; see the included INSTALL-v2.md for those options.

3. Run the Installer and Choose Desktop

For an optional initial check, use ./install.sh --mode desktop --preflight-only. This checks prerequisites without installing components. If the default ports are occupied, choose different ports with --port and --hermes-port on the first installation command, then use the selected Dashboard port in the URLs below.

From the application directory, run:

./install.sh --time-zone Asia/Jakarta --configure-later

The installation-mode prompt offers:

Installation mode:
1. Linux Desktop
2. Linux Server / VPS

Enter 1 for Linux Desktop. The example selects Asia/Jakarta for the Dashboard display and service time zone; replace it with the required IANA time zone if needed. Without the option, the default is UTC. The --configure-later option keeps account and model configuration in the next step of this guide.

Approve the requested OS dependencies using sudo when prompted. The installer downloads and builds the required components, including a real Chromium browser and the Python components for PDF export. First installation can take time; allow each stage to finish.

Wait for Installation components checked. At that point, the generated dashboard.sh launcher is available. Browser login and the first Admin account are configured next; installation does not start a scan.

4. Configure the Model and Optional Tool Keys

Run:

./configure.sh

At Configure Hermes provider/model now?, answer y, select the provider and model, and complete its authentication prompts. This configures the installation's Hermes profile for scanner and chat work.

The wizard also offers optional tool keys:

Uncover can use other providers, which have their own credentials; see Scanning Tools for each tool's key requirements. These are separate from model-provider credentials. Optional tool keys can be configured later; capabilities that require a missing key will still need that key. For each tool key, Enter keeps or skips the value, n opens a hidden input, and r reuses compatible private configuration when detected. Enter keys through the configuration prompts rather than chat messages.

While first-time Admin setup is pending, configure prints a one-time setup code valid for 10 minutes. Keep it for the next step. Answer n to Start Dashboard setup now? to launch setup explicitly in the next step.

5. Create the First Admin and Sign In

Start the setup launcher:

./dashboard.sh --setup

Keep that terminal open. On the same computer, visit http://127.0.0.1:3053/setup and enter the setup code, username, display name, and an Admin password of 12–128 characters.

If the code expires while setup is pending, open a second terminal in the application directory and run ./configure.sh --setup-code to obtain a new one. Once the first Admin has been created, setup is closed. Additional accounts can be created later through Users & Roles.

Return to the setup terminal and press Ctrl+C. Then start the normal Dashboard:

./dashboard.sh

Open http://127.0.0.1:3053/sign-in and sign in with the newly created account. Use the configured 127.0.0.1 address consistently for this local setup.

Enlarge

To enable MFA, open Profile → Security / Sessions → Authenticator protection. Confirm the account password, add the displayed setup secret to Google Authenticator or another TOTP app, and enter its six-digit code to complete activation. Store the recovery codes privately.

MFA is optional for the local Admin at 127.0.0.1 under the current access rule. Admin access through a domain requires it and directs unenrolled Admins to this setup page. Once MFA is enabled, future logins need an authenticator code or a single-use recovery code. The authenticator app generates the code; Hunt Web does not send it by email.

6. Check the Installed Components

Leave the Dashboard running. In a second terminal, open the application directory and check the installation:

cd "$HOME/hunt-web-v2"
./configure.sh --status
./dashboard.sh status
"$HOME/.local/share/hunt-web-v2/bin/hunt-web" --version
"$HOME/.local/share/hunt-web-v2/bin/hunt-web" capabilities

For a custom data directory, use the CLI wrapper under that directory's bin folder. This keeps CLI commands connected to this installation's configuration.

In the Dashboard, open Health and select Refresh status. Read each component's status and next step. Hermes connectivity checks the Gateway; it does not establish that a model request will succeed. Review the provider and model under Settings → Hermes Chat, separately from Assistant settings.

Enlarge

The screenshot shows an existing workspace. A new installation may have no saved reports yet. Model credentials, connectivity, and quota can be checked further with a short assessment on an authorized test application before starting a longer scan.

7. Verify Chromium Launch in the Desktop Session

Hunt Web installs Chromium as the browser; Playwright supplies the automation library that controls it. For Greybox Browser, check the visible window and the account session as separate steps:

1. Create a Greybox Browser Target for the test application and save its Scope, application URLs, and account settings.
2. Use the account's browser-opening control in Target setup. Confirm that a Chromium window actually appears in the active Desktop session.
3. Sign in to the target application, including its MFA if required, and open the configured application check page.
4. Use the account's Check access control and confirm that access is verified. For two accounts, complete the checks for both separate sessions.

Refresh status reads saved state; it does not perform a fresh login check. After account access is ready, choose Prepare Run, then select Quick, Standard, or Deep and start the assessment.

8. Start, Stop, and Return After Reboot

./dashboard.sh runs in the foreground. To run in the background, stop an idle foreground launcher first, then use ./dashboard.sh start from the same graphical session.

Pause active scans and wait for scanner and Hermes work to become idle before stopping or restarting services. A service restart does not automatically resume a scan.

After reboot, sign in to the graphical Desktop, open a terminal in ~/hunt-web-v2, and start the Dashboard again. Browser launching uses that Desktop session. Background launcher logs are stored at ~/.local/share/hunt-web-v2/logs/dashboard.log with the default data location.

Troubleshooting

The package's INSTALL-v2.md and docs/operations.md provide more installation options and troubleshooting details. With the Dashboard and account access ready, continue to the scanning workflow guide to prepare the first Run and follow it through Findings and Report.