Persistent services
Durable onion identity
Service state is stored outside disposable containers so private onion identities can persist across restart and rebuild operations.
Linux • Tor • Containers • Security engineering
TorKit: persistent private onion services with an operator layer.
TorKit is my OnionShare-derived Linux project for running several private onion services as a managed system instead of a collection of one-off processes. The work focuses on persistent onion identity, container boundaries, host-side lifecycle control, recovery, and verification.
The project keeps OnionShare's upstream attribution and GPL licensing while adding TorKit-specific operational tooling around the service runtime.
Host-side control around OnionShare
TorKit separates host orchestration from the OnionShare-derived application code so service lifecycle, state, and operator actions can be controlled explicitly.
Operator controls
Loopback-only management
A host-side operator interface provides authenticated local controls for service lifecycle and destructive actions without exposing an administrative web surface publicly.
Containers
Constrained runtime
Docker Compose and a non-root application runtime keep service execution isolated while preserving the state needed for long-running private services.
Services and state
Private sharing and receiving
TorKit retains OnionShare-derived sharing and receiving workflows behind persistent service configuration and host-side lifecycle management.
Chat and Board
Chat remains disposable while TorKit Board adds a separate persistent SQLite-backed discussion mode for authorized visitors.
Explicit destructive operations
Administrative actions such as clearing persistent state are separated from ordinary service startup and require explicit operator intent.
Encrypted off-host recovery
The recovery workflow stages a coherent snapshot, validates it, and stores it in an encrypted Restic repository.
Integrity
Manifest and hash validation
Recovery payloads include a manifest and SHA-256 file inventory. SQLite state is checked before upload, and restore validates the payload before replacing local state.
Rollback
Replace safely
Restore stages data next to its destination, swaps paths into place, and rolls back failed installation attempts instead of partially overwriting live state.
AWS
Scoped S3 infrastructure
An optional Terraform stack provisions a private S3 bucket with public-access blocking, TLS-only access policy, server-side encryption, and an IAM user scoped to the TorKit recovery prefix.
Publication and runtime verification
The public repository uses a curated Git history and automated checks intended to keep release source separate from private engineering history and runtime secrets.
CLI regression tests
GitHub Actions exercises the inherited OnionShare CLI test suite and TorKit-specific runtime paths.
Container smoke tests
CI validates syntax, host-side unit tests, image build, and container smoke behavior.
Publication verification
Release checks scan the current source and public Git history for credential patterns, run privacy heuristics, and inspect committed images for GPS or author metadata.
Implementation stack
Python
Linux
Tor / OnionShare
Docker Compose
SQLite
Restic
AWS S3
Terraform
systemd
GitHub Actions