Skip to content

About

StartOS package for tor

Resources

Stars

1 star

Watchers

1 watching

Forks

Repository files navigation

Tor Logo

Tor on StartOS

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.md for 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.


Table of Contents


Image and Container Runtime

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 and Data Layout

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 Models

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, a ClientTransportPlugin line for each plugin the bridges need, and a Bridge line each; then a HiddenServiceDir block 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 Bridge lines, 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 DataDirectory wins over one written above the marker. List options such as SocksPort are 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.

Dependencies

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.

Network Access and Interfaces

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.

The URL plugin

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.

Installation and First-Run Flow

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.

Actions

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 through effects.action.run to manage its own addresses — for instance, to move an address back onto a port it renumbered. Each checks the action's caller against urlPluginMetadata.packageId and refuses a service acting on another's host; the user, whose caller is null, 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: urlPluginMetadata names the package, host, interface and internal port, and address.selection is new or one of the address ids the form offers.

Delete Unused Onion Addresses

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.

Reset Tor Connection

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, and store.json, none of which are under data/.
  • Availability: only while the service is running.

Turn Off / Turn On Automatic Recovery

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.

Connect via Bridges

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: bridges in store.json, rendered into torrc. Whitespace is normalized and duplicate lines dropped.
  • What it refuses, failing the form and changing nothing: any line other than obfs4, webtunnel or snowflake, an IP address and port, a 40-hex-digit fingerprint, then key=value arguments 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, .onion addresses 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.

Stop Using Bridges

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.

Tasks

None.

Health Checks

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.

The watchdog

With Automatic Recovery on, sustained unhealthiness escalates:

  1. 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).
  2. Once more, ten minutes later.
  3. Twenty minutes after that, queue a wipe of data/ and restart.
  4. 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.

The trade-off behind Automatic Recovery

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.

Backups and Restore

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 .onion address 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 tor volume. StartOS restores the package version saved with that backup; updating it then runs the layout migration.

Limitations and Differences

  1. Everything below the marker in torrc is generated, and hand edits there do not survive. Edits above it do.
  2. Onion services are not added by hand. They come from other services through the URL plugin.
  3. Deleting an address is irreversible — the key is the address.
  4. 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.
  5. The SOCKS proxy is not exported and is reachable only over loopback and the LXC bridge.
  6. The tor health check can restart the service on its own while Automatic Recovery is on.
  7. Operate a relay or bridge on a server other than the one hosting .onion addresses. A relay's IP address is publicly listed, and a server that is both a listed relay and the host of .onion addresses can have the two linked by load and timing measurements, whether or not they share a process. A relay's identity under keys/ is left in place. The migration retires the old or-multi host; custom domains assigned to it must be reattached to a current service interface.
  8. 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.

Quick Reference for AI Consumers

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 watchdog

For dependent packages: the SOCKS proxy is an unexported binding on host socks, port 9050. Import socksHostId and socksPort from tor-startos/startos/utils rather than hardcoding either.

About

StartOS package for tor

Resources

Stars

1 star

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages