Upstream docs: https://community.torproject.org/onion-services/
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.
Anonymity network for onion services and private browsing. Run onion services (.onion addresses) to make your installed apps accessible over the Tor network. Provides a SOCKS5 proxy for private browsing and can optionally operate as a Tor relay or bridge to support the network.
- 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
- Installation and First-Run Flow
- Configuration Management
- Network Access and Interfaces
- Actions
- Backups and Restore
- Health Checks
- Limitations and Differences
- What Is Unchanged from Upstream
- Quick Reference for AI Consumers
| Property | Value |
|---|---|
| Base image | Alpine Linux 3.21 with upstream tor package |
| Architectures | x86_64, aarch64, riscv64 |
| Entrypoint | tor -f /etc/tor/torrc |
| User | tor (non-root) |
The image is minimal -- just Alpine + the tor package. No custom patches
or modifications to the Tor binary.
| Volume | Mount Point | Contents |
|---|---|---|
tor |
/var/lib/tor |
Tor data directory, onion service keys, control socket |
The torrc configuration file is stored on the tor volume and is the single
source of truth for all onion service and relay settings. It is generated from
structured data and round-trips cleanly (metadata is embedded as comments).
Onion service keys are stored under /var/lib/tor/hs_<key>/ where <key> is
<packageId>-<hostId> (e.g., filebrowser-main).
- On first install, a critical task is created prompting the user to "Create your first onion service" via the Manage Onion Services action.
- No setup wizard or credentials -- Tor starts immediately with a SOCKS5 proxy on port 9050.
- Onion service
.onionaddresses are auto-generated by Tor on first startup after configuration.
All configuration is managed through StartOS actions. There is no upstream configuration UI.
| Setting | Managed By | Method |
|---|---|---|
| Onion services | StartOS action | Manage Onion Services |
| Relay/bridge settings | StartOS action | Configure Relay |
| SOCKS proxy port | Hardcoded | Always 0.0.0.0:9050 |
| Data directory | Hardcoded | Always /var/lib/tor |
| Control socket | Hardcoded | /var/lib/tor/control.sock |
| Exit relay | Hardcoded | Always disabled |
- Port: 9050
- Protocol: SOCKS5
- Purpose: Private browsing proxy for other services on the network
- Binding:
0.0.0.0:9050(accessible to all services on the StartOS network)
- Port: Configurable (default 9001)
- Protocol: Tor OR protocol
- Purpose: Relay traffic for the Tor network
- Only exposed when relay mode is enabled via the Configure Relay action
- ID:
manage-onion-services - Purpose: Add and remove Tor onion services for installed packages
- Availability: Any status
- Inputs:
- Service -- select from installed packages (plus StartOS UI itself)
- Host -- displayed as grouped interface names (e.g., "UI", "UI, API"); selecting a host includes all its port bindings automatically
- Private Key -- optional base64-encoded ed25519 key for vanity .onion addresses; leave blank to auto-generate
- Behavior: All enabled bindings for the selected host are mapped as
HiddenServicePortentries. The virtual (external) port uses the service's preferred external port; the target port uses the actual internal port.
- ID:
view-onion-addresses - Purpose: Display .onion URLs for all configured services
- Availability: Only when running
- Visibility: Disabled with message if no onion services are configured
- Output: One entry per port mapping, each with:
- Full
http://URL (port omitted for port 80) - Copyable text
- QR code
- Full
- ID:
configure-relay - Purpose: Configure Tor relay and bridge settings
- Availability: Any status
- Inputs:
- Enabled -- toggle relay on/off (default: off)
- Nickname -- 1-19 alphanumeric characters (default: "StartOSRelay")
- Contact Info -- optional operator contact
- Bridge Mode -- toggle bridge relay (default: off)
- OR Port -- 1-65535 (default: 9001)
- Bandwidth Rate -- e.g., "1 MBytes" (default)
- Bandwidth Burst -- e.g., "2 MBytes" (default)
- Note: Exit relay is always disabled. This package only supports non-exit relays and bridges.
- Backed up: Entire
torvolume (onion service keys, torrc, relay state) - Restore behavior: Volume-level restore; onion service keys are preserved, so .onion addresses survive backup/restore cycles.
- Method: Connects to Tor's Unix control socket and queries
GETINFO status/bootstrap-phase - States:
- Loading -- "Bootstrapping: X% - summary" (shown during startup)
- Success -- "Tor is running" (bootstrap reached 100%)
- Failure -- "Tor is not ready" (control socket unreachable or timeout)
- Timeout: 5 seconds per check
- No exit relay support.
ExitRelay 0is always set. This package only supports non-exit relays and bridges. - No Tor Browser. This package runs the Tor daemon only, not Tor Browser.
- SOCKS port is fixed at 9050 and cannot be changed via the UI.
- No stream isolation configuration is exposed.
- No pluggable transports (obfs4, snowflake, etc.) are included in the Alpine image.
- Bandwidth rate values are free-text strings (e.g., "1 MBytes") and are not validated against Tor's accepted units.
- Tor binary is the upstream Alpine package, unmodified
- Onion service v3 protocol behavior
- SOCKS5 proxy protocol and behavior
- Relay and bridge protocol behavior
- Tor directory authority connections
- Automatic circuit building and path selection
package_id: tor
image: Alpine Linux + tor package
architectures: [x86_64, aarch64, riscv64]
volumes:
tor: /var/lib/tor
ports:
socks: 9050
or: 9001 (conditional, relay mode only)
dependencies: none
startos_managed_config:
- torrc (generated from structured data)
actions:
- manage-onion-services
- view-onion-addresses
- configure-relay
languages: [en_US, es_ES, de_DE, pl_PL, fr_FR]