Install WebBrain and Connect Remote Ollama with Localtonet

How WebBrain, Ollama, and Localtonet fit together

WebBrain is an open-source browser extension for Chrome, Firefox, Edge, and compatible Chromium browsers. It runs in a side panel next to the active tab and can use the page as context for questions or browser tasks. Its three documented modes have different capabilities: Ask is read-only, Act can interact with pages, and Dev adds development-oriented information and reversible page edits.

WebBrain can use its managed default model or a model provider selected in Settings. Ollama is one of its documented local providers. Ollama exposes an HTTP API on port 11434 by default, including an OpenAI-compatible interface under /v1. WebBrain sends requests to that interface and receives model responses.

A loopback URL such as http://127.0.0.1:11434/v1 works only when the browser and Ollama are on the same computer. If WebBrain runs on a laptop and Ollama runs on a workstation elsewhere, 127.0.0.1 in WebBrain refers to the laptop. It does not refer to the Ollama workstation.

With Localtonet, our client runs on the Ollama computer or on another device that can reach it. The client establishes an outbound connection to a Localtonet relay server. An HTTP tunnel provides a public HTTPS URL and forwards requests to the configured local IP address and port. This avoids inbound router port forwarding, firewall changes, VPN setup, and the need for a public IP address.

Prerequisites and decisions to make first

Prepare each component before exposing the model service. Keeping the stages separate makes it possible to identify whether a failure belongs to WebBrain, Ollama, the Localtonet tunnel, or browser-origin enforcement.

• A current Chrome, Firefox, Edge, or compatible Chromium browser.
• Permission to install an extension or use the browser's temporary development-loading feature.
• An existing Ollama installation on the model-server computer.
• At least one model already installed in that Ollama instance.
• A command-line HTTP client such as curl for independent API checks.
• A Localtonet account and a connected client device that can reach Ollama.
• The device-specific Localtonet authentication token for that client.
• A decision between a short-lived direct test and a persistent authenticated deployment.

The simplest topology runs the Localtonet client on the same computer as Ollama. The tunnel can then target 127.0.0.1:11434, or a loopback reverse proxy if one is required. Keeping Ollama bound to loopback limits direct LAN exposure while the Localtonet client reaches it locally.

The Localtonet client can instead run on another private-network device, but Ollama must listen on an address reachable from that device. Ollama controls its listening address through OLLAMA_HOST. Changing it from loopback can expose the service to other devices on that network, so make that change only when the architecture requires it and apply appropriate host firewall policy.

Install and verify WebBrain

Most users should install WebBrain from an official browser marketplace. The current project documents releases through the Chrome Web Store, Firefox Add-ons, and Microsoft Edge Add-ons. Visit the official WebBrain website and follow the installation link for your browser. Confirm the extension identity, review its requested permissions, and complete the browser's normal installation prompt.

After installation, open the WebBrain side panel from its extension icon. Pinning the icon is optional. If the browser requests access to a site, consider whether that access is necessary for the page and task you intend to use.

Optional direct source loading

Developers and reviewers can clone the official repository:

git clone https://github.com/webbrain-one/webbrain.git

For Chrome, open:

chrome://extensions/

Enable Developer mode, select Load unpacked, and choose:

webbrain/src/chrome

For Firefox, open:

about:debugging#/runtime/this-firefox

Select Load Temporary Add-on and choose:

webbrain/src/firefox/manifest.json

Firefox removes temporary add-ons when the browser restarts. Permanent Firefox installation requires signing through addons.mozilla.org. For routine use, the signed marketplace release is more convenient.

Verify the extension before selecting Ollama

Check the extension manager for duplicate installations before continuing. A marketplace copy and source-loaded copy can have different settings and separate storage. Disable the copy you are not testing.

Start Ollama and verify its API locally

Start Ollama using its documented server command if it is not already running:

ollama serve

Keep that process running while performing the following checks. If your operating-system installation manages Ollama as a background service, use its normal service controls instead of starting a duplicate process.

Check the basic service response

curl -i http://127.0.0.1:11434/

A successful response confirms that something is listening on Ollama's expected loopback port. A connection-refused error means that no process accepted the connection at that address and port. Resolve that before creating a tunnel.

Discover installed models through the native API

curl http://127.0.0.1:11434/api/tags

The JSON response lists models known to this Ollama instance. Copy the exact model identifier you intend to use, including any tag shown by the server. Do not substitute a model name from an example if it is not present in this response.

Verify the OpenAI-compatible model list

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

This is the interface relevant to WebBrain. A successful response should contain an OpenAI-style model list. If /api/tags works but /v1/models does not, the problem is local API compatibility rather than Localtonet.

Perform a local OpenAI-compatible generation

Replace YOUR_INSTALLED_MODEL with an exact identifier returned by the model-list check:

curl http://127.0.0.1:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_INSTALLED_MODEL",
    "messages": [
      {
        "role": "user",
        "content": "Reply with the single word READY."
      }
    ],
    "stream": false
  }'

A successful JSON response containing an assistant message proves that the model can generate through the same API family WebBrain uses. A model-not-found response means the identifier is wrong or unavailable. A server error during loading or inference belongs to Ollama or the model environment and should be resolved before tunneling.

Create the Localtonet HTTP tunnel

Use an HTTP tunnel because WebBrain communicates with Ollama through HTTP. File Server, proxy tunnels, and VPN Manager address different use cases and are not substitutes for this forwarding configuration.

The current dashboard options should be checked against our HTTP tunnel documentation. Exact relay choices and account-specific options come from the live dashboard.

Test the public API and handle Host or origin failures

Do not enter the endpoint into WebBrain immediately. First test the public API with a command-line client. If the tunnel URL is https://your-assigned-address, request:

curl -i https://your-assigned-address/v1/models

Use the exact HTTPS URL assigned by the running tunnel. The hostname above is only a placeholder. Do not append the local port to an HTTP tunnel URL unless the dashboard explicitly supplies a public host-and-port endpoint.

Option A: Configure the required Ollama origins

Ollama uses OLLAMA_ORIGINS to add trusted origins. If the public hostname is stable, add the exact public origin rather than using a broad wildcard, then restart Ollama so the changed environment takes effect. For example, the value would include the real origin in this form:

OLLAMA_ORIGINS=https://your-assigned-address

Browser requests can also carry an extension origin such as a chrome-extension:// or moz-extension:// value. Do not guess it. If the command-line public test succeeds but WebBrain reports a CORS or origin error, inspect the failed request in the browser's extension or developer tools and identify the exact Origin value. Add only the specific trusted origin required by your installation, then restart Ollama and repeat the test.

Environment-variable configuration and service restart steps differ among operating systems and installation methods. Apply OLLAMA_ORIGINS using the same supported service environment mechanism used by your Ollama installation. Confirm the effective behavior with a request rather than assuming that editing a shell variable changed an already-running background service.

Option B: Put a Host-rewriting reverse proxy in front of Ollama

Ollama's public-tunnel guidance uses a Host header override because a tunnel normally forwards its own public hostname. Since this guide cannot claim that Localtonet rewrites that header, a local reverse proxy is the predictable fallback. The proxy receives the tunnel request and sends it to Ollama with the Host value Ollama expects.

A minimal Nginx server block can listen only on loopback port 8080 and forward to Ollama:

server {
    listen 127.0.0.1:8080;

    location / {
        proxy_pass http://127.0.0.1:11434;
        proxy_set_header Host localhost:11434;
    }
}

Validate and reload Nginx using the supported procedure for your operating system and installation. Then test the proxy locally before changing Localtonet:

curl -i http://127.0.0.1:8080/v1/models

If that succeeds, change the Localtonet HTTP tunnel target from port 11434 to 8080, restart the tunnel, and repeat the public /v1/models request. The reverse proxy addresses the Host header sent to Ollama. If WebBrain still reports a browser-origin error, configure the required exact origin through Ollama's supported OLLAMA_ORIGINS mechanism.

Verify a completion through the public endpoint

After /v1/models succeeds, replace the model placeholder and send a controlled public request:

