Native proxy settings by tim2zg · Pull Request #2827 · element-hq/element-desktop

tim2zg · 2026-02-01T10:33:36Z

Description

This PR implements a native "Network Proxy" settings window, allowing users to configure their proxy connection directly within the application UI instead of relying on command-line arguments or environment variables.

Changes

Added a new Proxy Settings entry to the "View" menu.
Implemented a dedicated Electron window with a UI that matches the Element look and feel (including dark/light mode support).
Created a new module to handle applying proxy configurations to the Electron defaultSession.
Persisted proxy configuration using the existing Store.

Solution for Issue: #772

Checklist

Ensure your code works with manual testing.
New or updated public/exported symbols have accurate TSDoc documentation.
Linter and other CI checks pass.
I have licensed the changes to Element by completing the Contributor License Agreement (CLA)

Co-authored-by: tim2zg <59140326+tim2zg@users.noreply.github.com>

…-e9fc06269a7b Fix TypeScript error TS2345 in settings.ts: Add type assertion for desktopProxyConfig

Langugaes

- Added proxy authentication handling in the Electron main process. - Introduced `getLastAppliedConfig` function to retrieve the last applied proxy configuration. - Enhanced the proxy preload script to include a resize window feature. - Updated the proxy window HTML to improve UI with a modern design and better accessibility. - Implemented secure password storage for proxy credentials. - Refactored proxy configuration handling to ensure proper validation and error handling. - Improved the settings management for proxy configurations, including reading and writing to secure storage.

…elds and documentation

CLAassistant · 2026-02-01T10:33:43Z

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ tim2zg
❌ Copilot
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

dosubot · 2026-02-01T10:33:46Z

Related Documentation

No published documentation to review for changes on this repository.

Write your first living document

^{How did I do? Any feedback?}

t3chguy · 2026-02-02T10:07:34Z

src/proxy-preload.cts

Can this be cts instead and be transpiled by typescript into the lib dir instead of avoiding typescript? I.e follow the path of the main preload script

t3chguy

This is exciting, but a few points

Additionally, looks like the autoUpdater won't respect these proxy settings which is problematic without a warning to the user

t3chguy · 2026-02-02T10:07:53Z

src/proxy-window.html

@@ -0,0 +1,378 @@
+<!--
+Copyright 2026 New Vector Ltd.


We are not New Vector anymore, this should be your copyright anyway

t3chguy · 2026-02-02T10:07:59Z

src/proxy-window.ts

