Skip to main content
Helium Services provide optional functionality like extension updates, browser updates, and filter list management while respecting user privacy. All services are opt-in and self-hostable.
Privacy First: Helium services are completely optional. The browser works fully offline when services are disabled.

Architecture Overview

Core Components

Service Registry

Centralized preference-based service configuration

Schema Versioning

User notification system for behavior changes

URL Builder

Dynamic URL construction based on preferences

Settings UI

User-facing service management interface

Service Types

1. Extension Updates

Provides privacy-respecting extension update checks:
GURL GetExtensionUpdateURL(const PrefService& prefs) {
    if (!ShouldAccessExtensionService(prefs)) {
        return GetDummyURL();
    }
    return GetServicesBaseURL(prefs).Resolve("/extensions/update");
}
Features:
  • No tracking or analytics
  • Only checks for user-installed extensions
  • Respects user privacy preferences
  • Can be completely disabled
Preference: helium.services.extension_updating

2. Browser Updates

Automatic browser update notifications:
GURL GetBrowserUpdateURL(const PrefService& prefs) {
    if (!ShouldAccessUpdateService(prefs)) {
        return GetDummyURL();
    }
    // Platform-specific URL construction
    return GetServicesBaseURL(prefs).Resolve("/updates/browser/...");
}
Platform Support:
  • ✅ macOS: Full auto-update support
  • ✅ Linux: Update notifications (manual install via package manager)
  • 🔄 Windows: In development
Preference: helium.services.update_fetching_enabled

3. uBlock Origin Assets

Proxied filter list updates:
GURL GetUBlockAssetsURL(const PrefService& prefs) {
    if (!ShouldAccessUBlockAssets(prefs)) {
        return GetDummyURL();
    }
    return GetServicesBaseURL(prefs).Resolve("/ubo/assets.json");
}
  1. Default lists are bundled with Helium and loaded from local storage
  2. When services enabled: Lists are updated via proxied requests through Helium services
  3. Privacy benefit: Filter list providers don’t see user IP addresses
  4. Optional lists: User-added lists are fetched directly (not proxied)
Source: ~/workspace/source/patches/helium/core/ublock-helium-services.patch Preference: helium.services.ublock_assets

4. Native Bangs

DuckDuckGo-style search shortcuts:
  • !g query → Google search
  • !gh query → GitHub search
  • !w query → Wikipedia search
Bangs are processed client-side when possible, with fallback to services for comprehensive support. Preference: helium.services.bangs_enabled

5. Spellcheck Dictionaries

Downloads language dictionaries for spell checking:
GURL GetSpellcheckURL(const PrefService& prefs) {
    if (!ShouldAccessServices(prefs)) {
        return GetDummyURL();
    }
    return GetServicesBaseURL(prefs).Resolve("/spellcheck/...");
}
Preference: helium.services.spellcheck_files

Schema Versioning System

Helium uses a schema versioning system to ensure users are informed about service behavior changes.

Current Schema Version

inline constexpr int kHeliumCurrentSchemaVersion = 1;
Source: ~/workspace/source/components/helium_services/schema.h:737

How It Works

1

Schema Version Increment

When services behavior changes significantly, the schema version is incremented.
2

User Notification

User sees a notification in the app menu and settings page explaining the changes.
3

Pending State

Changes are not active until the user acknowledges the notification.
4

Acknowledgment

User reviews changes and clicks “Got it” to accept the new schema version.

Notification UI

When schema changes are pending:

App Menu Badge

“Services updated” label appears on the app menu button

Settings Alert

Prominent notification on the Helium services settings page

Changelog Example

static constexpr auto kHeliumSchemaChangelog =
    base::MakeFixedFlatMap<int, std::string_view>({
        {
          1,
          "Automatic component updates are now available. "
          "They're managed by the same toggle that enables automatic browser updates.\n"
          "From now on, you'll be notified about major changes to Helium services. "
          "Even though these notifications are extremely rare, you can choose to "
          "ignore them and accept all future changes automatically."
        }
    });
Source: ~/workspace/source/components/helium_services/schema.cc:708-716

Service Configuration

Default Origin

const char kHeliumDefaultOrigin[] = "https://services.helium.imput.net";
All services are hosted at this domain by default.

Custom Origin

Users can self-host Helium services:
1

Open Settings

Navigate to Settings → Privacy and security → Helium services
2

Enter Custom URL

Input your self-hosted origin in the “Use your own instance” field
3

Validation

Only HTTPS URLs (or localhost for development) are accepted
4

Apply

Services immediately switch to your custom origin
Security Warning: Only use custom origins you control. Never paste URLs from untrusted sources.

Origin Validation

std::optional<GURL> GetValidUserOverridenURL(std::string_view user_url_) {
    if (user_url_.empty()) {
        return std::nullopt;
    }
    
    GURL user_url = GURL(user_url_);
    if (!user_url.is_valid()) {
        return std::nullopt;
    }
    
    bool isSecure = user_url.SchemeIs(url::kHttpsScheme) || 
                    net::IsLocalhost(user_url);
    if (!isSecure) {
        return std::nullopt;
    }
    
    return user_url;
}
Source: ~/workspace/source/components/helium_services/helium_services_helpers.cc:486-502

Preferences

All service preferences are stored in the user’s profile:
Preference: helium.services.enabled
Type: Boolean
Default: true
Description: Master switch for all Helium services
Preference: helium.services.origin_override
Type: String
Default: "" (empty)
Description: Custom self-hosted origin URL
Preference: helium.services.schema_version
Type: Integer
Default: 0
Description: Last acknowledged schema version
Preference: helium.services.disable_schema_alerts
Type: Boolean
Default: false
Description: Auto-accept all future schema changes
  • helium.services.extension_updating (Boolean)
  • helium.services.update_fetching_enabled (Boolean)
  • helium.services.ublock_assets (Boolean)
  • helium.services.bangs_enabled (Boolean)
  • helium.services.spellcheck_files (Boolean)
Source: ~/workspace/source/components/helium_services/pref_names.h

Settings UI Implementation

The Helium services settings page is implemented as a Polymer component:
<settings-toggle-button id="servicesToggleButton"
    pref="{{prefs.helium.services.enabled}}"
    label="$i18n{heliumServicesToggle}"
    sub-label="$i18n{heliumServicesToggleDescription}">
</settings-toggle-button>
Source: ~/workspace/source/chrome/browser/resources/settings/privacy_page/services_page.html:229-233

Privacy Guarantees

No Tracking

Services don’t log IP addresses, user agents, or create persistent identifiers

No Analytics

No usage statistics or telemetry collected

Minimal Data

Only necessary information sent (e.g., extension ID for updates)

Open Source

Services implementation will be published at helium-services

Self-Hosting Guide

To host your own Helium services instance:
1

Clone Repository

git clone https://github.com/imputnet/helium-services
cd helium-services
2

Configure Environment

Set up your environment variables and configuration
3

Deploy

Deploy to your server with HTTPS enabled
4

Configure Browser

Enter your origin in Helium settings → Helium services
Self-hosting documentation is available in the helium-services repository.

Next Steps

Architecture Overview

See how services fit into Helium’s architecture

Onboarding System

Learn how users consent to services during setup

Build docs developers (and LLMs) love