curl https://your-assigned-address/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_INSTALLED_MODEL",
    "messages": [
      {
        "role": "user",
        "content": "Reply with the single word REMOTE."
      }
    ],
    "stream": false
  }'

This test proves that the public endpoint can perform inference independently of WebBrain. If model discovery works publicly but completion fails, compare the response with the same request sent locally. The tunnel cannot make an unavailable model load successfully.

Configure WebBrain for the remote Ollama server

Open WebBrain's Settings and go to its provider or model configuration. The current project includes an Ollama provider card and also supports generic OpenAI-compatible providers. Choose the Ollama card for a standard Ollama server. Use a generic OpenAI-compatible provider only when your gateway requires that configuration.

Understand WebBrain's research-sharing control

For local and bring-your-own providers, WebBrain's provider-specific Share queries for research switch is documented as off by default. When enabled, it can share a scrubbed prompt and response plus a bounded, content-free diagnostic timeline for that provider's model attempts, including failed runs. The diagnostic timeline can contain tool names, outcomes, error codes, and timings, but not tool arguments, page content, or screenshots.

A failure before normal generation can still contribute a bounded model-facing request and final blocker when sharing is enabled. Turning the switch off also purges queued diagnostics. Review this setting for the specific provider rather than assuming that using a local model alone determines all research-sharing behavior.

Distinguish provider errors from tunnel errors

A tunnel failure usually appears before Ollama can return a meaningful model response. Examples include DNS failure, connection failure, gateway errors, or inability to reach the local target. A provider failure occurs after the endpoint is reachable and can include an invalid model identifier, unsupported request behavior, missing gateway credentials, or an Ollama error response.

A browser CORS failure occupies a third category. The command-line public test can succeed while the browser blocks WebBrain from reading the response. Look for an Origin or CORS message in the relevant developer console, identify the exact rejected origin, and update the narrow Ollama origin policy. Do not rebuild the tunnel merely because a browser-only request was rejected.

Security and privacy considerations

Local inference can keep model execution on hardware you control, but the remote browser still sends prompts and page context to the public endpoint. The tunnel makes the target reachable. It does not add application authentication to an Ollama service that does not already require it.

Use direct unauthenticated publication only for a short test

A direct Localtonet HTTP tunnel to Ollama can be useful for a controlled validation window. Start it immediately before testing, avoid sensitive page content, do not share the URL, and stop it as soon as the test is complete. A difficult-to-guess URL is not a durable authorization mechanism.

For persistent access, place a compatible authenticated gateway in front of Ollama and tunnel the gateway rather than the bare model API. The gateway should enforce the access policy required by your environment. Confirm that its authentication format is supported by the WebBrain provider configuration you choose.

Use least-capability browser modes

Ask mode is read-only and is the safest starting point. Act can click, type, navigate, upload, download, and fill forms. Dev adds page source, styles, console and network context, plus reversible page edits. Use Act or Dev only when the task requires those capabilities, and review plans and permission prompts before consequential actions.

Separate Localtonet identity from API authorization

A Localtonet authentication token identifies the client device that carries a tunnel. It is not an Ollama API key and should never be entered into WebBrain. The public tunnel URL is also not the device token, but it should still be treated as sensitive when it leads to an unauthenticated service.

Restrict origins without confusing them with authentication

OLLAMA_ORIGINS controls which browser origins Ollama accepts. Host rewriting determines which Host value Ollama receives. Neither mechanism verifies the identity of an individual user. A persistent deployment still needs an appropriate authentication and authorization layer.

Test with low-risk content

Use public documentation during installation and connectivity checks. Avoid financial dashboards, authentication pages, health information, private code, confidential files, customer records, and production administration panels. Prove the architecture before evaluating higher-risk workflows.

Routine operation and safe shutdown

Use a consistent startup sequence so each dependency can be checked before the next one:

