oniongrok forwards ports on the local host to remote Onion addresses as Tor hidden services and vice-versa.
oniongrok is a decentralized way to create virtually unstoppable global network tunnels.
For example, you might want to securely publish and access a personal service from anywhere in the world, across all sorts of network obstructions — your ISP doesn’t allow ingress traffic to your home lab, your clients might be in heavily firewalled environments (public WiFi, mobile tether), etc.
With oniongrok, that service doesn’t need a public IPv4 or IPv6 ingress. You’ll eventually be able to restrict access with auth tokens. And you don’t need to rely on, and share your personal data with for-profit services (like Tailscale, ZeroTier, etc.) to get to it.
oniongrok sets up socket forwarding tunnels. It’s like
socat(1), for onions.
Export localhost port 8000 to a temporary, one-time remote onion address.
Export localhost port 8000 to temporary remote onion port 80.
~ is shorthand for the forward between source~destination.
Export localhost port 8000 to a persistent remote onion address nicknamed ‘my-app’.
Nicknames can be re-used in multiple forwarding expressions to reference the same onion address. Let’s set up a little web forum for our Minecraft server.
oniongrok 8000~80@minecraft 25565@minecraft
All the forwards without nicknames use the same temporary address.
oniongrok 192.168.1.100:8000~80,8080,9000 9090
Export a UNIX socket to an onion address.
Export to a non-anonymous remote onion service, trading network privacy for possibly reduced latency.
oniongrok --anonymous=false 8000
Import a remote onion’s port 80 to localhost port 80.
Import remote onion port 80 to local port 80 on all interfaces. This can be used for creating an ingress to the onion on public networks.
Running with Docker is simple and easy, the only caveat is that its the container forwarding, so adjust local addresses accordingly.
Forward port 80 on Docker host.
docker run --rm ghcr.io/cmars/oniongrok:main host.docker.internal:80
If you’re using Podman, exposing the local host network is another option.
podman run --network=host --rm ghcr.io/cmars/oniongrok:main 8000
Because local forwarding addresses are DNS resolved, it’s very easy to publish hidden services from within Docker Compose or K8s. Check out this nextcloud example (watch the log for the onion address)!
Each commit into main triggers an automated release, which publishes a Homebrew tap and Docker image.
brew tap cmars/oniongrok
brew install oniongrok
Dockerfile builds a minimal image that can run oniongrok in a container with the latest Tor release from the Tor Project. Build and runtime is Debian-based.
In a local clone of this project,
The built binary
oniongrok will require a
tor daemon executable to be in your
Should theoretically work on: Linux, Darwin, Android (gomobile) according to the berty.tech/go-libtor README. There are some quirks; see comments in
tor/init_libtor.go for details.
In a local clone of this project,
This will take a long time the first time you build, because it compiles CGO wrappers for Tor and its dependencies.
You’ll need to have C library dependencies installed for the build to work:
If you’re on NixOS, you can run
nix-shell in this directory to get these dependencies installed into your shell context.
Client authentication is great for securing personal services over Tor.
Operate from a yaml file.
oniongrok --config config.yaml
Considering support for distributions: NixOS, brew & choco.
Pull requests are welcome in implementing the above wishlist / planned functionality.
Otherwise, donate to the Tor project with your dollar, or by hosting honest proxies and exit nodes. If you like and use this project, support the public infrastructure that benefits us all.
The oniongrok is a github repository by Casey Marshall