Tailscale in the browser without changing system VPN settings. For a short overview and install links, see the project README.
Version: 0.1.15 (extension and native host) | Manifest V3 Browsers: Chrome, Firefox, and Chromium-family browsers with the same Chrome Web Store build (Brave, Edge, Vivaldi, Opera; Arc on macOS) Platforms: macOS (amd64, arm64), Linux (amd64 packages; amd64/arm64 raw helpers), Windows (amd64 MSI; amd64/arm64 raw helpers). Chrome and Firefox Flatpak are separate Linux install paths (Chrome, Firefox) License: MIT Website: tesseras.org/tailchrome Chrome Web Store: Chrome Web Store Firefox Add-ons: Firefox Add-ons (AMO) Privacy Policy: privacy-policy.md
- Overview
- Architecture
- Feature Set
- Native Messaging Protocol
- Extension Internals
- Native Host Internals
- Proxy System
- State Management
- Popup UI
- Browser Differences
- Installation and Setup
- Project Structure
- Build System
- CI/CD Pipeline
- Test Infrastructure
- Configuration Reference
- Security Model
- Data Handling and Privacy
- Store Listings
- Contributing
Tailchrome runs a full Tailscale node in each browser profile. System networking is unchanged. Two components cooperate:
- A TypeScript Manifest V3 extension sets browser proxy rules and renders the popup, side panel, or sidebar UI.
- A Go native messaging host (
tsnet) runs the node and listens on a local SOCKS5/HTTP proxy.
They exchange JSON over the browser native messaging protocol. Browser tailnet traffic uses the local proxy, so Tailchrome works with or without the Tailscale system app.
Each browser profile has its own Tailscale identity. Different profiles can use different tailnets at the same time.
+---------------------------------------------+
| POPUP UI |
| (popup.ts, views/*.ts, components/*.ts) |
| - Connected view with peer list |
| - Exit node picker |
| - Profile switcher |
| - Disconnected / NeedsLogin / NeedsInstall |
+-------------------+--------------------------+
| chrome.runtime.Port ("popup")
| PopupMessage / BackgroundMessage
v
+---------------------------------------------+
| BACKGROUND SERVICE WORKER |
| (background.ts) |
| - StateStore (TailscaleState) |
| - NativeHostConnection (auto-reconnect) |
| - BadgeManager (icon/text updates) |
| - ProxyManager (Chrome PAC / Firefox API) |
| - Context menu handlers |
| - Keepalive timer |
+-------------------+--------------------------+
| chrome.runtime.connectNative()
| 4-byte LE length + JSON
| NativeRequest / NativeReply
v
+---------------------------------------------+
| NATIVE HOST (Go) |
| - tsnet.Server per browser profile |
| - IPN bus watcher (real-time state) |
| - SOCKS5 + HTTP proxy on 127.0.0.1:0 |
| - Tailscale web client at 100.100.100.100 |
| - Profile management (create/switch/delete) |
| - Taildrop file sender |
+---------------------------------------------+
|
| WireGuard / DERP / Control
v
Tailscale Network
- Startup: Extension opens native messaging connection. Host starts, binds a SOCKS5/HTTP proxy on a random local port, and sends
procRunningwith the port number and version. - Init: Extension sends
initwith a browser-profile UUID (initID) and an optionalwantRunninghint. Host creates (or reuses) atsnet.Serverwith state stored at~/.config/tailscale-browser-ext/<initID>/. Becausetsnet.StartforcesWantRunning=true, the host appliesWantRunning=falseright after starting a fresh server when the hint isfalse— this is what keeps the node down at browser launch when auto-connect is off. - State watching: Host starts a goroutine (
watchIPNBus) that monitors the IPN notification bus for state, prefs, netmap, browse-to-URL, and health changes. On any change, it fetches full status and sends aStatusUpdateto the extension. - Proxy routing: The background service worker receives the status, passes it to the
ProxyManager, which configures browser-level proxy rules (PAC script on Chrome,proxy.onRequeston Firefox). - Popup: When the user opens the popup, it connects via a
chrome.runtime.Portnamed"popup". The background immediately sends currentTailscaleState. User actions dispatchBackgroundMessagetypes which the background translates toNativeRequestcommands.
- Browse tailnet devices by IP or MagicDNS name from the browser.
- Each browser profile has its own Tailscale node and identity.
- Route all browser traffic through any exit node on your tailnet. When a suitable Mullvad exit exists, the picker shows a Recommended row labeled "Best available Mullvad VPN".
- Per-profile split tunneling with Bypass and Only domain rules. Rules match suffixes and apply after mandatory Tailscale routes (MagicDNS, 100.64.0.0/10, subnet routes), so tailnet traffic is unchanged.
- MagicDNS resolves tailnet device names.
- Split DNS uses nameservers from Tailscale or Headscale, including nameservers reached through subnet routes.
- Subnet routing reaches IPv4 and IPv6 resources behind subnet routers (detected from peer info).
- With an exit node enabled, you can optionally allow LAN access.
- The peer list groups online and offline peers, supports search, and updates the DOM incrementally.
- Copy a peer's Tailscale IP or DNS name to the clipboard in one click.
- Open a peer's web UI in a new tab.
- Open SSH-capable peers in the Tailscale web SSH client at
http://100.100.100.100/ssh/<hostname>. - Set a per-device custom port or URL for quick open actions.
- Send files to other tailnet devices with Taildrop.
- The context menu item "Send page URL to Tailscale device" sends the current page URL as a text file via Taildrop.
- File send progress appears in persistent toast notifications.
- Create, switch, and delete multiple Tailscale profiles (identities).
- Point a profile at a self-hosted HTTP(S) control server such as Headscale. Changing servers starts a fresh login on the new server and keeps the previous account in Profiles. The previous server does not need to be reachable.
- Shields Up blocks all incoming connections.
- Run as Exit Node advertises this browser node as an exit node.
- Login and logout authenticate with Tailscale. Login URLs must match allowed origins.
- Sign in with a pre-authorized auth key instead of a browser login. The key registers only the current browser profile, can carry tags for a narrow ACL, and is never saved by the extension or helper.
- Operational health warnings appear in a collapsible banner. The upstream experimental-build notice is informational only. Other warnings, including peer-list truncation, stay visible. The extension filters the experimental notice text from older compatible helpers.
- The extension icon shows online, offline, or warning state, with a text badge when an exit node is active. Experimental-build notices do not change connected or exit-node badges. Helper and routing failures still show warnings.
- Reconnect to the native host with exponential backoff (1s base, 30s max).
- After a package install, helper discovery retries on a session-persisted schedule. Current-user registration repair is offered only if discovery still fails.
- Missing registration, permission denial, startup failure, unexpected stop, helper-reported errors, and explicit protocol incompatibility each have distinct recovery copy.
- Copy or export a bounded, allowlisted helper diagnostic report with sensitive values redacted. Nothing is submitted automatically.
- A helper or release version mismatch alone is informational. Authenticated proxy support is required. Optional commands depend on advertised helper capabilities.
- The last selected exit node is restored after reconnect.
- Toasts in the popup cover file send, errors, and suggestions.
- Arrow keys navigate the peer list.
- The UI adjusts hints on macOS.
- Open as side panel switches the UI from popup to Chrome side panel or Firefox sidebar. One quick-settings row controls it on Chrome and Firefox.
- Auto-connect on start (quick settings) brings the tailnet up on the first status after init when the backend is
StoppedorNoState. A session-scoped flag preserves an explicit disconnect across service-worker restarts in the same browser session. The background listens forruntime.onStartupso launch does not wait for the popup to open. Init includes a session-scopedwantRunninghint (launch preference or last explicit toggle) so the host can keep the node down when auto-connect is off, despite tsnet defaulting to up on start. If the node still comes up (helper without the field, or a failed prefs edit), the background sendsdownonce per host connection and does not override a newer user action. Switching or creating a profile clears recorded run intent; the new profile's saved prefs decide run state.
This section lists current behavior only. Missing or partial features versus the native Tailscale client, plus architectural limits, are documented in FEATURE_PARITY.md. Maintain parity claims there; update this link if that file moves or is renamed.
Communication uses the Chrome native messaging wire format: a 4-byte little-endian length prefix followed by a JSON payload. Maximum message size is 1 MB (Chrome-enforced limit).
| Command | Fields | Description |
|---|---|---|
init |
initID: string, wantRunning?: boolean |
Initialize tsnet.Server for browser profile UUID; optional hint for whether the node should run after startup |
login |
-- | Request a fresh Tailscale login URL |
login-auth-key |
authKey: string |
Register the logged-out profile with an auth key |
up |
-- | Set WantRunning=true |
down |
-- | Set WantRunning=false |
get-status |
-- | Request full status update |
ping |
-- | Keepalive; host replies with pong |
set-exit-node |
nodeID: string |
Set exit node (empty string to clear) |
set-prefs |
prefs: Partial<PrefsView> |
Apply partial preference changes |
list-profiles |
-- | List all Tailscale profiles |
switch-profile |
profileID: string |
Switch to a different profile |
new-profile |
-- | Create and switch to a new empty profile |
delete-profile |
profileID: string |
Delete a profile |
send-file |
nodeID, fileName, fileData (base64), fileSize, transferID?, chunkIndex?, chunkCount? |
Send file via Taildrop (supports chunked transfer) |
suggest-exit-node |
-- | Request optimized exit node suggestion |
ping-peer |
nodeID: string |
Ping a specific peer (diagnostic) |
bug-report |
note?: string |
Generate bug report |
netcheck |
-- | Return the helper's current netcheck availability diagnostic |
logout |
-- | Log out of current Tailscale account |
| Reply Field | When Sent | Payload |
|---|---|---|
procRunning |
Immediately on host startup | { port, pid, version, proxyAuth, supportsNetcheck?, supportsPingPeer?, supportsLogin?, supportsCustomControlURL?, supportsAuthKeyLogin?, error? } |
init |
After init command |
{ error? } |
pong |
After ping |
{} |
status |
After state changes or get-status |
Full StatusUpdate object |
profiles |
After profile commands | { current, profiles[] } |
exitNodeSuggestion |
After suggest-exit-node |
{ id, hostname, location? } |
fileSendProgress |
During file send | { targetNodeID, name, percent, done, error? } |
diagnostic |
After ping-peer, netcheck, or bug-report |
{ title, body } |
error |
On command failure | { cmd, message } |
bug-report is accepted by the Go host protocol. The current TypeScript
NativeRequest union and extension do not send it.
interface StatusUpdate {
backendState: "NoState" | "NeedsMachineAuth" | "NeedsLogin" |
"InUseOtherUser" | "Stopped" | "Starting" | "Running";
running: boolean;
tailnet: string | null;
magicDNSSuffix: string;
splitDNSDomains?: string[]; // Restricted suffixes; absent on older helpers
dnsRoutes?: string[]; // Authoritative restricted routes; absent when unknown
selfNode: SelfNode | null;
needsLogin: boolean;
browseToURL: string; // Login URL from control plane
authURL?: string; // Alternate login URL surfaced by the host
exitNode: ExitNodeInfo | null;
peers: PeerInfo[];
peersTruncated?: boolean; // True if the 1 MiB reply cap omitted peers
totalPeers?: number; // Full count before truncation
prefs: TailscalePrefs | null;
health: string[];
error: string | null;
}When NeedsLogin is active, the extension opens a validated browseToURL immediately when available. If the URL is missing and the helper advertises supportsLogin, the extension sends login, waits for a fresh browseToURL or authURL, validates the URL, and then opens it.
If the helper advertises supportsAuthKeyLogin, the login view also offers "Use an auth key". The extension sends login-auth-key with the key, and the helper passes it to the backend for the current profile only, then registers without a browser URL. The key is never written to storage, prefs, or logs. If the coordination server rejects the key, the helper replies with a login-auth-key error that omits the key and drops it from the backend so it is not retried. Key sign-in does not need protected browsing to be released, because the helper reaches the coordination server directly.
set-prefs.prefs.controlURL uses an empty string for Tailscale's default control plane and an HTTP(S) URL for a custom server. The helper validates the URL and preferences before switching to an empty local profile. The new profile clears server-scoped exit-node state and requires a fresh login. The previous account remains in Profiles, and failures attempt to restore its identity and preferences. Switching does not require remote logout. Settings for the pending login survive a helper restart.
If a status payload would exceed the browser's 1 MiB native-message limit, the helper removes peers from the end until it fits and sets peersTruncated plus totalPeers. The popup displays a health warning instead of silently losing all status updates on very large tailnets.
Each PeerInfo includes: id, hostname, dnsName, tailscaleIPs[], os, online, active, exitNode, exitNodeOption, isSubnetRouter, subnets[], tags[], rxBytes, txBytes, lastSeen, lastHandshake, keyExpiry, location?, taildropTarget, sshHost, userId, userName, userLoginName, userProfilePicURL.
The extension is a pnpm monorepo with two packages:
| Package | Path | Purpose |
|---|---|---|
@tailchrome/extension |
packages/extension/ |
WXT app for Chrome/Firefox packaging, browser-specific proxy managers, entrypoints |
@tailchrome/shared |
packages/shared/ |
Shared TypeScript: types, state management, popup logic, background core, proxy utils |
The shared package contains all the platform-agnostic logic. The extension package contains browser-specific entrypoints, proxy managers, and WXT configuration.
**packages/shared/src/background/**
| File | Purpose |
|---|---|
background.ts |
Core service worker: native host management, popup communication, state subscriptions, context menus, diagnostics, and keepalive |
native-host.ts |
Serialized native-host connection lifecycle, typed connection events, evidence-based disconnect classification, and exponential reconnect backoff |
state-store.ts |
StateStore with no-op deduplication, subscriptions, and native status mapping |
../helper-diagnostics.ts |
Pure diagnostic sanitizer, allowlist, bounds, and local report formatter |
badge-manager.ts |
Extension icon/badge updates for online, offline, warning, and exit-node states |
proxy-utils.ts |
IPv4/CIDR helpers, MagicDNS/split-domain sanitization, subnet collection, and proxy decisions |
ipv6-subnets.ts |
IPv6 literal/CIDR validation and a shared subnet matcher for Firefox and generated Chrome PAC scripts |
routing-protection.ts |
Persisted, account-scoped routing policy and fail-closed behavior across helper or worker restarts |
proxy-session.ts |
In-memory helper proxy credentials and authenticated session handoff to browser-specific managers |
domain-split.ts |
Split-tunneling config storage and normalization |
auto-connect.ts |
Auto-connect preference, per-session handled flag, and session connection intent (wantRunning init hint) |
timer-service.ts |
Browser-neutral timer interface and native-timer implementation |
chrome-alarm-timer-service.ts |
Chrome alarm-backed one-shot timers that survive MV3 worker suspension |
startup-wake.ts |
Synchronous browser-start wake listener registration |
ui-surface.ts |
Popup/side-panel preference storage and browser-specific toolbar behavior |
**packages/shared/src/popup/**
| File | Purpose |
|---|---|
popup.ts |
Custom-URL hydration, background connection, view routing, and live/deferred sub-view state |
helper-diagnostics.ts |
On-demand copy/download UI for the shared local helper report |
utils.ts |
Clipboard, toast notifications, keyboard navigation, formatting, and platform detection |
custom-urls.ts |
Per-device custom port/URL storage using chrome.storage.local |
peer-filters.ts |
Device-list filtering rules |
icons.ts |
SVG icon definitions |
**packages/shared/src/popup/views/**
| File | Purpose |
|---|---|
connected.ts |
Main connected view: identity, quick/advanced settings, split tunneling, peer search/list, and footer |
exit-nodes.ts |
Exit-node picker: local recommendation, search, grouping, flags, and live updates |
profiles.ts |
Profile switcher: create, switch, and delete actions |
disconnected.ts |
Starting, reconnecting, stopped, and helper-error recovery states |
needs-login.ts |
Login prompt, auth key sign-in, and coordination-server settings |
needs-install.ts |
Package installation and registration-repair entry point |
install-helpers.ts |
Runtime platform/architecture selection, per-user setup, terminal commands, and registration recovery |
**packages/shared/src/popup/components/**
| File | Purpose |
|---|---|
peer-list.ts |
Peer list with online/offline grouping and incremental DOM updates |
peer-item.ts |
Peer row: live details, copy/open/ping/SSH/Taildrop actions, and custom URL editor |
coordination-server-row.ts |
Reusable custom control-server editor with capability gating |
ui-surface-row.ts |
Popup versus side-panel/sidebar setting |
header.ts |
Logo and accessible connection toggle |
health-warnings.ts |
Collapsible health warning banner |
toggle-switch.ts |
Reusable accessible toggle component |
**packages/extension/src/background/**
| File | Purpose |
|---|---|
chrome.ts |
Chrome background bootstrap, durable reconnect timer, and proxy-auth wiring |
chrome-proxy-manager.ts |
Mandatory PAC generation, ownership verification, and fail-closed routing |
chrome-proxy-auth.ts |
Per-helper HTTP proxy credentials and Chrome authentication callbacks |
firefox.ts |
Firefox background bootstrap and alarm-based keepalive |
firefox-proxy-manager.ts |
proxy.onRequest listener with authenticated, fail-closed SOCKS routing |
**packages/extension/entrypoints/**
| File | Purpose |
|---|---|
background.ts |
Routes to Chrome or Firefox background initialization |
popup/main.ts |
Popup entry; imports shared popup module |
popup/index.html |
Popup HTML shell |
popup/style.css |
Popup styles |
Defined in packages/shared/src/constants.ts:
| Constant | Value | Purpose |
|---|---|---|
TAILSCALE_SERVICE_IP |
100.100.100.100 |
Tailscale service/web client address |
TAILSCALE_IPV6_PREFIX |
fd7a:115c:a1e0: |
Tailscale node IPv6 routing prefix |
KEEPALIVE_INTERVAL_MS |
25000 |
Ping interval to keep service worker alive |
RECONNECT_BASE_MS |
1000 |
Reconnection backoff base |
RECONNECT_MAX_MS |
30000 |
Reconnection backoff ceiling |
ADMIN_URL |
https://login.tailscale.com/admin |
Tailscale admin console |
DEFAULT_CONTROL_URL |
https://controlplane.tailscale.com |
Default coordination server |
The native host is a Go binary at host/ using tailscale.com/tsnet pinned to v1.103.0-pre.0.20260819151608-90ed0bcf4bc2. This revision includes the UDP DNS routing fix and the security fixes from v1.102.3; see Split DNS.
| File | Purpose |
|---|---|
main.go |
Entry point, proxy startup, and native messaging mode |
cli.go |
Explicit install/uninstall/version command parsing and legacy setup compatibility |
host.go |
Framing loop, synchronized tsnet session lifecycle, request dispatch, prefs/login/diagnostic handlers, and bounded status replies |
authkey_login.go |
Auth key sign-in: key validation, redaction, rejection reporting, and discarding rejected keys |
protocol.go |
Wire protocol types and 1 MiB message limit |
status.go |
Retrying IPN bus watcher, debounced refresh, cached notification state, and StatusUpdate construction |
proxy.go / proxy_policy.go |
SOCKS5/HTTP multiplexing, authenticated destination policy, lazy quad-100 web client, and buffered CONNECT tunneling |
dns.go / exit_dns.go |
Restricted split-DNS forwarding and exit-node DNS behavior |
profiles.go |
Profile management through the current local-client snapshot |
saved_prefs.go |
Loads saved profile preferences before tsnet startup and persists settings for pending logins |
control_url.go |
Changes coordination servers using a fresh local profile, with rollback to the previous account |
taildrop.go |
Chunk reassembly, asynchronous cancellable PushFile, progress, and cleanup |
install.go / install_*.go |
Cross-platform native host installation and cleanup, including Chrome/Firefox Flatpak sandbox state and registration |
peers.go |
Peer/status conversion from Tailscale types |
exitnode.go |
Exit-node selection and suggestion handlers |
*_test.go |
Framing, proxy, peer conversion, status/prefs, Taildrop, installer, and platform-specific regression coverage |
- Browser launches the host via native messaging (stdin/stdout). Not a terminal -- goes directly to messaging mode.
- Proxy starts on
127.0.0.1:0. The port is sent back to the extension viaprocRunning. - Extension sends
initwith a profile identifier restricted to 1-64 ASCII letters, numbers, underscores, or hyphens. Host creates atsnet.Serverat~/.config/tailscale-browser-ext/<ID>/and atomically installs it as the current session. - IPN bus watcher monitors state, prefs, netmap, browse-to-URL, and health changes. Errors trigger bounded exponential retries; each change schedules a debounced full
StatusUpdatefrom the same session snapshot. - Host reads commands in a loop from stdin, dispatches to handlers, and writes replies to stdout.
- On stdin EOF (browser closed), the host cancels the watcher and active Taildrop transfers, closes the tsnet server, and exits cleanly.
Before starting tsnet, the host reads the selected account's saved preferences and supplies its coordination server, hostname, and advertised tags. It restores subnet-route acceptance, DNS, Shields Up, LAN access, SSH, and advertised routes before publishing the session to the proxy and status watcher. New browser profiles accept subnet routes by default. The extension supplies the startup connection intent and restores its selected exit node after the account is running. An unreadable preference record stops initialization instead of replacing the saved settings with defaults.
The proxy uses Tailscale's proxymux.SplitSOCKSAndHTTP() to multiplex a single listener:
- SOCKS5 traffic is handled by
tailscale.com/net/socks5, with authentication and the helper's destination policy applied before dialing. - HTTP traffic is handled by an
httputil.ReverseProxywith the same authentication and destination checks. - Requests to
100.100.100.100are routed to the Tailscale web client (web.ServerinManageServerMode). Proxy authentication is checked first; the web client then enforces its own session, capability and CSRF checks. - HTTPS CONNECT requests are hijacked for bidirectional tunneling through tsnet.
All three proxy paths resolve restricted DNS domains through configured IP nameservers, validating both the nameserver route and returned IPs against the current session's routing policy before dialing. The IPN watcher sends authoritative restricted domains as dnsRoutes, retaining splitDNSDomains for compatibility; disabling corpDNS or removing a route clears the corresponding browser routing. An omitted dnsRoutes field indicates that configuration is not yet known and preserves existing protection. See Split DNS for setup and nameserver routing requirements.
The loopback proxy requires a fresh random credential on every helper launch. Chrome uses authenticated HTTP proxying; Firefox uses authenticated SOCKS5. Credentials stay in the background proxy manager and are excluded from popup state, storage, and diagnostics. The helper also validates destinations against its current network map and preferences before dialing. See SECURITY.md.
Running the raw host without a command in a terminal retains legacy setup: it copies itself to the historical per-user helper directory and registers all supported browsers. New installers place the executable at their stable path and invoke install --binary-path PATH. This direct command registers Chrome, Firefox, and detected optional browsers without making another executable copy. See helper installation for explicit browser selection and legacy compatibility.
Known peer short names, full MagicDNS names, and restricted DNS domains use the helper. Split DNS follows the most specific domain route from Tailscale or Headscale and supports IPv4/IPv6 nameserver addresses over authorized routes, including TCP-only and UDP-only nameservers. Encrypted resolver URLs are not supported. Routes without a supported IP nameserver fail instead of falling back to system DNS.
Ordinary browsing keeps the browser/system resolver. Proxied exit-node traffic uses the exit node's DNS unless a restricted resolver is configured to stay in use with that exit node. Excluded domains keep their normal resolver. Restricted DNS routes require the MagicDNS setting to be enabled.
Chrome uses a dynamically generated PAC (Proxy Auto-Config) script set via chrome.proxy.settings.set(). The PAC script routes traffic based on:
- Tailnet destinations -> proxy: the service IP (
100.100.100.100), full MagicDNS names, exact known peer short names, restricted DNS domains, CGNAT addresses (100.64.0.0/10), Tailscale IPv6 addresses (fd7a:115c:a1e0::/48), and approved IPv4/IPv6 subnet addresses. Domain rules match both the domain and its subdomains.isInNet()is used only for IPv4 literals; IPv6 uses a shared numeric prefix matcher. Neither subnet matcher resolves hostnames through local DNS. - Other traffic with a selected exit node -> proxy subject to the user's Bypass or Only domain rules; protected requests are blocked while the exit node or helper is unavailable.
- Otherwise ->
DIRECT.
The Chrome PAC target is PROXY 127.0.0.1:<port>, with HTTP proxy authentication supplied by the background handler.
Chrome restricts which requests extension handlers can observe,
including requests initiated by other extensions. Before enabling protected
routes for a new helper session, Tailchrome makes its own authenticated HEAD
request to http://tailchrome-proxy-auth.invalid/ through the helper. This
populates Chrome's proxy credential cache for subsequent HTTPS CONNECT requests,
including other extensions' API calls. During this exchange, only the probe
reaches the helper; other protected destinations remain blocked. A failed or
timed-out probe leaves them blocked. The probe endpoint requires the same
credential and returns an empty, uncached response without contacting tsnet.
Older authenticated helpers can return a destination error after authenticating;
that also populates the cache. Credentials remain in background memory and
Chrome's auth cache, and are replaced when the helper session changes.
This credential is generated by Tailchrome for each helper process. It is
separate from Tailscale login, same-user proof tokens, and RunWebClient;
changing that preference does not disable proxy authentication. Users should
not enter their Tailscale password in a proxy authentication dialog. An
individual tunnel failure does not by itself establish that the proxy settings
or all protected browsing have failed.
Successful PAC settings are reused until routing changes. Worker suspension preserves the browser settings; reconnecting replaces the helper endpoint after confirmation.
Firefox uses the browser.proxy.onRequest API with an event listener that evaluates each request URL:
- Same routing logic as Chrome (service IP, CGNAT, Tailscale IPv6, MagicDNS, peer short names, subnets, restricted DNS domains, exit node)
- Protected requests use an authenticated SOCKS proxy with
proxyDNS: truein a chain ending innull, preventing browser proxy fallback. Other requests use the normal browser connection. - IPv4 matching uses numeric comparison (
ipToNum()) instead of PAC'sisInNet(); IPv6 subnet matching uses the same implementation embedded in the Chrome PAC.
Routing protection: Both browsers retain a sanitized routing snapshot across restarts, including restricted DNS domains but excluding helper ports and credentials. Exit-node choices are scoped to the account and coordination server. Helper loss or an unavailable exit node blocks protected requests while preserving split-tunnel exceptions. Chrome uses mandatory PAC settings and checks effective proxy ownership.
Both browsers exclude new IPv4 and IPv6 subnet routes that overlap the helper's forbidden address ranges, including broad prefixes containing those ranges. Rejected routes do not divert otherwise direct traffic into the helper. IPv4 routes saved by older versions remain protected during outages and authentication setup, but rejected prefixes are excluded from active subnet routing; selected exit-node rules still apply.
The popup reports routing failures separately from the Tailscale connection. Choose Disconnect and browse normally to release protection when the helper cannot respond.
StateStore (packages/shared/src/background/state-store.ts) is a minimal Redux-like store:
interface TailscaleState {
routingPolicy?: RoutingPolicy; // Effective active/blocked/direct routing decision
routingHealth?: RoutingHealth; // Browser proxy ownership and availability
selectedExitNodeID?: string | null;
stateVersion: number; // Monotonically increasing counter
hostConnected: boolean;
initialized: boolean;
proxyPort: number | null;
proxyEnabled: boolean;
backendState: BackendState;
tailnet: string | null;
selfNode: SelfNode | null;
peers: PeerInfo[];
exitNode: ExitNodeInfo | null;
magicDNSSuffix: string | null;
splitDNSDomains: string[];
dnsRoutes?: string[];
browseToURL: string | null;
prefs: TailscalePrefs | null;
health: string[];
pendingExitNodeID: string | null; // Optimistic selection until host confirmation
currentProfile: ProfileInfo | null;
profiles: ProfileInfo[];
exitNodeSuggestion: ExitNodeSuggestion | null;
domainSplit: { mode: "bypass" | "only"; domains: string[] };
error: string | null;
hostVersion: string | null;
helperFailure: HelperFailure | null;
helperDiagnostic: HelperDiagnostic | null;
helperVersionNotice: HelperVersionNotice | null;
repairRegistrationAvailable: boolean;
supportsNetcheck: boolean;
supportsPingPeer: boolean;
supportsLogin: boolean;
supportsCustomControlURL: boolean;
supportsAuthKeyLogin: boolean;
reconnecting: boolean;
autoConnectOnStart: boolean;
}update(partial)shallow-compares supplied fields, then merges and incrementsstateVersiononly when something changedapplyStatusUpdate(status)maps aStatusUpdatefrom the host into state fieldssubscribe(callback)registers a listener called on every state change- Listeners receive the full state; ProxyManager, BadgeManager, and popup broadcast all subscribe
PopupMessage (background -> popup):
{ type: "state", state: TailscaleState }-- full state push{ type: "toast", message, level: "info"|"error", persistent? }-- notification
BackgroundMessage (popup -> background):
- Connection and recovery:
release-routing,toggle,login,disconnect-and-login,login-auth-key,logout, andretry-native-host - Routing and preferences:
set-exit-node,clear-exit-node,set-pref,set-advertise-routes,set-domain-split, andset-auto-connect-on-start - Profiles and diagnostics:
switch-profile,new-profile,delete-profile,ping-peer, andnetcheck - Files and navigation:
send-file,suggest-exit-node,open-admin, andopen-web-client
helperFailure is evidence-based and uses these stable categories:
| Failure kind | Evidence | Recovery surface |
|---|---|---|
helper-unavailable |
Browser reports that the native-messaging host is absent | Platform release package installation, followed by registration repair only after discovery retries fail |
helper-not-allowed |
Browser reports that the host exists but this extension is not allowed | Registration repair is promoted immediately |
helper-start-failed |
The browser found the host, but startup failed before a healthy connection | Retry, package repair, and local diagnostics |
helper-stopped |
A previously healthy helper connection closed | Automatic reconnect plus manual retry |
helper-reported-error |
The helper started and returned an explicit startup/protocol error | Retry, package repair, and local diagnostics |
helper-incompatible |
The helper omits a valid supported authenticated-proxy session (helper-proxy-auth-required) |
Update the helper and extension together; a version string alone never causes this state |
Starting a package or verified repair records a retry deadline in
chrome.storage.session. Attempts run after 2, 5, 10, 20, and 30 seconds and
are restored after a Manifest V3 worker restart. Successful initialization
clears the retry and repair state. If a package/fallback retry sequence ends
with helper-unavailable or helper-not-allowed,
repairRegistrationAvailable promotes current-user registration repair; a
manual retry or any other failure category does not.
helperVersionNotice compares the installed helper version with the extension
release only to show a dismissible notice. It never replaces the active popup
view. Optional commands such as login, custom coordination servers, netcheck,
and peer ping remain controlled by the capabilities advertised in
procRunning. Only an explicit future-protocol incompatibility blocks setup.
Helper diagnostic details are sanitized as they cross the native connection boundary. The report is created only when the user clicks copy or export. Its schema is versioned and capped at 8 KiB; it contains extension/helper/release versions, operating system, architecture, browser family, connection flags, failure kind/code, sanitized detail, advertised capabilities, and repair availability. It deliberately does not spread the full extension state into the report.
The popup is a vanilla TypeScript UI (no framework) rendered into the extension popup HTML. Views are functions that return DOM elements.
popup.ts routes to views based on TailscaleState:
| Condition | View |
|---|---|
helper-unavailable, helper-not-allowed, or helper-incompatible |
needs-install |
backendState === "NeedsLogin" |
needs-login |
backendState === "Running" |
connected |
| Startup failure, unexpected stop, helper-reported error, retry, or any other state | disconnected |
A helper version notice is inserted above whichever normal view is active; it does not participate in routing.
+----------------------------------+
| [Tailscale logo] [Toggle ON/OFF]|
+----------------------------------+
| Status: Connected to <tailnet> |
| IP: 100.x.y.z |
+----------------------------------+
| [Health warning banner] |
+----------------------------------+
| Exit Node: [current / None] >|
| Split tunneling: [mode] >|
| Shields Up [toggle] |
| MagicDNS [toggle] |
| Auto-connect on start [toggle] |
| Advanced [toggle] |
| Run as Exit Node [toggle] |
| Local node page: Open >|
| Coordination server >|
| Advertise subnets [toggle] |
| Profile: [name] (optional) > |
| Open as side panel [toggle] |
+----------------------------------+
| [Search devices…] (6+ peers) |
+----------------------------------+
| ONLINE (3) |
| > laptop 100.10.1.1 linux |
| > server 100.10.1.2 linux |
| > phone 100.10.1.3 android |
| OFFLINE (1) |
| > desktop 100.10.1.4 windows |
+----------------------------------+
| Native helper <version> |
| [Admin Console] [Logout] |
| [Star the repo!] |
+----------------------------------+
Exit node sub-view: Opening Exit node shows the full picker (search,
suggested node, Mullvad grouping where applicable). Allow LAN access is a
checkbox there—not in Quick Settings. Advertise subnets expands its own
editor, independently of Advanced. Each peer item expands to show Copy IP,
Copy DNS, Open, SSH (if capable), Send File (if a Taildrop target), and a custom
URL editor. A Profile row is added when state.profiles is non-empty and
opens the profile switcher. Admin Console appears only for Tailscale's
default coordination server, and the helper-version footer row appears only
after the host reports a version.
The device list previews five devices, with online devices first. View all and Show fewer expand or collapse it; search always includes the full list. Click an IP address to copy it without opening the device's actions. Search is offered for six or more devices, excluding Mullvad exit infrastructure.
The status bar distinguishes confirmed browser routing from the node's connection. The profile switcher retains the confirmed Active profile while showing a pending switch, disables conflicting actions, and offers retry guidance if the helper fails or does not confirm within 20 seconds.
| Feature | Chrome | Firefox |
|---|---|---|
| Manifest version | V3 | V3 |
| Proxy mechanism | chrome.proxy.settings (PAC script) |
browser.proxy.onRequest (listener) |
| Background type | Service worker (persistent with keepalive) | Event page (suspended aggressively) |
| Keepalive | Native interval; one-shot reconnects also use a durable chrome.alarms backup |
browser.alarms every 25s |
| State persistence | Sanitized local routing snapshot, session intent, and alarm-backed reconnect | Same routing snapshot and session intent; proxy listener starts blocked on wake |
| Native host ID | com.tailscale.browserext.chrome |
com.tailscale.browserext.firefox |
| Permissions | proxy, storage, nativeMessaging, contextMenus, alarms, sidePanel |
Same except sidePanel |
| Min version | -- | Firefox 142+ |
| Distribution | Chrome Web Store | Firefox Add-ons (AMO) |
| Extension ID | bhfeceecialgilpedkoflminjgcjljll (CWS) |
tailchrome@tesseras.org (gecko) |
- Alarms keepalive: Firefox suspends event pages after ~30s of inactivity. A
browser.alarmsalarm fires every 25s to send a keepalive ping and prevent suspension. - Synchronous listener registration: Proxy, runtime connection, storage, install, context-menu, alarm, startup, and sidebar listeners are all registered during initial script evaluation. Storage restoration begins first but never delays event-listener registration.
- Proxy listener registration: The
proxy.onRequestlistener is registered at extension load and persists across suspensions. It starts in blocked mode, then follows the effective policy after the shared routing snapshot is restored and live helper state arrives. - Persisted protection:
routingProtectionV1stores a sanitized, account-scoped routing snapshot in local storage. It excludes helper ports and credentials; Firefox obtains fresh proxy credentials from the native connection before protected requests can use the helper. - Data collection disclosure: Firefox AMO requires explicit data collection permissions declared in the manifest via
gecko.data_collection_permissions.
Install the extension, register the native helper, then log in. Step-by-step commands, version pairing (v0.1.14+ authenticated proxy), repair, and Flatpak are documented in helper installation. The README lists quick install one-liners.
Chrome (and Chromium-family browsers using the same store listing):
- Install from the Chrome Web Store
- Complete per-user helper setup from the popup (macOS helper app, Windows MSI or architecture-aware PowerShell installer, or Linux terminal command). Assets come from GitHub Releases. Homebrew and system packages are optional (packaging docs).
- Log in to Tailscale
Firefox:
- Install from Firefox Add-ons or the matching GitHub Release
- Use the same helper setup flow as Chrome
- Log in to Tailscale
The v0.1.14 helper separates binary placement from browser registration.
tailchrome install registers the installed executable directly, prints paths,
and supports custom extension IDs and browser targets. Chrome and Firefox are
registered for first use; optional browsers use installation footprints unless
explicitly requested. Linux registration honors XDG configuration paths.
The Unix and PowerShell installers select a release and architecture, verify the artifact, replace the stable user-owned executable safely, and invoke this command. Latest stable is the general default; an explicit version remains available. macOS app, MSI, Homebrew and Linux system packages retain ownership of their own executable. Install and registration repair use the same entry point. Windows signature status follows the release's recorded signing mode; see the policy.
Legacy installer flags remain compatible and retain their historical staging
behavior. Existing native-host names and extension IDs are unchanged. The new
uninstall command removes registrations owned by its executable; the installer
or package manager removes the executable. Node state is preserved.
See helper installation for exact commands, executable paths, legacy behavior, safe upgrades, uninstall and Chrome/Firefox Flatpak setup. The matching release's installer assets must exist before distributing its extension.
Per-profile Tailscale state is stored at:
~/.config/tailscale-browser-ext/<browser-profile-UUID>/
Each browser profile generates a UUID on first connection, stored in chrome.storage.local as profileId.
Native installations keep this historical location even when browser manifest registration uses XDG paths. Chrome and Firefox Flatpak use their sandbox's writable XDG configuration directory for separate node state. Installing the sandbox helper does not migrate or delete native node identities.
tailchrome/
+-- packages/
| +-- extension/ # WXT app (browser-specific)
| | +-- entrypoints/
| | | +-- background.ts # Background entry (routes to chrome/firefox)
| | | +-- popup/ # Popup HTML, CSS, entry
| | +-- src/background/
| | | +-- chrome.ts # Chrome bootstrap and proxy-auth wiring
| | | +-- firefox.ts # Firefox bootstrap and keepalive
| | | +-- chrome-proxy-manager.ts
| | | +-- chrome-proxy-auth.ts
| | | +-- firefox-proxy-manager.ts
| | +-- config/
| | | +-- firefox-disclosure.ts # AMO data collection declaration
| | +-- public/ # Icons (online/offline/warning states)
| | +-- wxt.config.ts # WXT manifest & build config
| | +-- package.json
| |
| +-- shared/ # Platform-agnostic code
| +-- src/
| | +-- types.ts # All TypeScript type definitions
| | +-- constants.ts # Configuration constants
| | +-- helper-diagnostics.ts # Allowlisted local report formatter
| | +-- background/ # Service worker core logic
| | | +-- background.ts # Main background initialization
| | | +-- native-host.ts # Native host connection manager
| | | +-- state-store.ts # State management
| | | +-- badge-manager.ts # Icon/badge updates
| | | +-- proxy-utils.ts # IP/CIDR/DNS utilities
| | | +-- routing-protection.ts # Persisted fail-closed routing policy
| | | +-- proxy-session.ts # Authenticated helper proxy session
| | | +-- timer-service.ts # Timer abstraction
| | | +-- chrome-alarm-timer-service.ts # MV3 durable reconnect timeout
| | | +-- domain-split.ts # Split-tunneling persistence
| | | +-- auto-connect.ts # Startup connection preference
| | | +-- startup-wake.ts # Browser launch listener
| | | +-- ui-surface.ts # Popup/side-panel behavior
| | +-- popup/ # Popup UI views & components
| | | +-- popup.ts # View router
| | | +-- helper-diagnostics.ts # Copy/export actions
| | | +-- utils.ts
| | | +-- custom-urls.ts
| | | +-- icons.ts
| | | +-- views/
| | | | +-- connected.ts # Main connected view
| | | | +-- exit-nodes.ts # Exit node picker
| | | | +-- profiles.ts # Profile switcher
| | | | +-- disconnected.ts # Error recovery view
| | | | +-- needs-login.ts # Login view
| | | | +-- needs-install.ts # Install guide view
| | | | +-- install-helpers.ts
| | | +-- components/
| | | | +-- peer-list.ts
| | | | +-- peer-item.ts
| | | | +-- coordination-server-row.ts
| | | | +-- ui-surface-row.ts
| | | | +-- header.ts
| | | | +-- health-warnings.ts
| | | | +-- toggle-switch.ts
| | +-- __test__/ # Test fixtures and mocks
| +-- package.json
|
+-- host/ # Native messaging host (Go)
| +-- main.go # Entry point
| +-- cli.go # Explicit install/uninstall/version CLI
| +-- host.go # Host struct, message loop, handlers
| +-- protocol.go # Wire protocol types
| +-- status.go # IPN bus watcher
| +-- proxy.go # SOCKS5/HTTP proxy
| +-- proxy_policy.go # Authenticated destination policy
| +-- dns.go / exit_dns.go # Split and exit-node DNS forwarding
| +-- profiles.go # Profile management
| +-- taildrop.go # File transfer
| +-- install.go # Manifest installation
| +-- install_darwin.go # macOS paths
| +-- install_linux.go # Linux paths
| +-- install_flatpak_*.go # Chrome/Firefox Flatpak sandbox registration
| +-- install_windows.go # Windows paths + registry
| +-- peers.go # Peer info extraction
| +-- exitnode.go # Exit node handlers
| +-- *_test.go # Framing, proxy, status, peer, transfer, install tests
| +-- go.mod / go.sum
|
+-- config/
| +-- extension-ids.json # Extension & native host IDs
|
+-- packaging/ # Platform packages and native manifests
| +-- homebrew/ # Formula/cask maintenance docs
| +-- linux/ # nFPM DEB/RPM definition and builder
| +-- macos/ # PKG builder and per-user repair app
| +-- windows/ # WiX MSI and native ARM64 smoke
+-- Casks/tailchrome.rb # Published macOS Homebrew cask
+-- Formula/tailchrome.rb # Source-built macOS/Linux formula
|
+-- scripts/
| +-- e2e/ # Puppeteer runner, fixtures, native-host mock, scenarios
| +-- install.sh # Verified macOS/Linux per-user installer
| +-- install.ps1 # Verified Windows amd64/ARM64 per-user installer
| +-- install.test.sh # Hermetic installer tests
| +-- install.test.ps1 # Portable PowerShell installer fixtures
| +-- test-flatpak.sh # In-sandbox Chrome/Firefox native-messaging smoke
| +-- update-homebrew.mjs # Release-driven cask/formula updater
| +-- verify-windows-signatures.ps1 # Authenticode and embedded-EXE verifier
| +-- validate-extension-ids.mjs # Extension/native manifest drift check
| +-- validate-release-tag.mjs # Cross-file release version check
+-- store-assets/ # Store listing images
+-- docs/
| +-- privacy-policy.md
| +-- firefox-amo-launch.md
| +-- firefox-amo-review-notes.md
| +-- firefox-smoke-test.md
| +-- FEATURE_PARITY.md
| +-- STORE_LISTING.md
| +-- puppeteer-testing-suite.md
| +-- helper-installation.md
| +-- split-dns.md
| +-- DOCUMENTATION.md # This file
| +-- CONTRIBUTING.md
| +-- SOURCE_CODE_REVIEW.md # Firefox AMO reviewer guide
| +-- SECURITY.md
| +-- WINDOWS_CODE_SIGNING_POLICY.md
| +-- RELEASE_CHECKLIST.md
| +-- CODE_OF_CONDUCT.md
|
+-- .github/workflows/
| +-- ci.yml # PR checks
| +-- flatpak-smoke.yml # Chrome/Firefox Flatpak helper smoke on PRs
| +-- release.yml # Immutable tagged candidate builds
| +-- publish-helper-release.yml # Protected exact-candidate publication
| +-- publish.yml # Store submission
| +-- update-homebrew.yml # Post-release tap update proposal
|
+-- Makefile # Top-level build targets
+-- package.json # Root workspace scripts
+-- pnpm-workspace.yaml # Monorepo config
+-- tsconfig.base.json # Shared TS config
+-- README.md
+-- LICENSE # MIT
- Go 1.26.6+ (per
host/go.mod) - Node.js 22+
- pnpm (via corepack)
- Desktop Chrome or Firefox for testing
| Command | Description |
|---|---|
pnpm install --frozen-lockfile |
Install JS dependencies |
pnpm build:chrome |
Build Chrome extension via WXT |
pnpm build:firefox |
Build Firefox extension via WXT |
pnpm zip:chrome |
Create chrome.zip for distribution |
pnpm zip:firefox |
Create firefox.zip + firefox-sources.zip |
pnpm lint:firefox |
Validate Firefox extension with web-ext lint |
pnpm review:firefox |
Full Firefox review gate (build + lint + zip + publish validation) |
pnpm typecheck |
Run TypeScript type checking |
pnpm test |
Run all tests (vitest) |
pnpm test:installer |
Run hermetic verified-installer shell tests |
pnpm test:homebrew |
Run Homebrew release-updater tests |
pnpm validate:ids |
Validate extension ID consistency |
pnpm validate:release-tag <tag> |
Validate release tag format |
make host |
Build native host for current platform |
make host-all |
Build host binaries for all platforms |
make host-linux-amd64 |
Build the Linux package input |
make host-linux-arm64 |
Build the Linux ARM64 raw helper |
make host-windows-amd64 |
Build the Windows amd64 raw helper |
make host-windows-arm64 |
Build the Windows ARM64 raw helper |
make macos-pkg |
Build the macOS system package and per-user app (macOS only) |
make windows-msi |
Build an unsigned development MSI (Windows with WiX only) |
make linux-packages |
Build the Linux DEB and RPM packages with nFPM |
make dev |
Chrome watch mode via WXT |
make all |
Build extension + host |
make clean |
Clean all build outputs |
| Output | Location |
|---|---|
| Chrome extension | packages/extension/.output/chrome-mv3/ |
Chrome extension (dev, make dev) |
packages/extension/.output/chrome-mv3-dev/ |
| Firefox extension | packages/extension/.output/firefox-mv3/ |
| Chrome ZIP | packages/extension/.output/chrome.zip |
| Firefox ZIP | packages/extension/.output/firefox.zip |
| Firefox sources ZIP | packages/extension/.output/firefox-sources.zip |
| Host binary | dist/tailscale-browser-ext |
| Host cross-compile | dist/tailscale-browser-ext-{os}-{arch} |
WXT (packages/extension/wxt.config.ts) handles:
- Manifest V3 generation for Chrome and Firefox
- Icon definitions (online, offline, warning states at 16/32/48/128px)
- Chrome extension key for stable development ID
- Firefox gecko settings (addon ID,
strict_min_version: "142.0", data collection permissions) - Source ZIP configuration for AMO review (allowlisted paths only)
- Vite alias
@tailchrome/shared->packages/shared/src
The workflow runs extension unit/type/ID checks, verified-installer tests, the Chrome browser smoke suite, extension builds, the Firefox build/lint/review gate, actionlint, and ShellCheck on every pull request. A SHA-pinned path filter enables host/packaging work only when relevant files change:
- host-build (Linux): dependency download,
go vet, race-enabled Go tests, and the native host build - host-windows-tests: Windows-specific Go tests and PowerShell installer fixtures
- windows-arm64-smoke: native ARM64 executable and installer checks
- homebrew (when tap/updater files change): formula source build, install, registration, test, and uninstall on Linux and macOS; macOS also validates the published signed cask
- package-linux: amd64/arm64 raw builds with architecture checks plus
.deband.rpmgeneration with pinned nFPM and ownership-boundary inspection - macos-package-smoke: unsigned package smoke build that asserts the launchable
/Applications/Tailchrome Helper.apppayload - windows-signature-verifier: fixed-SDK positive/negative Authenticode verifier fixtures
- workflow-static-validation: actionlint over every workflow and ShellCheck over installer and packaging scripts
This separate workflow creates clean user-scoped Chrome and Firefox Flatpak installations, installs the helper into each sandbox, verifies native-message framing from inside the sandbox, uninstalls it, and retains diagnostics even on failure.
The candidate workflow resolves the exact tagged source commit and uses that immutable SHA in every downstream checkout. It:
- Validates extension IDs, the release tag, and the tag-to-source relationship
- Builds
chrome.zip,firefox.zip,firefox-sources.zip - Builds raw helpers for macOS, Linux, and Windows, each for amd64 and arm64
- Verifies Firefox source ZIP: extracts sources, rebuilds from scratch,
diff -qragainst original to ensure reproducibility - Signs/notarizes the macOS binaries, app, and package and verifies every layer
- Builds and inspects Linux
.deb/.rpmpackages and includes the Unix and PowerShell bootstraps - In signed mode, verifies both raw Windows EXEs, the outer x64 MSI, and its embedded amd64 EXE against the configured signing policy; explicit unsigned mode records its exception
- Requires native ARM64 runtime evidence and Defender evidence for both raw Windows EXEs and the MSI in both signing modes
- Assembles the complete allowlisted matrix, generates
SHA256SUMS.txtonly after final signing/packaging, creates build-provenance attestations, and stores the immutable candidate for 90 days
The candidate workflow has no release-write permission and never publishes assets. The currently documented external Windows signer selection and publisher subject are intentionally fail-closed; see WINDOWS_CODE_SIGNING_POLICY.md.
Publication accepts a candidate run ID, tag, and checksum-manifest digest. It
resolves and pins the source SHA from the validated tag and candidate run,
then verifies that the candidate came from this repository's candidate
workflow, succeeded for that immutable source, is still available, matches the
exact asset allowlist and checksums, and has valid signatures. It also
verifies the candidate attestations before the protected
windows-release-clearance environment approval.
After approval, publication is retry-safe: it creates or reuses a draft release, refuses conflicting existing bytes, uploads only missing identical assets without clobbering, re-verifies the complete draft, and publishes it explicitly. The reviewer-approved bytes and published bytes therefore share the same candidate manifest digest. Defender/Malwarebytes findings apply only to those exact hashes; an ordinary SmartScreen unknown-reputation warning is tracked separately from a malware or PUA detection. The complete operator procedure and asset matrix are in RELEASE_CHECKLIST.md.
Two jobs with environment-gated approvals:
- submit-chrome (environment:
chrome-web-store)
- Downloads
chrome.zipfrom GitHub Release - Verifies SHA256 checksum
- Submits via
pnpm wxt submit --chrome-zip
- submit-firefox (environment:
firefox-amo)
- Downloads
firefox.zip+firefox-sources.zip - Verifies checksums
- Validates Firefox publish gate
- Submits via
pnpm wxt submit --firefox-zip --firefox-sources-zip --firefox-channel listed - Supports
dry_runmode
After a stable helper release is published, this workflow verifies the release tag and checksum-manifest digest, computes the tagged source-archive checksum, updates the cask and source formula, reruns updater and Ruby syntax checks, and opens a reviewable pull request. It uploads the patch as a manual fallback if pull-request creation is unavailable.
Vitest with Chrome API mocks (packages/shared/src/__test__/chrome-mock.ts).
Background tests:
| Test File | Covers |
|---|---|
background.test.ts |
Service worker core: native message handling, popup communication, exit node restore, context menus, keepalive |
native-host.test.ts |
Connection lifecycle, reconnection with exponential backoff, error handling |
state-store.test.ts |
State management: update(), applyStatusUpdate(), subscribe(), version incrementing |
badge-manager.test.ts |
Icon/badge updates for all state combinations |
proxy-utils.test.ts |
IP conversion, CIDR parsing, MagicDNS sanitization, subnet collection |
routing-protection.test.ts |
Persisted routing snapshots, account scoping, fail-closed transitions, and explicit release |
proxy-session.test.ts |
Helper proxy credential lifecycle and session replacement |
auto-connect.test.ts |
Backend eligibility, local preference, session handled flag, and persisted connection intent |
timer-service.test.ts |
Timer abstraction contract |
chrome-alarm-timer-service.test.ts |
MV3 alarm-backed reconnect timeout and one-shot deduplication |
ui-surface.test.ts |
Side panel toggle plumbing: persistence, applyUiSurface, sidebar opener registration |
Proxy tests:
| Test File | Covers |
|---|---|
chrome-proxy-manager.test.ts |
PAC generation, mandatory blocked routing, ownership verification, and deduplication |
chrome-proxy-auth.test.ts |
Chrome HTTP proxy credential challenges and isolation |
chrome.test.ts |
Chrome bootstrap and PAC preservation across worker suspension |
firefox-proxy-manager.test.ts |
Authenticated/fail-closed SOCKS routing, DNS and split-tunnel decisions, direct mode, and no-fallback proxy chains |
firefox.test.ts |
Firefox-specific keepalive via alarms |
Popup tests:
| Test File | Covers |
|---|---|
popup.test.ts |
View routing for all state combinations |
peer-item.test.ts |
Peer component rendering and actions |
peer-filters.test.ts |
Peer search, online/offline grouping |
custom-urls.test.ts |
Custom URL storage |
utils.test.ts |
HTML escaping, clipboard, toast, platform detection, location helpers |
ui-surface-row.test.ts |
"Open as side panel" quick-settings row |
views/connected.test.ts |
Accessible quick-setting navigation and preservation of unsaved split rules |
views/disconnected.test.ts |
Reconnecting-state precedence |
views/exit-nodes.test.ts |
Exit node picker: search, Recommended row, Mullvad grouping, selection logic |
views/install-helpers.test.ts |
Platform/architecture asset selection, pinned installer commands, and retry/repair UI |
types.test.ts |
Shared type guards / fixture sanity |
Native host tests (Go):
| Test File | Covers |
|---|---|
protocol_test.go |
Invalid/oversized frame recovery, status truncation, and profile-ID validation |
proxy_test.go |
Quad-100 routing and buffered CONNECT bytes |
proxy_policy_test.go, proxy_integration_test.go |
Destination authorization, authenticated proxying, web client, and identity-transition gates |
dns*_test.go, exit_dns_test.go |
Restricted split DNS, subnet nameservers, exit DNS, cancellation, and fail-closed behavior |
peers_test.go |
Peer IP, route, identity, tag, key-expiry, and capability conversion |
status_test.go |
Status/prefs mapping and cached browse/login state |
taildrop_test.go |
Chunk assembly/progress, validation, cleanup, and active-transfer cancellation |
install_test.go, install_windows_test.go |
CLI parsing, manifest/registry installation, extension-ID formatting, and cleanup |
install_flatpak_test.go |
Chrome/Firefox Flatpak ownership, rollback, sandbox containment, locking, CLI flags, and cleanup |
control_url_test.go |
Control-server normalization and validation |
Installer and platform smoke tests:
| Test File | Covers |
|---|---|
scripts/install.test.sh |
Hermetic Unix installer downloads, verification, upgrade, rollback, and uninstall |
scripts/install.test.ps1 |
Portable Windows architecture selection, verification, replacement, rollback, and uninstall |
scripts/test-flatpak.sh |
Chrome or Firefox Flatpak sandbox installation, native procRunning/pong framing, and cleanup; it does not test the store extension, login, or browser routing |
scripts/update-homebrew.test.mjs |
Cask/formula version and checksum updates, validation, downgrade rejection, and idempotence |
pnpm test # Run all unit tests once
pnpm test:installer # Run the Unix verified-installer fixtures
pnpm test:homebrew # Run Homebrew updater tests
pnpm e2e:chrome # Puppeteer end-to-end suite (Chrome)
pnpm e2e:firefox # Puppeteer end-to-end suite (Firefox)
pnpm e2e:full # Full Puppeteer suite, both browsers
cd host && go test ./... # Native host Go testsThe Puppeteer harness lives in scripts/e2e/; see puppeteer-testing-suite.md for layout, fixtures, and the smoke vs. full suites.
{
"chromeExtensionId": "bhfeceecialgilpedkoflminjgcjljll",
"firefoxAddonId": "tailchrome@tesseras.org",
"chromeNativeHostId": "com.tailscale.browserext.chrome",
"firefoxNativeHostId": "com.tailscale.browserext.firefox"
}| Permission | Purpose |
|---|---|
proxy |
Configure browser proxy settings |
storage |
Persist profileId, exit node, custom URLs |
nativeMessaging |
Communicate with native host |
contextMenus |
Right-click "Send page URL" menu |
alarms |
Firefox keepalive and Chrome suspension-safe reconnect timeout |
sidePanel |
Chrome toolbar integration for the optional docked UI |
<all_urls> (host permission) |
Proxy interception for all URLs |
| Key | Storage | Purpose |
|---|---|---|
profileId |
chrome.storage.local |
Browser profile UUID for tsnet isolation |
customUrls |
chrome.storage.local |
Per-device custom open targets |
domainSplitConfig |
chrome.storage.local |
Split-tunneling mode (bypass/only) and domain list |
autoConnectOnStart |
chrome.storage.local |
Opt-in preference for auto-connecting the tailnet on browser start |
uiSurface |
chrome.storage.local |
Toolbar surface: popup or sidePanel/Firefox sidebar |
autoConnectHandled |
chrome.storage.session |
Per-session flag that prevents auto-connect from overriding an explicit manual disconnect |
desiredWantRunning |
chrome.storage.session |
Per-session connection intent sent as the wantRunning hint with host init |
lastSessionWantRunning |
chrome.storage.local |
Temporary fallback intent across extension reload/update; cleared at the next browser startup |
helperActivationRetry |
chrome.storage.session |
Source, retry index, and absolute helper-discovery deadline |
helperRegistrationRepairAvailable |
chrome.storage.session |
Whether package/fallback discovery exhausted and repair should be promoted |
routingProtectionV1 |
chrome.storage.local |
Sanitized account-scoped routing snapshots and transition state for fail-closed restoration; excludes helper ports and credentials |
For Tailscale's default control plane, login URLs from the native host (browseToURL or authURL) are validated against this allowlist before opening:
https://login.tailscale.comhttps://controlplane.tailscale.comhttps://tailscale.com
For a configured custom coordination server, delegated login URLs may use another origin. The URL must still be valid HTTP(S), and an HTTPS coordination server may only delegate to HTTPS. A stale default-Tailscale login URL is held briefly while the new server emits its current URL.
The extension does not infer protocol incompatibility from semantic versions. A version difference alone produces a dismissible notice. Optional features are enabled from the capabilities advertised by the connected helper.
Authenticated-proxy support is mandatory starting with v0.1.14. The helper must
provide a valid procRunning.proxyAuth session using the supported protocol
version and a valid proxy port. Missing or invalid session credentials produce
helper-incompatible with diagnostic code helper-proxy-auth-required, and the
extension does not enable that proxy.
Upgrade the helper and extension together from v0.1.13 or earlier. The older helper does not provide proxy credentials; the older extension uses unauthenticated SOCKS and cannot authenticate to the new helper. Consequently, neither mixed pair can provide normal protected browsing. Publish the matching helper assets before the store rollout, and complete both updates before resuming protected browsing. A version-only compatibility test must use a helper fixture that supplies the required authenticated session.
SHA256SUMS.txt covers every final release asset after signing,
notarization, and packaging. When GitHub CLI is available,
gh attestation verify <asset> --repo dantraynor/tailchrome verifies the
artifact's build provenance. On macOS, use pkgutil --check-signature for the
package and codesign --verify --deep --strict plus spctl for the embedded
app. On Windows, use Get-AuthenticodeSignature or SignTool; the release gate
additionally verifies both raw EXEs, the byte-identical amd64 MSI-embedded EXE,
and the outer MSI against one exact publisher subject and timestamp policy.
Signed Windows publication requires a configured signing provider and its exact publisher subject. Missing credentials, policy values, signatures, timestamps, nested identity, or security evidence fail the signed candidate. The documented unsigned mode must be selected explicitly; it never follows automatically from a signing failure. See WINDOWS_CODE_SIGNING_POLICY.md and SECURITY.md for verification and false-positive reporting.
- Only browser traffic is proxied -- system networking is never modified
- The proxy binds to
127.0.0.1only (not exposed to the network) - Suspending Chrome's MV3 worker does not clear Tailchrome's mandatory PAC.
Chrome removes its proxy setting only when Tailchrome's effective policy
becomes
direct, immediately for an explicit routing release or after a requested disconnect is confirmed. Firefox keeps itsproxy.onRequestlistener installed and returnsdirectin that mode - If an already protected route loses the helper, its authentication session, or its selected exit node, protected requests remain fail-closed (while split-tunnel exceptions remain direct) instead of falling through
- HTTP and SOCKS5 proxy connections require credentials generated for the helper process and delivered to the extension through native messaging
The Tailscale web client (100.100.100.100) checks its management session and
the viewer's capabilities independently of proxy authentication. Mutating web
requests retain Tailscale's same-origin checks using Sec-Fetch-Site or
Origin. The Sec-Tailscale: browser-ext header does not replace those checks.
Web logout and native account changes stop new web requests and drain active handlers before changing identity. An authorized web logout clears the old profile's cached state and web authorization at the LocalAPI boundary, before logout executes. The host serializes this operation with native commands and shutdown; a browser disconnect does not release the gate while a submitted mutation is still running.
Native messaging is restricted to the declared extension IDs in the native host manifest. The Chrome manifest uses allowed_origins, Firefox uses allowed_extensions.
| Data | Where | Purpose |
|---|---|---|
profileId |
Browser local storage | Per-profile Tailscale node isolation |
customUrls |
Browser local storage | Custom per-device URLs |
domainSplitConfig |
Browser local storage | Split-tunneling mode and domain list (entered by the user) |
autoConnectOnStart |
Browser local storage | "Auto-connect on start" preference (off by default) |
uiSurface |
Browser local storage | Popup versus side-panel/sidebar preference |
autoConnectHandled |
Browser session storage | Per-session flag to honor an explicit manual disconnect |
desiredWantRunning |
Browser session storage | Per-session helper startup intent |
lastSessionWantRunning |
Browser local storage | Temporary update/reload fallback for connection intent; cleared on browser startup |
helperActivationRetry |
Browser session storage | Pending package/fallback discovery retry deadline |
helperRegistrationRepairAvailable |
Browser session storage | Session-scoped registration-repair promotion |
routingProtectionV1 |
Browser local storage | Sanitized account-scoped routing snapshots and transition state; excludes helper ports and credentials |
~/.config/tailscale-browser-ext/<UUID>/ |
Filesystem | tsnet state directory (keys, config) |
When enabled, Tailchrome transmits:
- Browsing activity and website content needed for proxy/exit-node traffic
- Authentication data for login to Tailscale or the configured custom coordination server
- Device and network metadata for peer discovery
- User-initiated file contents for Taildrop transfers
Data is sent only to: the local native host, the user's tailnet and configured coordination plane (Tailscale by default), and sites the user accesses through Tailchrome.
Tailchrome does not include analytics, crash telemetry, advertising identifiers, or marketing data.
Helper activation diagnostics do not change that promise. A report is generated only after the user clicks Copy diagnostic report or Export diagnostic report and remains local until the user chooses to paste or share the copied/exported file. The allowlist excludes tailnet/account identity, profile and peer data, browsing history and URLs, login/authentication data, credentials, file-transfer content, Tailscale state directories, extension storage contents, filesystem user names, and registry values containing user data. Plain-text native errors are sanitized for home paths, URLs, hosts, email addresses, IP addresses, tokens/secrets, UUIDs, and registry paths before they can be retained in the bounded report.
Full policy: docs/privacy-policy.md
- Category: Productivity
- Short description: "Access your Tailscale tailnet directly from your browser. Per-profile VPN without touching system networking."
- Extension ID:
bhfeceecialgilpedkoflminjgcjljll
- Listing status: Published on Firefox Add-ons (AMO).
- Categories: Privacy & Security, Other
- Addon ID:
tailchrome@tesseras.org - Minimum Firefox version: 142.0
- Source code disclosure:
firefox-sources.zipincluded with each release for AMO reviewer verification
Full listing text: STORE_LISTING.md
- Fork the repo and clone locally
- Install dependencies: Go 1.26.6+, Node.js 22+, pnpm (via
corepack enable) pnpm install --frozen-lockfile- Build:
pnpm build:chrome,pnpm build:firefox,make host - Load extension in browser for testing:
- Chrome:
chrome://extensions-> Developer Mode -> Load unpackedpackages/extension/.output/chrome-mv3-dev/(withmake dev) orpackages/extension/.output/chrome-mv3/(afterpnpm build:chrome) - Firefox:
about:debugging#/runtime/this-firefox-> Load temporary addonpackages/extension/.output/firefox-mv3/manifest.json
- Install native host by running the built binary directly
- Open an issue first before submitting a PR
- Keep PRs focused -- one feature or fix per PR
- Write clear commit messages
- Test changes in both Chrome and Firefox
- Follow existing code patterns
Full guide: CONTRIBUTING.md
Key dependencies in host/go.mod:
| Dependency | Version | Purpose |
|---|---|---|
tailscale.com |
v1.103.0-pre.0.20260819151608-90ed0bcf4bc2 | tsnet, local client, IPN, socks5, proxymux, web client |
golang.org/x/term |
v0.45.0 | Terminal detection for auto-install |
golang.org/x/sys |
v0.47.0 | System calls |