1. Start Ollama and request the local /v1/models endpoint.
2. If used, start or verify the local reverse proxy and test its /v1/models endpoint.
3. Run the Localtonet client on the device that can reach the selected target.
4. Start the saved HTTP tunnel.
5. Request the public /v1/models endpoint.
6. Confirm that WebBrain still uses the correct HTTPS base URL with /v1.
7. Begin with a low-risk Ask-mode request.
8. Use Act or Dev only when required.

If the Ollama port, proxy port, listening address, or host computer changes, update and retest the Localtonet target. If the public URL changes, update WebBrain and any exact OLLAMA_ORIGINS entry that referred to the old origin.

For shutdown, stop the Localtonet tunnel first to end public reachability. Then stop the reverse proxy or Ollama if your operating policy does not require them to remain available locally. You can retain the stopped tunnel configuration for later use or delete it when it is no longer needed.

Document which machine owns the model, which Localtonet device carries the tunnel, whether the target is Ollama or a reverse proxy, which provider is active in WebBrain, and who is authorized to use the endpoint. Keep tokens, gateway credentials, private model names, and reusable URLs out of screenshots and support transcripts.

Troubleshooting WebBrain, Ollama, and Localtonet

The WebBrain icon or side panel does not appear

Confirm that the extension is installed and enabled. For a source-loaded Chrome copy, verify that the selected directory is webbrain/src/chrome. For Firefox, reload webbrain/src/firefox/manifest.json after a browser restart because temporary add-ons are removed. Disable duplicate store and source installations.

The local Ollama connection is refused

Confirm that Ollama is running and listening at the address used by the request. Test http://127.0.0.1:11434/ on the Ollama host. If the Localtonet client runs on another machine, loopback is not reachable from that client and Ollama or the reverse proxy must listen on an appropriate private address.

/api/tags works but generation fails

Model metadata can be available even when inference fails. Verify the exact model identifier, check the Ollama error body, and repeat the same completion locally. Resolve model loading, memory, or server errors before testing remotely.

The public endpoint returns 403

This commonly indicates Ollama's Host or origin validation. Localtonet is forwarding the public request, but this guide does not assume that it rewrites the Host header. Add the exact trusted origin through Ollama's supported configuration where appropriate, or tunnel a local reverse proxy that sets Host to localhost:11434.

The public endpoint returns a gateway or target error

Confirm that the Localtonet client is connected, the tunnel is started, and the local target is correct from the client's perspective. Test that exact target on the client device. If the tunnel now points to port 8080, verify that the reverse proxy is running there.

curl works but WebBrain reports CORS or Origin errors

Command-line clients do not enforce browser CORS policy. Inspect the failed browser request to find the exact Origin value. Add only the required trusted origin to Ollama through OLLAMA_ORIGINS, restart the Ollama service, and retest. Do not assume the public hostname and extension origin are the same value.

WebBrain reports that the model does not exist

Compare its configured model field with the exact identifiers returned by /api/tags or /v1/models. Tags are part of the identifier. If model discovery is available, refresh it after changing the endpoint. Alternatively, leave WebBrain's optional Model field blank when that behavior is suitable so loaded-model capability is checked again on each turn.

WebBrain works with its managed provider but not Ollama

This confirms the extension itself is operational. Recheck the selected provider, the HTTPS base URL, the /v1 suffix, the model identifier, and any authenticated gateway requirements. Then compare WebBrain's failure with the independent public completion test.

The tunnel worked and then stopped

Ollama must remain running, any reverse proxy must remain running, the Localtonet client must remain connected, and the tunnel must remain started. A saved tunnel configuration is not evidence that the tunnel is currently active.

Responses fail on large pages

WebBrain documents automatic context-window detection for Ollama and automatic conversation compaction, but fixed instructions, tool schemas, page content, history, and requested output still consume context. Its documented 16k value is a fallback rather than a guaranteed minimum. Try a model with a larger usable context window, shorten the conversation, narrow the task, or use a smaller page.

Remote generation is slow

Send a comparable request locally. If local inference is already slow, the model, context size, workload, or server hardware is the likely constraint. If local inference succeeds but the public request fails, diagnose connectivity and policy without assuming a performance guarantee from the tunnel.

Frequently asked questions