Backing Up Your Onion Address

Your .onion address is a private key on disk. Keep the key and you keep the address forever. Lose it and the address is gone permanently, with no recovery, no reset, and no support ticket that can bring it back. This page is short because the rule is simple, but it's the most important operational thing here.

What the address actually is

When you started HiddenForge, it created a folder for your service inside the directory you mounted (in the Quickstart, that's ./tor-keys). Inside it:

tor-keys/mysite/
├── hostname                 # your .onion address, in plain text
├── hs_ed25519_secret_key    # the private key: THIS is the address
└── hs_ed25519_public_key

The hostname file is just a readable copy of the address. The address is really hs_ed25519_secret_key. Whoever has that file controls the address; whoever loses it loses the address.

Back it up now

Copy the whole key folder somewhere safe and offline:

tar czf hiddenforge-keys-backup.tar.gz tor-keys/

Then move that file off the server, to encrypted storage you control. Treat it like the private key it is:

• Encrypt it. Anyone who reads hs_ed25519_secret_key can impersonate your service.
• Keep it offline. Don't leave the only copy on the same machine that's serving it.
• Don't email it, paste it, or sync it to a third-party cloud in the clear.

Restoring

To bring an address back on a new machine, put the key folder back before you start the container:

mkdir -p tor-keys
tar xzf hiddenforge-keys-backup.tar.gz     # restores tor-keys/mysite/
docker compose up -d

HiddenForge never overwrites an existing key, so it will pick up the restored key and serve the same .onion as before.

Choosing your address in advance (optional, higher-effort)

By default the address is random. If you want a specific prefix (a "vanity" address), or you don't want the key ever generated on the serving machine, you can create the key elsewhere and mount it:

• Generate a v3 vanity key offline with a tool like mkp224o, or generate an ordinary key on an air-gapped machine.
• Place the resulting hs_ed25519_secret_key (with its public key and hostname) into tor-keys/<service>/ before the first start.

This keeps the private key from ever being created on the internet-connected host, which matters if your threat model includes the serving machine being seized or compromised.

The one thing to remember

If you take nothing else from this wiki: back up the key folder, encrypted and offline, before you tell anyone your address. Everything else here can be rebuilt. That can't.