@@ -0,0 +1,96 @@
+/*
+Copyright 2026 New Vector Ltd.


t3chguy · 2026-02-02T10:08:05Z

src/proxy.ts

@@ -0,0 +1,154 @@
+/*
+Copyright 2026 New Vector Ltd.


t3chguy · 2026-02-02T10:08:57Z

src/proxy-window.html

I think this will want to use Compound components for UI, so may need more complexity and likely to be within the main UI rather than entirely standalone. Needs design

Will need help with this

t3chguy · 2026-02-02T10:10:35Z

src/proxy-window.html

+        <h1>Network Proxy</h1>
+
+        <div class="section">
+            <span class="section-title">Connection Mode</span>
+            <label class="radio-option"
+                ><input type="radio" name="mode" id="proxy-mode-system" value="system" checked /> Use system proxy
+                settings</label
+            >
+            <label class="radio-option"
+                ><input type="radio" name="mode" id="proxy-mode-direct" value="direct" /> No proxy (direct
+                connection)</label
+            >
+            <label class="radio-option"
+                ><input type="radio" name="mode" id="proxy-mode-custom" value="custom" /> Manual configuration</label
+            >
+        </div>


tried it but not sure if it's right

t3chguy · 2026-02-02T10:11:21Z

src/proxy-window.html

+                        <input id="proxy-password" type="password" autocomplete="off" />
+                    </div>
+                </div>
+                <div class="helper-text">Passwords are stored securely in the system keychain.</div>


I don't think this is true with safeStorage, a single random string is stored in system keychain and other secrets are encrypted symmetrically using it. Additionally the user may have no keychain where this message becauses confusing.

t3chguy · 2026-02-02T14:36:16Z

I have licensed the changes to Element by completing the Contributor License Agreement (CLA)

You checked this box but the CLA does not appear to be signed.

Could you also include screenshots of what the UI you added looks like?

…elds and documentation

…g/element-desktop into feat/native-proxy-settings

tim2zg · 2026-02-02T18:06:12Z

This is exciting, but a few points

Additionally, looks like the autoUpdater won't respect these proxy settings which is problematic without a warning to the user

Added a notice

tim2zg · 2026-02-02T18:13:20Z

I have licensed the changes to Element by completing the Contributor License Agreement (CLA)

You checked this box but the CLA does not appear to be signed.

Could you also include screenshots of what the UI you added looks like?

Also, the CLA is not okay because I tried using GitHub Copilot at the beginning and didn’t reset the history. GitHub now lists Copilot as a contributor.

americanrefugee · 2026-02-03T15:42:49Z

Hello, thanks for your contribution @tim2zg!

In order to integrate this feature into the product, the form you've proposed will need to be presented in a modal (rather than in a separate browser tab). Then there will be 2 places from which the user can access this modal: From the Welcome screen, and from Settings. Here are visuals to help illustrate:

On the Sign in page, we would add a text link in the footer

Click the link to launch the modal. By default the modal would show just the 3 radio button options with the first selected. The "Save" button is disabled until a change is made.

If the last option is selected, then the form appears below. The "Cancel" and "Save" buttons should be sticky and the form scrolls behind until the end. Once the user has entered the minimum information, the "Save" button is enabled.

3_Modal - Network proxy - Manual configuration selected

Once signed into the client, the user can go to Settings > Security & Privacy > Network proxy to manage this setting.

4_Settings_Security and Privacy_Network proxy

Ideally, please provide 1.) the modal and form contents and 2.) the settings section block.

As for UI components, use those provide by our Compound Design System at https://compound.element.io

Here's a quick cheat sheet:

tim2zg · 2026-02-05T16:50:37Z

Hey, thanks for the feedback. Would this then be added to the main element app repo or injected into it from the wrapper? And would I then need to open up a second pull request there?

Best regards

…component

t3chguy · 2026-02-06T09:16:14Z

Yes the UI code would live in element-web & communicate over IPC, there's already a wrapper for settings to handle the IPC communication for you. In the future it may be possible to have the UI code live on the element-desktop side and be injected as a module but we aren't there yet. In the near future element-desktop will be re-merged into the element-web (mono)repo to make contributions like this easier.

tim2zg and others added 9 commits September 23, 2025 21:37

added proxy support

9e246ab

Initial plan

170423d

Fix TypeScript error by adding type assertion to Store.get result

277d022

Co-authored-by: tim2zg <59140326+tim2zg@users.noreply.github.com>

Merge pull request #1 from tim2zg/copilot/fix-17239290-f811-4d26-aaa4…

36dae2d

…-e9fc06269a7b Fix TypeScript error TS2345 in settings.ts: Add type assertion for desktopProxyConfig

Merge pull request #2 from element-hq/develop

023c534

Langugaes

Merge branch 'element-hq:develop' into develop

4498694

feat: implement native proxy settings window

e3f2e73

feat(proxy): enhance proxy configuration interface with additional fi…

27ecd18

…elds and documentation

tim2zg requested a review from a team as a code owner February 1, 2026 10:33

tim2zg requested review from MidhunSureshR and t3chguy February 1, 2026 10:33

github-actions bot added the Z-Community-PR Issue is solved by a community member's PR label Feb 1, 2026

dosubot bot added the T-Enhancement label Feb 1, 2026

t3chguy reviewed Feb 2, 2026

View reviewed changes

t3chguy requested changes Feb 2, 2026

View reviewed changes

t3chguy changed the title ~~Feat/native proxy settings~~ Native proxy settings Feb 2, 2026

tim2zg added 7 commits February 2, 2026 17:51

feat(proxy): enhance proxy configuration interface with additional fi…

40f87f3

…elds and documentation

Merge branch 'feat/native-proxy-settings' of https://github.com/tim2z…

6d3d6b5

…g/element-desktop into feat/native-proxy-settings

Merge branch 'feat/native-proxy-settings' of https://github.com/tim2z…

c701014

…g/element-desktop into feat/native-proxy-settings

Merge branch 'feat/native-proxy-settings' of https://github.com/tim2z…

2d7bd30

…g/element-desktop into feat/native-proxy-settings

Merge branch 'feat/native-proxy-settings' of https://github.com/tim2z…

ec6b3c7

…g/element-desktop into feat/native-proxy-settings

feat(proxy): remove unused proxy preload resource from copy script

80f721c

Merge branch 'feat/native-proxy-settings' of https://github.com/tim2z…

31b8770

…g/element-desktop into feat/native-proxy-settings

t3chguy requested a review from a team February 2, 2026 18:27

feat(proxy): remove proxy window resources and add NetworkProxyModal …

e630f29

…component

Conversation

tim2zg commented Feb 1, 2026

Description

Changes

Checklist

Uh oh!

CLAassistant commented Feb 1, 2026

Uh oh!

dosubot bot commented Feb 1, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

t3chguy left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

t3chguy commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tim2zg commented Feb 2, 2026

Uh oh!

tim2zg commented Feb 2, 2026

Uh oh!

americanrefugee commented Feb 3, 2026

Uh oh!

tim2zg commented Feb 5, 2026

Uh oh!

t3chguy commented Feb 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

t3chguy commented Feb 2, 2026 •

edited

Loading