Deploying a Tor Hidden Service to Heroku in 5 Minutes

Remember Tor? Much like Julian Assange, Ethereum, or PGP, you might have thought that it had simply disappeared. But in fact all of these things still exist! And for certain corners of the internet they’re as popular as ever.

So if you’ve caught Tor Fever, follow along while I show you how to deploy your Tor hidden service to Heroku. Or skip to the bottom if you don’t like gifs and just want to copy/paste the code (or just look at the buildpack).

Tor is still very popular

Disclaimer: This is a guide for hobbyists and nerds, not for political dissidents, aspiring drug dealers, or anyone else who requires real anonymity online. If your safety and/or cartel is really on the line, I recommend finding a different guide. On with the show.

This example will usecreate-react-app but you can use whatever language and framework you like. To get started, initialize your project in a new repo. We’ll be calling ours “toroku” because it’s cute.

This is a Toroku in the wild

Dust off your terminal and fire up a new React app:

# This assumes you have a recent version of Node & NPM
npx create-react-app toroku
cd toroku
npm start

Kapow! We have our app running on localhost. You should see the familiarcreate-react-app boilerplate in your browser.

Bask in its soothing blue light

With the Heroku cli installed, you can deploy this in two lines of code. If you’re not using React, replace the create-react-app buildpack with whatever is appropriate for the framework you’re using.

heroku create toroku --buildpack mars/create-react-app
git push heroku master

When the deploy finishes, type heroku open to view your app in the browser. Mine is now online at toroku.herokuapp.com.

But I don’t want just *anyone* to be able to see that React boilerplate. I’m very secretive. Put on your favorite hacker glasses and let’s get hacking.

The nice thing with Heroku is there’s a buildpack for almost everything. Here’s one I created for running your app as a Tor hidden service:

heroku buildpacks:add jtschoonhoven/heroku-buildpack-tor

To actually use the buildpack, you’ll need to create a Procfile so that the run_tor command is called when your app starts. The snippet below tells Heroku to call run_tor and bin/boot when the app starts. bin/boot comes from the create-react-app buildpack, so you’ll need to replace that if you’re using a different framework.

START_SERVER_COMMAND="./tor/bin/run_tor & bin/boot"
echo "tor: $START_SERVER_COMMAND" > Procfile

Our Procfile now defines a dyno named tor. Normally you would use Heroku’s special web dyno, but Heroku’s automatic HTTPS redirects for web dynos make things complicated for Tor (Tor is already end-to-end encrypted so you don’t need HTTPS). Anyway, commit and deploy:

git add .
git commit -m "run app as Tor hidden service"
git push heroku master

This may take a couple minutes while Heroku downloads Tor, verifies the signature, and builds from source. Now is a good time to take a pee.

When the install finishes, our app is not yet online. Heroku doesn’t automatically create non-web dynos, so we have to tell it to “scale up” to one dyno:

heroku ps:scale tor=1

And with that, we have successfully deployed a Tor hidden service! Celebrate! Poor yourself a Coke! Smash a piñata! You deserve it.

Oh, but suppose you want to actually find your app online? Since we didn’t specify our own .onion address (we could have, we just didn’t), Tor created one for us when it started. The easiest way to retrieve the address is to just pull it off the dyno:

heroku ps:exec --dyno=tor.1 'cat "/app/hidden_service/hostname"'

You might have to restart the dyno and rerun this command if it’s your first time using ps:exec. But when the command succeeds, you’ll see the .onion address printed to stdout. Or if you don’t want to paste weird exec commands in your console, you can pull the address from the logs with heroku logs --tail.

Anyway, plop that .onion address in Tor Browser and after a few hops around the globe you’ll be back to basking in the cool blue light of the create-react-app boilerplate. Congratulations! You are a supreme hacker!

Check out the heroku-buildpack-tor repo for more instructions, including how to make your .onion address permanent, or how to generate a vanity address (both are easy). If you found this helpful, give us a clap or a star on the repo, would you?

Happy hacking!