Installation & activation

Install BlankTrail Proxy on Windows, Linux or macOS, trust its root certificate and activate your licence. The whole thing takes a few minutes.

Windows

Download the installer (.exe) from your account at blanktrail.com.
Run it and choose your language (English, Russian or Chinese).
Read the installation notice, then complete the wizard. Optionally enable a desktop icon and "start on sign-in".
When prompted by Windows, approve installing the root certificate — this lets the proxy serve HTTPS without certificate warnings.
The app launches automatically and its icon appears in the system tray.

Where the app lands depends on the choice you make at the very start of the wizard. An install for all users goes to C:\Program Files\BlankTrail Proxy; an install for me only goes to %LOCALAPPDATA%\Programs\BlankTrail Proxy. The wizard asks for no administrator rights by default, so a standard account gets the SECOND path — if the product is not under Program Files, look there. Either way it adds two Start-menu shortcuts: one launches the tray app, the other opens the dashboard in your browser.

Updating or reinstalling

If a previous version is present, the installer offers three choices:

Update — keep license, settings and password. Only the program files are replaced.
Reinstall from scratch — reset to a fresh state. Optionally keep the license and root certificate.
Remove — uninstall BlankTrail Proxy from this computer.

NoteBecause BlankTrail Proxy intercepts TLS with its own certificate, some antivirus tools may flag it. If yours conflicts with the app, add BlankTrail Proxy to its exclusions.

Where the state and the log live

The state — the profile database, the root certificate, the license keys, the cache and the logs — lives in the data directory next to the application's executable. If that directory is not writable (an install into Program Files without rights, or a folder an antivirus watches), the application moves to %LOCALAPPDATA%\BlankTrail — so there are TWO possible places, and both are worth checking.

data\proxy.log — the application log; at 50 MB the old part moves to proxy.log.1.
data\profiles.db — the profile database; data\ca.crt and data\ca.key — the root certificate and its key.
data\license.key, data\license.secret and data\device_id — the license and the device identity. Move an installation to another machine TOGETHER with them, or it counts as a new device and takes a second seat.
data\traffic_port_<port>.jsonl — the ports' request logs, if they were ever switched on.

This is also the answer to “what to keep before reinstalling”: the whole data directory. On Linux the same state lives in /var/lib/blanktrail, and the log is available through journalctl -u blanktrail -f.

Linux

The quickest way is the personalized one-line installer shown on the Downloads page of your account — it fetches the right package for your architecture, installs OpenVPN, and activates your license automatically.

To install a package by hand, download the .deb for your architecture and install it:

sudo dpkg -i blanktrail_1.3.1_amd64.deb
sudo systemctl enable --now blanktrail

The service runs as a dedicated system user. Its configuration lives at /etc/blanktrail/config.yaml and its state (license, certificate, database) under /var/lib/blanktrail.

Managing the service

sudo systemctl status blanktrail     # check status
sudo systemctl restart blanktrail    # restart
sudo journalctl -u blanktrail -f     # follow logs

The dashboard is served on port 8891. On a server, reach it over an SSH tunnel or a private network — for example: ssh -L 8891:127.0.0.1:8891 user@host, then open http://127.0.0.1:8891 locally.

TipPrefer a tarball? Extract the .tar.gz for your architecture and run the bundled install script as root.

macOS

An archive is published for macOS for both architectures — Intel and Apple Silicon. Unpack the .tar.gz from the downloads page and run the bundled install script; the application runs as a background service and the dashboard opens at the same 127.0.0.1:8891.

NoteThere is no menu-bar icon on macOS — everything is done from the dashboard, as on Linux.

Docker

The image is built from the release artifact and published under the same version number as the client: blanktrail/blanktrail-proxy, for linux/amd64 and linux/arm64. Inside is the same proxy and the same dashboard as in a desktop install.

The ready run command — with the proxy password, volumes for state and the certificate, the dashboard published and the captcha-API port — is shown on the downloads page in your cabinet, already carrying the current tag. Port 8892 is published in advance even though the captcha API is off: it is switched on in the dashboard and takes effect at once, whereas a port not published when the container was created cannot be added later. The image page lists every published tag.

blanktrail/blanktrail-proxy on Docker HubTags, architectures and a short run guide

The configuration file

On Linux the file is /etc/blanktrail/config.yaml, in a container it is wherever you mounted it, on Windows it sits next to the application. Everything configured from the dashboard lives in the database, not here: the file sets what is needed BEFORE the first request — addresses, paths and startup ports.

Key	Default	What it sets
`api.addr`	`:8891`	The address of the control server: the dashboard and the API. This is the port to publish from a container.
`log.level`	`info`	The log level: debug, info, warn or error. It changes on the fly with PUT /api/v1/log_level.
`log.console_level`	`—`	A separate threshold for console output; empty means the same as the file's.
`log.file`	`data/proxy.log`	Where the application log is written. Empty means the error stream only.
`log.max_size_mb`	`50`	The size past which the log rotates aside to proxy.log.1. It bounds disk use on long runs.
`portmanager.idle_timeout`	`30m`	How long until a port with no traffic closes. A port may have its own value (PUT /api/v1/port/{port}/idle).
`portmanager.max_ports`	`100000`	The ceiling on simultaneously open ports. It is headroom, not the plan's limit: what is actually allowed is decided by the license.
`portmanager.startup_ports`	`—`	The ports the product opens BY ITSELF at start. See below.
`mitm.ca_cert / ca_key`	`data/ca.crt / data/ca.key`	The root certificate TLS is opened with, and its key.
`mitm.crl_public_host`	`—`	The address at which the certificate revocation list is visible from ANOTHER machine: host or host:port. Needed when the proxy ports are used from elsewhere.
`mitm.cert_ttl`	`24h`	How long a site certificate issued on the fly lives.
`database.path`	`data/profiles.db`	The fingerprint profile database.
`license.key_file`	`data/license.key`	The file holding a license key of the form SPF-XXXXX-XXXXX-XXXXX. secret_file and device_id_file sit next to it — move them together with the key, or the installation will look like a new device.
`selfupdate.report_rollbacks`	`true`	Whether to report a failed self-update. It is the only report the product sends unasked; false leaves the reason in the log alone.

NoteThe installed file contains a proxy block with the http_addr and socks5_addr keys (for example 0.0.0.0:8090 and 0.0.0.0:1080), and a cert_cache_size key in the mitm block. These are leftovers from early versions and configure NOTHING: the product listens on neither 8090 nor 1080, and the certificate cache size is fixed inside the program. Proxy ports appear only through portmanager.startup_ports or through the API, and you choose their numbers — those are the numbers to forward in a firewall or a container, not the values from the proxy block.

Ports opened at start

This is what the file is most often edited for: a container that must come up with a port already open. The list is read by the product itself, and the ports open EXACTLY when the license gate has allowed serving — they cannot open earlier, and an outside script does not know that moment: it can only rush or sleep blindly. After the connection to the authorization server is restored the ports reopen by themselves.

A fragment of config.yaml

portmanager:
  idle_timeout: "30m"
  startup_ports:
    - port: 20134
      protocol: socks5
    - port: 20135
      protocol: http

An empty protocol means http; http and socks5 are allowed.
The identity and the other settings of such a port are given afterwards — through PUT /api/v1/port/{port}/config or by loading a preset.
An empty list behaves exactly as before: the product opens nothing by itself.

NoteEditing the file on a running installation makes sense only together with a restart: it is read once at start. Everything that needs changing on the fly — the log level, the idle timeout, domain routing — is changed through the API and survives a restart by itself.

Root certificate

BlankTrail Proxy terminates TLS locally, so every device that connects through it must trust its root certificate. Otherwise browsers and tools will show certificate errors on HTTPS sites.

On Windows the installer adds the certificate to the system trust store automatically. To install it on another device, open the dashboard, click the CA Certificate button in the header, and follow the per-platform instructions. You can also download the certificate directly from the API (see License & access → The root certificate (CA)).

ImportantOnly install the certificate on devices you control and route through your own BlankTrail Proxy instance. It exists solely so those devices can trust your local proxy.

First run

On first launch the app prepares its local state, generates the root certificate, and starts the dashboard. Open http://127.0.0.1:8891 (or use the tray's "Open Dashboard" item) to finish setup.

You'll be guided through activating your license and setting a dashboard password. After that, the dashboard is ready for managing ports.

Activating your license

A license is required for BlankTrail Proxy to run. You can activate in a few ways:

Email + password — sign in with your blanktrail.com account credentials in the onboarding screen.
Ticket + license ID — use a confirmation code when two-factor confirmation is required.
Zero-touch — a gated installer can carry an enrollment token and activate automatically on first boot.

Get your license and downloads from your account at blanktrail.com. A running instance keeps working through short authorization-server outages thanks to a built-in grace window, so a brief hiccup won't interrupt a job.

Three things are worth knowing about the grace period, because planning long work depends on them. It lasts exactly ONE DAY: while the authorization server is unreachable a running instance keeps working, but after 24 hours the open ports CLOSE and new ones do not open — with the answer “serving suspended: license inactive”. And at STARTUP there is no grace at all: an application starting without a connection to the license server will not begin serving.

NoteHence a practical consequence for containers and servers: a route to the authorization server is needed both at startup and at least once a day. The ports listed in portmanager.startup_ports reopen by themselves once the connection returns.

System-level traffic interception

The installer's task page has a separate item, “System traffic interception”. It registers the privileged service without which the product can work only as an ordinary proxy — that is, with applications you can point at a proxy address.

The item is visible only in an install “for all users” and needs an administrator confirmation. In a per-user install, or if the confirmation is declined, setup continues and interception simply stays unavailable — the service can be installed later from the “TUN helper” tray group.

NoteRegistering the service intercepts nothing by itself: until a port with interception is open the service simply waits. On upgrade it re-registers if it was installed before, and it is removed when the product is uninstalled.

System traffic interceptionWhat the service does to the machine, the interception scopes, states and diagnostics.

🔴 In an administrative install this item is TICKED in advance: an administrator who simply presses “Next” registers the service. To skip it the box must be unticked by hand — setup does not break because of that, interception simply stays unavailable until the service is installed from the tray menu.