How to Install the Hermes Browser Workspace Locally

Step-by-step setup

Step 1: Confirm Hermes works in the terminal

Open the same shell where you installed Hermes and run:

hermes --help

Then start a normal Hermes chat or run your existing setup command:

hermes setup

Do this before troubleshooting the browser. If the base agent cannot start, the dashboard will not have a healthy backend to manage.

If you use Ollama locally, confirm that Ollama is reachable from the Hermes environment before opening the browser UI.

For WSL2 with Ollama running inside WSL2:

curl http://127.0.0.1:11434/v1/models

For a WSL2 setup that needs to reach Ollama running on the Windows host, try the host bridge first:

curl http://host.docker.internal:11434/v1/models

If that hostname is not available in your WSL2 environment, use the Windows host IP from WSL or switch to mirrored networking if your Windows build supports it.

Step 2: Launch the official Hermes dashboard

Start the local dashboard with:

hermes dashboard

The dashboard opens on:

http://127.0.0.1:9119

This is the built-in Hermes browser interface. It is meant for managing your local Hermes installation without editing configuration files by hand.

In the dashboard, you can manage:

• Agent status and recent sessions
• Model and provider configuration
• Gateway status
• API keys and local credentials
• Logs
• Scheduled jobs
• Skills and toolsets
• Memory and session history

The dashboard binds to localhost by default. Keep it that way unless you have a specific reason to expose it beyond your own machine.

Step 3: Use the main dashboard options

For a different port:

hermes dashboard --port 8080

For a dashboard that does not automatically open the browser:

hermes dashboard --no-open

For an explicit localhost bind:

hermes dashboard --host 127.0.0.1

Avoid binding the dashboard to 0.0.0.0 on a normal personal machine. A browser dashboard for an agent can expose credentials, configuration, logs, and tool access. Treat it as a private local control panel, not a public web app.

Step 4: Enable the in-browser TUI chat

The standard dashboard does not automatically expose the embedded chat terminal. To enable the browser Chat tab, install the optional dashboard dependencies:

pip install 'hermes-agent[web,pty]'

Then launch:

hermes dashboard --tui

You can also enable the same behavior with:

HERMES_DASHBOARD_TUI=1 hermes dashboard

The Chat tab runs the Hermes terminal interface behind a pseudo-terminal and streams it into the browser. That is why WSL2 matters on Windows: a normal native Windows shell may not support the same PTY behavior for this feature.

If the rest of the dashboard works but the Chat tab fails, test the normal terminal TUI first:

hermes --tui

If hermes --tui fails, fix the terminal-side issue before debugging the browser.

Step 5: Install the community Hermes WebUI

The official dashboard is built into Hermes. The community Hermes WebUI is a separate browser workspace that provides a more app-like interface around Hermes, including a three-panel layout with navigation, chat, and workspace file browsing.

Use it when you want:

• A fuller browser-first workspace
• Session navigation in a side panel
• Workspace file browsing and previews
• A UI that feels closer to a dedicated local web app

Clone the WebUI repository:

git clone https://github.com/nesquena/hermes-webui.git hermes-webui
cd hermes-webui

Then follow the repository's current install instructions. The WebUI project changes quickly, so use its README as the source of truth for the exact bootstrap command, Docker command, or local Python setup.

The important principle is simple: install Hermes Agent first, confirm it works, then add the WebUI. Do not use the WebUI as a workaround for a broken Hermes setup.

Step 6: Choose official dashboard or WebUI

Use the official Hermes dashboard if your goal is configuration, sessions, logs, jobs, skills, API keys, and the built-in browser Chat tab.

Use the community Hermes WebUI if your goal is a broader browser workspace with a three-panel interface and file-oriented workflow.

For most local users, the clean order is:

1. Install Hermes Agent.
2. Connect the model provider.
3. Run hermes dashboard.
4. Add --tui if you want browser chat.
5. Try the community WebUI only after the official dashboard works.

That order makes troubleshooting much easier because each layer has a clear dependency.

Common problems

If Hermes starts in WSL2 but your Windows browser cannot open http://127.0.0.1:9119, check these points in order.

Confirm the dashboard is running

Inside WSL2:

curl http://127.0.0.1:9119

If that fails inside WSL2, the dashboard is not listening correctly. Restart it with:

hermes dashboard --host 127.0.0.1 --port 9119

Try the WSL2 IP address

Inside WSL2:

hostname -I

Then open this from Windows, replacing the IP address:

http://<wsl-ip-address>:9119

This is useful when localhost forwarding is not behaving as expected.

Check for a port conflict

If port 9119 is already in use, choose another port:

hermes dashboard --port 9120

Then open:

http://127.0.0.1:9120

Use mirrored networking when appropriate

On supported Windows 11 builds, WSL mirrored networking can make localhost behavior more predictable between Windows and WSL2. If you use it, restart WSL after changing WSL networking settings and test the dashboard again.

