Onionize

A command-line tool that creates ephemeral Tor Onion Services to proxy local TCP ports.

Think of it as a decentralized, private alternative to ngrok, powered by Arti (the official Tor implementation in Rust).

🇷🇺 Читать на русском

🚀 Concept

The Problem: Developers often need to expose a local web server (e.g., localhost:3000) to a colleague or client but don't want to configure router port forwarding or pay for centralized tunneling services.

The Solution: onionize takes a local port and instantly creates a temporary .onion address for it. No registration, no central servers, no NAT configuration required.

✨ Features

• Ephemeral Onion Services: Generates a temporary .onion address that vanishes when you stop the process.
• Zero Configuration: No torrc editing required; uses the embedded Arti client.
• Client Authorization (Restricted Access): Secure your service using x25519 keys so only authorized clients can connect.
• QR Code Generation: Instantly generates a QR code to open the link on Tor Browser Mobile.
• TCP Proxy: Forwards traffic bi-directionally between the Tor network and your local service.
• Cross-Platform: Runs on Linux, macOS, and Windows.
• Localization: Supports English and Russian (detects system locale automatically).

📦 Installation

Build from Source

Requirements: Rust and Cargo.

# Clone the repository
git clone [https://github.com/andsemenoff/onionize.git](https://github.com/andsemenoff/onionize.git)
cd onionize

# Build and run
cargo run --release -- --help

Install via Cargo

cargo install --path .

🛠 Usage

Basic Usage

Expose your local server running on port 3000:

onionize --port 3000

Wait for the bootstrap to finish. You will see a link like http://[random-string].onion

Show QR Code

To easily share the link with a mobile device:

onionize -p 3000 --qr

🔒 Restricted Access (Client Authorization)

If you want to prevent random people from accessing your local service, you can enable Restricted Discovery. This requires the client to possess a specific private key to even find the service in the Tor network.

Option A: Ephemeral Restricted Mode (Easiest)

Automatically generate keys for this session only:

onionize -p 3000 --restricted

The tool will output a Client Key string. You must add this key to your client's Tor configuration to connect.

Option B: Manual Key Management

1. Generate keys:

   onionize --keygen
   

   This will output a Public Key (for the server) and a Private Key (for the client).

2. Run the proxy with the authorized public key:

   onionize -p 3000 --auth "descriptor:x25519:<YOUR_PUBLIC_KEY>"
   

⚙️ CLI Options

🌍 Localization

The interface language is determined automatically based on your system locale. To force a specific language, set the ARTI_LANG environment variable:

ARTI_LANG=ru onionize

Development

To test the proxy locally, you can start a simple file server in another terminal:

python3 -m http.server 3000

Then run onionize. It will generate an onion link. Open this link in Tor Browser to access your local server.

Similar Projects

ephemeral-hidden-service (Python)

⚠️ Disclaimer

Security Notice: By default (without --restricted or --auth), this tool exposes your local port to the entire Tor network. Anyone who knows the generated .onion address can access your service.

• Do not expose sensitive services without additional authentication (e.g., Basic Auth on the web server or using the built-in --restricted mode).
• This tool is intended for development and testing purposes.

🤝 Contributing

Contributions are welcome!

1. Fork the project.
2. Create your feature branch (git checkout -b feature/AmazingFeature).
3. Commit your changes.
4. Push to the branch.
5. Open a Pull Request.

⚖️ License

This project is licensed under either of:

• Apache License, Version 2.0
• LICENSE-MIT

at your option.