TorCap – A Self-Hosted Tor Screen Logger for Your Own Machines

1. Why TorCap? Transparent Logging for Your Own Devices

I’ve always liked the idea of having an “activity black box” for my own machines – something I can check when I break my workflow, mis-click a window, or want to reconstruct what I was doing at 01:00 last night on my Windows box.

Most tools that do screen logging either fall into two extremes:

• Security / remote support products aimed at enterprises, with closed code and heavy agents.
• Sketchy “spyware” tools that are opaque, stealthy and clearly not built with ethics in mind.

TorCap is a middle path:

• Open and auditable: small Python codebase, clear config, no magic.
• Self-hosted: screenshots live on your own Debian server, not a cloud SaaS.
• Tor-only access: web UI is served as a private .onion site.
• Non-stealthy by design: you configure it for your accounts, with clear paths and logs.

The goal isn’t to spy on others, but to give yourself a forensic timeline of what happened on your Windows session, stored safely on a machine you control.

2. Architecture – Server, Client and Tor in the Middle

TorCap consists of two main components: a Debian server with a Flask app, and a Windows client that captures screenshots and ships them over Tor.

2.1 Server (Debian) – Tor Hidden Service + Flask UI

The server side lives typically on a Debian 13 VPS or a home server:

• Flask app (tor_server.py) listening on 127.0.0.1:5000.
• Tor configured to expose that app as a hidden service (e.g. abc123.onion).
• Screenshot storage under a root folder like:

  /home/youruser/TorCap_data/
  ├─ CiscoAnass/
  │  ├─ 21-11-2025/
  │  │  ├─ screenshot_20251121_000918.png
  │  │  └─ ...
  └─ nesrino186/
     └─ 22-11-2025/

• Web UI to:
  • Log in with admin credentials.
  • Browse by user → day → thumbnail grid.
  • Click a thumbnail to open a full-size preview modal.

All server settings live in server_config.json (more on that later), not in random environment variables.

2.2 Client (Windows) – TorCap.exe Screen Logger

The Windows side is built from app.py into a single TorCap.exe using PyInstaller. It:

• Starts when you log into your account (via Task Scheduler).
• Takes screenshots every interval_seconds (default 10s).
• Saves them under a daily folder: C:\Users\You\Pictures\Security\DD-MM-YYYY\.
• Collects screenshots into batches and uploads them to the server via Tor (SOCKS proxy).
• Respects a max folder size and rotates old files to avoid filling the disk.

Configuration lives in a local config.json placed next to the EXE: capture interval, screenshot folder, Tor SOCKS proxy, server .onion URL, shared upload password, etc.

2.3 Why Tor and Not Plain HTTPS?

Using Tor for this kind of logging has some nice properties:

• No public IP exposure: the Debian server doesn’t need a public port; Tor handles routing.
• End-to-end encryption: Tor hidden services are encrypted by design.
• Clear separation: you always access the UI explicitly via Tor Browser; there’s a mental barrier between “normal web” and “screenshot vault”.

3. Implementation – From Debian Setup to Windows Scheduled Task

Let’s walk through the main steps to get TorCap running on your own devices: server, Tor hidden service, Windows config and EXE build.

3.1 Server Setup on Debian

Basics on Debian 13:

sudo apt update
sudo apt install python3 python3-venv python3-pip tor

mkdir -p ~/TorCap
cd ~/TorCap

python3 -m venv venv
source venv/bin/activate
pip install flask

Copy the server files into ~/TorCap:

• tor_server.py – the Flask app.
• server_config.json – your server config (create it next).

3.1.1 server_config.json

Example:

{
  "root_folder": "/home/youruser/TorCap_data",
  "web_username": "anass",
  "web_password": "CHANGE_THIS_WEB_PASSWORD",
  "upload_password": "CHANGE_THIS_UPLOAD_PASSWORD",
  "site_name": "TorCap",
  "session_secret": "CHANGE_THIS_SESSION_SECRET"
}

Key values:

• root_folder – where screenshots live on the server (per user/day).
• web_username / web_password – login for the Tor web UI.
• upload_password – shared secret; must match each Windows client.
• session_secret – random string for Flask sessions.

3.1.2 Tor Hidden Service

Edit /etc/tor/torrc:

sudo nano /etc/tor/torrc

Add at the bottom:

HiddenServiceDir /var/lib/tor/TorCap_service/
HiddenServicePort 80 127.0.0.1:5000

Restart Tor and grab the hidden service hostname:

sudo systemctl restart tor
sudo cat /var/lib/tor/TorCap_service/hostname

You’ll get something like: nlbsg4kl2itgwcu5g6ysikwmx77lavxb5kh2c36mg7wlmazn2332hhid.onion. That’s your private URL for:

• Tor Browser (web UI).
• Windows config.json as server_url.

3.1.3 Running the Flask Server

cd ~/TorCap
source venv/bin/activate
python tor_server.py

Now open Tor Browser and browse to: http://YOUR_ONION_HOSTNAME.onion/, then log in with your web credentials.

3.2 Windows Client – Builder Machine

On the machine where you build TorCap.exe:

cd C:\Users\YourUser\Desktop
mkdir TorCap
cd .\TorCap

python -m venv venv
.\venv\Scripts\activate

pip install mss requests pysocks pyinstaller

Copy in:

• app.py – the Windows client code.
• config.json – client configuration template.

3.2.1 config.json on Windows

{
  "interval_seconds": 10,
  "screenshot_folder": "C:/Users/YourUser/Pictures/Security",
  "server_url": "http://YOUR_ONION_HOSTNAME.onion",
  "upload_password": "CHANGE_THIS_UPLOAD_PASSWORD",
  "upload_batch_size": 10,
  "max_folder_size_mb": 500,
  "tor_socks_proxy": "socks5h://127.0.0.1:9050",
  "log_file": "screen_guard.log"
}

Notes:

• server_url uses http:// (Tor handles encryption).
• upload_password must match the server’s.
• tor_socks_proxy points to your local Tor instance (service or Tor Browser).
• max_folder_size_mb prevents your disk from filling up.

3.2.2 Build TorCap.exe

.\venv\Scripts\activate

pyinstaller --onefile --noconsole ^
  --name="TorCap" ^
  app.py

After the build, your EXE will be at: C:\Users\YourUser\Desktop\TorCap\dist\TorCap.exe.

3.3 Deploying to Your Own Windows PCs

On each Windows machine you want to log (again: your own accounts):

• Create a folder, e.g. C:\Program Files\TorCap\.
• Copy TorCap.exe and a tailored config.json into it.

3.3.1 Task Scheduler – Run at Login

Configure a task that starts TorCap when you log in:

1. Open Task Scheduler.
2. Create Task → Name: TorCap.
3. General tab:
   • “Run only when user is logged on” (transparent behaviour).
4. Triggers → New → “At log on” → select your user.
5. Actions → New → “Start a program”:
   • Program: C:\Program Files\TorCap\TorCap.exe
   • Start in: C:\Program Files\TorCap\
6. Save the task.

Next time you log in, TorCap will start, follow the config, and begin sending screenshots to your Tor server, respecting the batch size and rotation rules.

4. Behaviour, Safety and Ethical Boundaries

TorCap is intentionally opinionated about how it behaves and how it should be used.

4.1 How the Client Behaves

• On startup:
  • Loads config.json from the EXE directory.
  • Ensures the base screenshot folder exists.
  • Scans for existing .png files and treats them as pending uploads.
• Every interval_seconds:
  • Creates a folder DD-MM-YYYY for the current day.
  • Captures a screenshot named screenshot_YYYYMMDD_HHMMSS.png.
  • Adds it to the pending upload queue.
  • Runs rotation to keep total size under max_folder_size_mb.
• Upload logic:
  • When pending files ≥ upload_batch_size, tries to POST them to /api/upload on the Tor server via the SOCKS proxy.
  • Sends username, day and file, with X-Upload-Password header.
  • On HTTP 200: deletes the local file; on error: keeps it for retry.

4.2 How the Server Behaves

• Reads server_config.json on startup.
• Stores files under root_folder / <username> / <day> / filename.png.
• Validates the upload password on each request.
• Provides an authenticated web UI for browsing screenshots via Tor Browser only.

4.3 Ethics, Law and Responsible Use

This part is important:

• TorCap is intended for self-monitoring and personal audit on machines you own.
• Using similar tooling to secretly record someone else’s screen without consent can be illegal and is definitely unethical.
• If multiple people use a machine, make sure everyone understands that TorCap is running.
• If you’re in a company context, follow local laws and internal policies – don’t roll your own monitoring without proper approval.

The repo even calls out that the code tries to avoid stealthy or malware-style tricks. The idea is transparency, not “hiding in the shadows”.

5. What’s Next for TorCap?

TorCap already does what I wanted: a reproducible, self-hosted screen logger for my own devices. But there’s a clear roadmap for improvements:

• Better UI: filters, keyboard navigation, and a timeline view that lets you scrub through screenshots like a video.
• Multi-factor access: adding TOTP or hardware key support for the Tor web UI.
• Advanced retention settings: per-user retention periods and automatic clean-up jobs on the server.
• Integration with logs: link screenshots to system logs or activity logs for deeper debugging of “what happened at that time”.
• Optional encryption at rest: encrypt screenshots on disk with a separate key, to add another layer on top of Tor’s transport encryption.

For now, TorCap is a nice example of combining Python, Flask, Tor and Windows scripting into a very focused tool that respects the boundary between personal observability and surveillance.