Sandbox Browser

A censorship-resistant Chromium fork with embedded SOCKS5 proxy, Windows AppContainer sandbox, TLS fingerprint randomization, custom HTML/CSS parsers, Psiphon auto-launch and chaining, and VPN-style UI toggle.

GitHub • Issues

Alpha: Under active development. Release build only, Windows x64 only. Expect rough edges.

Sandbox Browser

Chromium browser with proxy chaining & sandbox controls

Check it out on Product Hunt →

Project Structure

browser/
├── patches/             # Chromium source patches
│   └── 0001-chromium-modified-files.patch  # All Chromium file modifications
├── src/                 # New source files (to be copied into Chromium)
│   ├── chrome/browser/sandbox_browser/     # Custom browser integration
│   ├── chrome/browser/ui/views/toolbar/    # VPN toggle button
│   ├── net/proxy/sandbox_proxy/            # SOCKS5 proxy implementation
│   ├── sandbox/policy/win/                 # AppContainer sandbox policy
│   └── third_party/custom_parsers/         # Custom HTML/CSS parsers
├── build/
│   └── setup_chromium.cmd    # Apply patches + copy files + download Psiphon
├── docs/                # Documentation
└── README.md

Setup

Prerequisites

1. Chromium source at C:\chromium\src (or set CHROMIUM_SRC env var)
2. depot_tools in PATH
3. Visual Studio 2022 Build Tools with Windows SDK

Quick Start

build\setup_chromium.cmd
set DEPOT_TOOLS_WIN_TOOLCHAIN=0
autoninja -C out/Default -j3 chrome

Manual Setup

set CHROMIUM_SRC=C:\path\to\chromium\src
cd %CHROMIUM_SRC%
git apply patches\0001-chromium-modified-files.patch
robocopy src\ %CHROMIUM_SRC% /E
gn gen out/Default --args="is_debug=false symbol_level=1"
set DEPOT_TOOLS_WIN_TOOLCHAIN=0
autoninja -C out/Default -j3 chrome

Running

The browser auto-configures itself. Just run:

chrome.exe --sandbox-tls-randomize --enable-logging --v=1

Automatic Psiphon Detection and Launch

The browser scans for a running Psiphon process on startup. If found, it chains through Psiphon's SOCKS5 tunnel automatically (your IP changes). If Psiphon is not running, the browser tries to launch it from:

1. PSIPHON_PATH environment variable
2. Same directory as chrome.exe (checks psiphon3_official.exe, psiphon3.exe, psiphon-tunnel-core.exe)

After launching Psiphon, the browser waits up to 60 seconds for the tunnel to establish. The embedded SOCKS5 proxy then chains through Psiphon.

rem Disable auto-launch:
chrome.exe --sandbox-tls-randomize --sandbox-no-psiphon-launch

Manual Psiphon (if auto-launch is off or fails)

rem Step 1: Download and start Psiphon from psiphon.ca
psiphon3.exe

rem Step 2: Launch browser (auto-detects Psiphon)
chrome.exe --sandbox-tls-randomize

Proxy Flags

Flag	Description
--sandbox-no-proxy	Disable embedded proxy entirely
--sandbox-no-psiphon-launch	Don't auto-launch Psiphon (detect running only)
--sandbox-psiphon-port=<port>	Explicit upstream port (skip detection)
--sandbox-parent-proxy-host=<host>	Manual upstream SOCKS5 host
--sandbox-parent-proxy-port=<port>	Manual upstream SOCKS5 port
--sandbox-parent-proxy-user=<user>	Upstream auth username
--sandbox-parent-proxy-pass=<pass>	Upstream auth password
--sandbox-tls-randomize	Enable TLS fingerprint randomization
--use-custom-parsers	Enable custom HTML/CSS post-parse validation
--no-sandbox	Run without AppContainer sandbox

Features

Feature	Activation	Description
SOCKS5 proxy	Auto	Embedded proxy on 127.0.0.1:1080 (or 1082+ if Psiphon active)
Psiphon auto-detect	Auto	Finds running Psiphon via TCP table + process enumeration
Psiphon auto-launch	Auto	Launches Psiphon if not running, waits up to 60s for tunnel
VPN toggle	Toolbar button	ON: chain through Psiphon, OFF: direct connect (no transition failures)
TLS randomization	--sandbox-tls-randomize	Randomizes cipher suites, groups, sigalgs, TLS version, extensions
AppContainer sandbox	Auto (omit --no-sandbox)	Custom "SandboxBrowser" container for renderer processes
Custom parsers	--use-custom-parsers	Post-parse HTML/CSS validation layer
Upstream chaining	--sandbox-parent-proxy-*	Manual chain through any SOCKS5 proxy

Chaining Architecture

VPN ON:  Chrome → embedded proxy (1082+) → Psiphon tunnel → Psiphon servers → internet
VPN OFF: Chrome → embedded proxy (1082+) → direct connect → internet

The embedded proxy starts on port 1082+ when upstream is detected on port 1080, or port 1080 in standalone mode. VPN toggle controls g_vpn_enabled checked per-connection.

Star History

Contributors Hall of Fame

Show some love and end up in the hall of fame. Contributors get free merch and special access to our community.

Build Notes

• Release build only (is_debug=false, symbol_level=1)
• Windows x64 only
• DEPOT_TOOLS_WIN_TOOLCHAIN=0 required (VS 2022 Build Tools at C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools)