Arachnidium README

The project's README from github.com/p2r3/Arachnidium. As one markdown file: README.md.

Arachnidium

Data-optimizing HTTP(S) proxy, powered by mitmproxy.

Setup

  1. Find a home server - this can be any internet-connected computer, like an old laptop. Currently, pre-built releases exist for x64 Windows and Linux. If you need ARM or Mac support, clone the repository and run it from source.
  2. On your home server, download the portable archive for your system in Releases.
  3. Extract the archive and run Arachnidium.exe (or Arachnidium on Linux).
  4. Install the WireGuard client on your device: Android | iOS
  5. Add the VPN preset using the QR code displayed in Arachnidium. Alternatively, use the automatically generated wireguard.cfg file.
  6. This is where things get a little hairy - if you want to actually use this outside of your home WiFi, you'll have to configure your network to listen for incoming VPN connections. To do this, you will have to forward UDP port 51820 from your home server to your router. The exact process for this is vastly different for every network and router, and it would be impossible to give a universal guide in this document, so please research this yourself. Searching for "port forward udp <router model>" should be enough to get you on the right track. Alternatively, call your internet service provider and ask if they can help.
  7. Connect to the VPN and visit mitm.it on your phone's browser. Follow the instructions there to set up the certificate authority. Make sure to read all of the instructions.

If you run into issues, please make sure you've followed these steps carefully. Do your own troubleshooting first to make sure the issue isn't on your end (e.g. misconfigured network). Please do not message me personally asking for help - I sadly don't have the time (or patience) to be able to assist everyone, sorry.

Configuration

There are two ways to configure Arachnidium: via the graphical interface, or by editing defaults.json. Changes made in the GUI are not saved between restarts - for that, use the JSON file. If you want to run Arachnidium without the GUI, set ENABLE_GUI to false in defaults.json.

Running from source

To run this project from source code without building it (for development purposes, or to run on unsupported platforms):

  1. Install Python and uv.
  2. Install Bun.
  3. Clone this repository with submodules (using --recursive).
  4. Run uv run main.py
  5. In another terminal, change directory to bun-api and run bun i, then bun run index.ts

Contributing

Contributions are welcome, though please note that I am personally unlikely to continue working on this project in the long term. This was something that I've wanted to experiment with for a while, but unlike some of my other projects, I have little intention of actually growing this into its own thing. I might still merge pull requests from time to time, but I probably won't close issues on my own (unless it's something critical).

Before submitting an issue, make sure you've read and followed the usage instructions carefully and have done your own troubleshooting. I would prefer that you do not use LLMs in submitted code, but if you do, please be transparent about it. State where an LLM was used, and explain (in your own words) what it did.

Acknowledgements

The name "Arachnidium" is a homage to nature's earliest web developers. The arachnidium is, generally, the part of a spider's body responsible for producing webs. It also sounds really cool.

Arachnidium (p2r3/Arachnidium)

proxy-server
Searching Database…

397 ·GitHub
Arachnidium
What is this?Arachnidium is a self-hosted HTTP(S) optimization and compression proxy powered by mitmproxy, meant to run on a spare computer at home and be reached by your devices through a WireGuard VPN tunnel.
Is this an app on my phone, or something I run on a home server?It is a server application: you install and run it on an always-on home computer (even an old laptop), then connect your phone or laptop to it over a WireGuard VPN so your traffic gets proxied and compressed by mitmproxy.
How do I get Arachnidium running on my network?Download the portable archive for your OS from Releases, extract it and run Arachnidium.exe (or Arachnidium on Linux), install the WireGuard client on your device, then add the VPN config via the QR code or the generated wireguard.cfg file.
What's the catch with using this outside my home WiFi?To use it away from home you must forward UDP port 51820 from your home server to your router, and the exact steps vary wildly by router/ISP with no universal guide provided; the author also doesn't plan to actively grow or maintain this project long-term.
Which devices can connect to it as clients?Any device with a WireGuard client works; the README specifically links setup for Android and iOS.
Does this see my HTTPS traffic in plain text?Yes — Arachnidium relies on mitmproxy, so you must visit mitm.it on your device and install a locally-generated certificate authority, which lets the proxy decrypt and recompress your HTTPS traffic before it reaches you.
What does mitmproxy actually do here?It intercepts and decrypts your HTTPS connections so Arachnidium can compress and optimize the data in transit before passing it back to your device.
Can I configure it without opening the GUI?Yes, settings can be edited directly in defaults.json, and GUI changes don't persist across restarts unless saved there; you can also disable the GUI entirely by setting ENABLEGUI to false.
Why is it called Arachnidium?It's a playful reference to the arachnidium, the part of a spider's body that produces webs — a nod to 'nature's earliest web developers'.
What are similar projects?MasterHttpRelayVPN-RUST, warp-masque-actions, algo, russia-mobile-internet-whitelist, GoLiveBypass, NewYork, brook, shadowsocks-rust
Which topics is it in?wireguard-vpn, http-proxy, proxy-server, vpn-client, compression, qr-code, tunnel, privacy-tools, bun, vpn, http, json
Creator
p2r3
Size
0.2 MB
Stars
397
Updated
CommitOct 05ReleaselatestSep 24
Age
23d
Commits · 90 Days