Everything not listed in this document should behave the same as upstream Tor. If a feature, setting, or behavior is not mentioned here, the upstream documentation is accurate and fully applicable — see the Documentation section of
instructions.mdfor links.
Tor is the anonymity network daemon. On StartOS it is infrastructure rather than an app: it gives every other service a SOCKS proxy for outbound traffic and .onion addresses for inbound, and hands those addresses to StartOS through a plugin.
- Upstream repo: https://gitlab.torproject.org/tpo/core/tor/
- Wrapper repo: https://github.com/Start9Labs/tor-startos
- Image and Container Runtime
- Volume and Data Layout
- File Models
- Dependencies
- Network Access and Interfaces
- Installation and First-Run Flow
- Actions
- Tasks
- Health Checks
- Backups and Restore
- Limitations and Differences
- Quick Reference for AI Consumers
A minimal Alpine build around the distribution's tor package — no upstream image exists to use. The manifest's torVersion supplies an exact APK version to the Docker build; startos/versions/current.ts repeats it as the package version's upstream component. The image also carries lyrebird (obfs4 and WebTunnel) and snowflake-client (Snowflake), built from pinned upstream releases with a current Go toolchain in a separate Dockerfile stage: the transport plugins Tor runs as its own child processes while it connects through bridges.
| Property | Value |
|---|---|
| Image | Built from Dockerfile (FROM alpine) |
| Architectures | x86_64, aarch64, riscv64 |
| Command | tor -f /var/lib/tor/torrc |
| Subcontainer | Purpose |
|---|---|
tor-sub |
The tor daemon — start-cli package attach tor lands in it |
chown-tmp |
Temporary; re-owns hidden-service directories after a config change |
One oneshot, chown, runs first: Tor runs as the tor user and refuses a data directory that is not mode 700 and owned by it, while StartOS creates volumes root-owned.
riscv64 is deliberate: Tor is infrastructure other packages depend on, so it should be available wherever StartOS runs.
| Volume | Mount Point | Purpose |
|---|---|---|
tor |
/var/lib/tor |
torrc, the onion keys, Tor's own data, the control socket |
startos |
— (host side) | store.json; a one-time onion import file. Never mounted |
Inside the tor volume:
| Path | What it is |
|---|---|
torrc |
Tor's config. The top is the user's; the rest is generated — see File Models |
hidden_services/ |
One directory per .onion address, <package>/<host>/hs_<index>/. Irreplaceable |
data/ |
Tor's DataDirectory: the state file that pins its entry nodes, and its caches. Disposable |
control.sock |
Tor's control socket, which the health check and the reload use |
.wipe-requested, .auto-wiped |
The watchdog's flags. Present means set |
keys/ |
A relay's identity, on a server that ran one under an earlier release. Unused, and left in place |
torrc.legacy |
The torrc an earlier release wrote, set aside during migration. A record only |
Each hidden_services/ key is its .onion address — lose it and the address is gone for good. Everything Tor can rebuild lives under data/, which is what makes a reset a matter of deleting that one directory.
| File | Volume | Format | Modelled | Written by |
|---|---|---|---|---|
store.json |
startos |
JSON | Yes — FileHelper.json |
The actions, the URL plugin, init |
torrc |
tor |
Text | No — written, never read as state | init/renderTorrc |
store.json is the source of truth. It holds automaticRecovery; bridges, the bridge lines Tor connects through, without the Bridge keyword, where none means a direct connection; and onions: a record keyed <package>/<host>/<index>, each entry carrying its ports (externalPort, internalPort, ssl). A moved address also carries keyId, the original key directory's identity; moving the mapping leaves the key files in place. It does not hold a forward target, and nothing in it is ever removed automatically.
torrc is rendered from it, one way. A line beginning # ===== Everything below this line is generated splits the file:
- Above the marker is the user's. Its contents are preserved, with trailing newlines normalized, and Tor honors it. A file with no marker is treated as all user section.
- Below the marker is generated and replaced on every render:
SocksPort,DataDirectory,ControlSocket; while bridges are set,UseBridges 1, aClientTransportPluginline for each plugin the bridges need, and aBridgeline each; then aHiddenServiceDirblock per address. To change it, change the store — through a service's interface page or Tor's actions. - A change is reloaded in place, except a change to the
Bridgelines, which restarts Tor: Tor bootstraps through new bridges only when it starts. - Tor takes the last value of a single-valued option, so the generated
DataDirectorywins over one written above the marker. List options such asSocksPortare additive, so a user can add a listener but not displace the package's.
An onion's forward target is resolved when the file is rendered, from the live binding, and the render re-runs whenever a target changes. A port with no bridge address is left out, and an address with no port left to forward to is not written at all. Nothing stale is ever kept to point at a port another service might later hold.
None, and by design. Tor sits underneath other services rather than beside them. Dependents import socksHostId and socksPort from tor-startos/startos/utils to reach the proxy.
The SOCKS proxy is a binding with no exported interface: an unexported binding lands only on loopback and the LXC bridge, never the LAN. SocksPort 0.0.0.0:9050 binds every interface of the container, which has only those two, so Tor's start-up warning about a public address is expected.
| Binding | Host | Port | Exported? |
|---|---|---|---|
| SOCKS5 proxy | socks |
9050 | No — bridge and loopback only |
The package exports no interface of its own.
Tor registers as StartOS's url-v0 plugin provider. On every init, and whenever the store or a watched host changes, it exports each address to the interface it serves.
A key is never deleted automatically, and neither is a mapping. What gets cleaned up is what Tor listens on: torrc and the exported URLs only ever hold ports whose binding is enabled and resolves right now.
| What happened | What Tor does |
|---|---|
| The service's ports moved | Follows them — the target is resolved at render time |
| The binding was disabled | Stops serving and exporting it. The address is not unused: the port stays reserved to the service, so the address returns when the binding is enabled again, and Delete Unused Onion Addresses does not offer it |
| The port or host was retired | Stops serving and exporting it. The address becomes unused |
| The package was uninstalled | Stops serving and exporting it. The address becomes unused, and comes back by itself if the package is installed again |
| A restore has not reached it yet | Nothing to do — the address is served as soon as its host is bound, in whatever order packages are restored |
| A lookup threw | Skips it for this pass |
An unused address is one none of whose ports belongs to a binding its service still holds: no port is on a disabled binding, and none resolves to a bridge address. It is not written to torrc and shows on no interface page. It leaves two ways: Add Onion Service offers it for any interface of the same package, even on another host, which is how an address survives a service renumbering a port; and Delete Unused Onion Addresses destroys its key.
Nothing to configure. Install seeds store.json and renders a torrc. Start the service; the SOCKS proxy is available once the bootstrap completes. There is no task, no account, and no credential.
You do not add onion services by hand. They arrive through the URL plugin when a service is given a Tor address on its interface page.
An install carrying onion addresses from StartOS 0.3.5 imports them once. If onion-migration.json is present on the startos volume, init derives each address from its key, writes the key material into place, and renames the file to .onion-migration.json.bak. Each address keeps the ports StartOS hands over with it — the onion port and internal port of every mapping it had on 0.3.5, using the binding's native protocol (including native TLS), not an OS-added SSL leg — so it is served as soon as its service binds those ports, in whatever order the services migrate. An entry handed over without ports takes them from its host's bindings at import, disabled ones included, and gets an empty port list if the host is absent. Keys that are not properly clamped are skipped; retrying an interrupted import recognizes already imported addresses.
An import that leaves an address with no ports, and the update to 0.4.9.15:0 on a server that imported addresses, post a notification listing every unused address with its package and host, and how to attach one again.
Updating from a release that used torrc as its database runs a migration that reads the onions out of the old torrc into store.json, sets that file aside as torrc.legacy, and moves Tor's state and caches under data/ so the update does not re-select the server's entry nodes. Relay settings are dropped and the old relay host is retired, freeing its bindings. The downgrade is prohibited.
Add Onion Service / Delete Onion Service (hidden)
The plugin's table actions — StartOS invokes them from an interface page.
- Add attaches an address to the interface's binding: a new one, optionally from a supplied key (a base64 64-byte expanded ed25519 key with a clamped scalar; anything else is refused before a file is written), or an existing address of the same package. An address in use stays on its host; an entirely unused one can be explicitly moved to another host within that package, retaining its hostname and original key directory. Attaching to an existing address sheds any mapping of its whose binding is gone.
- Delete detaches: it removes that port's mapping and nothing else. The key stays, and an address left with no port becomes unused.
- Services call them too. Both are
access: 'public', so any installed service can run them througheffects.action.runto manage its own addresses — for instance, to move an address back onto a port it renumbered. Each checks the action'scalleragainsturlPluginMetadata.packageIdand refuses a service acting on another's host; the user, whosecallerisnull, may act on any. Add runs the check in its input form too, so a service cannot list another's unused addresses either. The input is the one the interface page sends:urlPluginMetadatanames the package, host, interface and internal port, andaddress.selectionisnewor one of the address ids the form offers.
The only thing in this package that destroys a key. It lists every unused address with its package and host, all selected by default, and deletes the selected ones with their keys.
- What counts as unused: no port of the address is on a disabled binding or resolves to a bridge address. A disabled binding is not served, but its address is kept for when the service enables it again.
- What it changes: deletes the
hidden_services/directory and the store entry of each selected address. It checks again at run time: if any selected address has come into use since the form opened, it deletes nothing and fails naming them. A binding lookup error also aborts reuse or deletion; it is not evidence that an address is unused. - Repeat safety: deleting is permanent — the key is the address.
- Availability: any status.
Queues a wipe of data/ and restarts. The deletion happens at the next start, before any daemon exists, because a running Tor holds that state in memory and writes it back on shutdown.
- When to run it: Tor is stuck bootstrapping, or keeps dropping circuits.
- Cost: Tor is offline for a few minutes, and it selects new entry nodes — see the trade-off.
- Not affected: the onion keys,
torrc, andstore.json, none of which are underdata/. - Availability: only while the service is running.
One action whose name, description and confirmation follow the current setting. It flips automaticRecovery in store.json. Off is fail closed: the watchdog never acts, and a stuck Tor stays offline until the user runs Reset Tor Connection.
Sets the bridges Tor connects through, pasted one per line as bridges.torproject.org and Tor Browser give them. obfs4, WebTunnel and Snowflake lines are accepted; there are no built-in bridges.
- When to run it: the server's network blocks Tor, or the user does not want the network to see this server connecting to Tor relays.
- What it changes:
bridgesinstore.json, rendered intotorrc. Whitespace is normalized and duplicate lines dropped. - What it refuses, failing the form and changing nothing: any line other than
obfs4,webtunnelorsnowflake, an IP address and port, a 40-hex-digit fingerprint, thenkey=valuearguments in printable ASCII other than",#,;and\; and, since each would stop Tor from starting, an IP address or port Tor cannot parse, or arguments past Tor's 510-byte limit. - Cost: Tor restarts and bootstraps through the bridges, which can take several minutes, and everything that uses Tor waits for it. All of Tor's traffic,
.onionaddresses included, then goes through the bridges. - Repeat safety: replaces the previous bridges. The form opens with the current ones.
- What happens next: the health check shows the bootstrap. Bridges that cannot be reached leave it stuck, and the watchdog escalates after fifteen minutes without progress rather than five.
- Availability: any status. While stopped, the bridges take effect at the next start.
Clears bridges, so Tor restarts and connects directly. Listed only while bridges are set. Its confirmation says that the network can then see this server connecting to Tor, and that on a network blocking Tor nothing connects. The bridge lines are not kept.
- Availability: any status.
None.
| Check | Displayed | Method |
|---|---|---|
tor |
"Tor SOCKS Proxy" | Tor's own control socket — bootstrap phase, circuit state, and dormancy |
The check reads Tor's real state: a bootstrap percentage with Tor's summary line while starting, and a distinct failure for "bootstrapped but cannot build circuits". Dormant counts as healthy. It polls once a second while unhealthy instead of the default thirty.
With Automatic Recovery on, sustained unhealthiness escalates:
- Five minutes with no movement in the bootstrap percentage, or fifteen while Tor connects through bridges, where one phase can take most of five: drop the pinned entry nodes and open circuits over the control socket (
DROPGUARDS,DROPTIMEOUTS,NEWNYM). - Once more, ten minutes later.
- Twenty minutes after that, queue a wipe of
data/and restart. - It wipes at most once per outage. If Tor is still broken afterwards the cause is not stale state — most likely the server has no working internet, or, with bridges set, the bridges are blocked or down — and the check says so and stops.
A healthy reading resets the ladder. With Automatic Recovery off, none of this runs.
Tor pins a small set of entry nodes and keeps them for months. That is deliberate: every fresh selection is another chance of picking an entry node run by an adversary, and the entry node is the one relay that sees this server's IP address. Tor's control specification says of DROPGUARDS, "Do not invoke this command lightly; it can increase vulnerability to tracking attacks over time."
The watchdog cannot tell a bad entry node from a dead link, so anyone able to interrupt this server's connection for five minutes, or fifteen while it connects through bridges, forces a fresh selection, and can repeat that. For most servers staying reachable matters more, which is why the setting defaults to on. The user-facing text states the trade-off and nothing of this mechanism, on purpose.
Both volumes are backed up — sdk.Backups.ofVolumes('tor', 'startos'). The store maps each key directory to the interface it serves, so the two travel together.
- This backup contains the private keys behind every
.onionaddress on the server. Anyone holding it can impersonate those addresses. - A restore brings back the bridges set when the backup was taken, and Tor connects through them. On a different network, or once they are blocked, run Connect via Bridges or Stop Using Bridges.
- Restore order does not matter. Nothing is pruned, so Tor can be restored before, with, or after the services that own its addresses, and each address is served as soon as its host is bound. One whose service never comes back stays unused until Delete Unused Onion Addresses removes it.
- A backup taken before the store-based layout holds only the
torvolume. StartOS restores the package version saved with that backup; updating it then runs the layout migration.
- Everything below the marker in
torrcis generated, and hand edits there do not survive. Edits above it do. - Onion services are not added by hand. They come from other services through the URL plugin.
- Deleting an address is irreversible — the key is the address.
- A key is only ever deleted by hand. Uninstalling a service, or retiring its host or port, leaves its addresses unused rather than deleting them, and installing the service again brings them back.
- The SOCKS proxy is not exported and is reachable only over loopback and the LXC bridge.
- The
torhealth check can restart the service on its own while Automatic Recovery is on. - Operate a relay or bridge on a server other than the one hosting
.onionaddresses. A relay's IP address is publicly listed, and a server that is both a listed relay and the host of.onionaddresses can have the two linked by load and timing measurements, whether or not they share a process. A relay's identity underkeys/is left in place. The migration retires the oldor-multihost; custom domains assigned to it must be reattached to a current service interface. - There are no built-in bridges, and only obfs4, WebTunnel and Snowflake are accepted. Tor Browser's built-in Snowflake works here by pasting its bridge lines into Connect via Bridges. meek, Conjure and plain bridge lines are refused.
package_id: tor
image: ./Dockerfile # FROM alpine, apk add tor; lyrebird and snowflake-client built from source
architectures:
- x86_64
- aarch64
- riscv64
subcontainers:
- tor-sub # the running daemon
- chown-tmp # temporary; re-owns hidden-service dirs after a config change
volumes:
tor: /var/lib/tor
startos: host side, never mounted (store.json; one-time onion import)
file_models:
- store.json # startos volume; source of truth: onions + bridges + automaticRecovery
generated_files:
- /var/lib/tor/torrc # user section above the marker is kept; the rest is rendered from store.json
disposable:
- /var/lib/tor/data # Tor's DataDirectory; Reset Tor Connection deletes it
irreplaceable:
- /var/lib/tor/hidden_services # one key directory per .onion address
flag_files: # present = set
- /var/lib/tor/.wipe-requested
- /var/lib/tor/.auto-wiped
startos_managed_env_vars: []
dependencies: []
interfaces: []
actions:
- add-onion-service # hidden; url-v0 plugin; public, a service may call it for its own hosts
- delete-onion-service # hidden; url-v0 plugin; public, a service may call it for its own hosts
- delete-unused-addresses # the only action that destroys a key
- reset-connection # only-running
- automatic-recovery # toggles store.json automaticRecovery; off = fail closed
- connect-via-bridges # sets store.json bridges from pasted obfs4/webtunnel/snowflake lines; restarts Tor
- stop-using-bridges # listed only while bridges are set; clears them, restarts Tor direct
tasks: []
health_checks:
- tor # displayed "Tor SOCKS Proxy"; also the self-recovery watchdogFor dependent packages: the SOCKS proxy is an unexported binding on host
socks, port 9050. ImportsocksHostIdandsocksPortfromtor-startos/startos/utilsrather than hardcoding either.