Next useful actions

After the dashboard opens reliably, decide whether the official dashboard is enough or whether you also need the optional in-browser TUI or community WebUI. Keep the first browser workspace local, run one low-risk session, and confirm that logs, memory, skills, and API key screens are not visible to anyone who should not manage the agent.

Background, planning, and caveats

Questions to answer before installing

• Do you want only the official dashboard, or do you also need the optional in-browser TUI tab?
• Is your model local (Ollama/LM Studio) or hosted behind a paid API, and is that budget approved?
• Are you running all Hermes parts in WSL2, Docker, or native Windows/Unix, and can you keep network paths consistent?
• Do you need immediate messaging integrations, or should they wait until after a stable dashboard baseline?
• Which team members will have access to the machine and local browser?

Approximate U.S. planning cost

Expected cost profile for this install path:

• License: Hermes Agent and dashboard are local OSS/core components, so no product subscription cost.
• Hardware: local setup is usually existing workstation cost; add GPU/CPU upgrades only if you run larger local models.
• Model API spend: free if fully local; billed per request if you use remote providers.
• Cloud or VPS: optional and only needed for remote access or team hosting.
• Developer setup time: 30 minutes to 2 hours, plus follow-up testing.

Cost breakdown

• Core software: $0
• Local model provider (Ollama/LM Studio): local compute only, no API meter
• Hosted model calls: provider-dependent usage charges
• Optional agent storage and logs: usually minor on local disk
• Optional remote deployment: standard VPS or cloud pricing, if selected

Official-source caveats

The exact command set can drift between Hermes releases. Use official docs as the source of truth before scripting installs:

• https://hermes-agent.nousresearch.com/docs/getting-started/installation/
• https://hermes-agent.nousresearch.com/docs/user-guide/features/web-dashboard
• https://hermes-agent.nousresearch.com/docs/windows-native

If an official page says a flag is no longer available, stop copying older commands and align to the current page.

Security checklist

Keep the browser workspace local unless you are deliberately building a secured remote setup.

Use these rules:

• Bind to 127.0.0.1 for everyday local use.
• Do not expose the dashboard to a public interface.
• Do not open firewall access unless you know exactly why.
• Treat API key screens as sensitive.
• Be careful with any tool or skill that can execute shell commands.
• Back up Hermes configuration and memory before major upgrades.
• Use SSH tunneling instead of public binding when accessing a remote machine.

The dashboard is powerful because it can manage the agent. That also means it deserves the same caution as any local admin panel.

Credential handling

• Prefer storing model and gateway tokens in the Hermes credential layer instead of ad hoc environment exports.
• Never share screenshots that show full .env or config content with keys visible.
• Revoke/rotate keys if command history or terminal logs were copied to another tool.
• Grant workspace service accounts only the minimum permissions needed for testing.

Filesystem permissions

• Use a normal user context for install and runtime.
• Keep ~/.hermes (and related install paths) writable only for the active user unless you run a managed multi-user setup.
• If hermes dashboard or daemon setup fails, check directory ownership before changing model endpoints.
• Back up and version control config, logs, and memory only if policy allows; these can include workspace references.

Rollback and update

For production-safe workflows:

1. Run hermes update after you have a clean baseline backup.
2. Run hermes doctor and quick CLI checks.
3. Restart dashboard and run one deterministic smoke test.

If things regress, restore from your prior state snapshot and re-run setup.

In many Hermes maintenance flows, a rollback point is created around update operations. Prefer restore-first behavior to deleting and reinstalling when state corruption is likely.

Common red flags

• Enabling public binding (--host 0.0.0.0) on unmanaged networks.
• Installing messaging channels before your approval strategy is clear.
• Running dashboard and WebUI on mixed network paths without endpoint verification.
• Ignoring WSL2 host resolution checks and masking port errors.

Common setup mistakes

The most common mistake is trying to install a browser UI before the base Hermes Agent works. Always prove the terminal path first.

Another common mistake is mixing environments. If Hermes runs in WSL2, install dashboard dependencies inside WSL2. If Hermes runs in a container, route browser and model connections according to that container setup. If Ollama runs on the Windows host, test the host bridge or the Windows host IP from inside the Hermes environment.

The third common mistake is exposing the dashboard too broadly. A local web UI for an autonomous agent is not the same risk profile as a static webpage. Keep it private unless you have authentication, firewall rules, and a clear network plan.

Bottom line

Start with the built-in Hermes dashboard:

hermes dashboard

Then add the browser chat pane only if you need it:

pip install 'hermes-agent[web,pty]'
hermes dashboard --tui

If you want a richer workspace UI, install the community Hermes WebUI after the official dashboard is already working. This gives you a stable troubleshooting path: terminal first, official dashboard second, community workspace third.