Skip to content

Home

Jump to bottom
MD Mehedi Hasan edited this page Aug 11, 2026 · 4 revisions

OnionHost

Host Websites. Share Files. Communicate Privately. Over Tor.

OnionHost is an Android application that transforms an Android phone into a private static-content server published through a Tor v3 Onion Service.

Import a website, document, media file, archive, or individual file, start hosting, and share the generated .onion address with visitors using Tor Browser.

OnionHost also includes anonymous one-to-one conversations and named group chat rooms served directly through the same Onion Service.

📌 Project Overview

Property Details
Project OnionHost
Platform Android
Language Kotlin
Minimum Android Android 8.0 / API 26
Build SDK Android API 34
Tor Tor v3 Onion Services
Current Source Version 1.1.1
Version Code 5
Organization Security Talent
License OnionHost Source-Available License

🔄 Hosting Workflow

                 User
                  │
                  ▼
           Import Content
                  │
                  ▼
       Application Private Storage
                  │
                  ▼
           Start Hosting
                  │
                  ▼
        Foreground Service
                  │
                  ▼
        Embedded HTTP Server
                  │
                  ▼
             Tor Bootstrap
                  │
                  ▼
       Onion Service Publication
                  │
                  ▼
          .onion Address
                  │
                  ▼
             Tor Browser

🛠️ Build From Source

Requirements

Development requires:

  • Android SDK API 34

  • JDK 17

  • Android 8.0+ device for runtime testing

Clone Repository

git clone https://github.com/SecurityTalent/OnionHost.git
cd OnionHost

Configure Android SDK

On Windows PowerShell:

$env:ANDROID_HOME = "C:\Users\<you>\AppData\Local\Android\Sdk"

Build Debug APK

.\gradlew.bat :app:assembleDebug

The debug APK will be generated at:

app/build/outputs/apk/debug/app-debug.apk

📦 APK Publishing

OnionHost uses the following repository path for the latest downloadable APK:

releases/OnionHost-latest.apk

This allows the download link to remain unchanged between releases.

Publish Latest APK

After building and testing:

.\gradlew.bat :app:publishLatestApk

The task updates:

releases/OnionHost-latest.apk

🔑 Production Signing

Production releases should always use a persistent private signing key.

Create an untracked:

keystore.properties

in the repository root.

Example:

storeFile=C:\secure\onionhost-release.jks
storePassword=your-store-password
keyAlias=onionhost
keyPassword=your-key-password

Never commit:

*.jks
*.keystore
keystore.properties

Publish Production APK

.\gradlew.bat :app:publishProductionApk

The task publishes the signed APK as:

releases/OnionHost-latest.apk

If signing properties are missing, the release publishing task intentionally does not publish the production APK.

🐛 Troubleshooting

Onion Service Is Not Live

Check:

  1. Internet connectivity.

  2. Tor status in Logs.

  3. Tor bootstrap progress.

  4. Onion Service publication status.

  5. Device connectivity.

  6. Battery optimization restrictions.

Do not share the Onion address until the service is reported as live.

Website Does Not Load

Verify:

  • Hosting is running.

  • The Onion address is correct.

  • Tor Browser is being used.

  • Website content was imported successfully.

  • index.html exists when expected.

  • Logs do not report an HTTP/Tor error.

Chat Does Not Load

Check:

  1. Onion Service status.

  2. Tor Browser connection.

  3. Correct chat URL.

  4. Hosting status.

  5. Application logs.

Chat History Disappeared

Normal hosting or device restarts should not remove chat history.

Chat data is removed if Android application data is cleared or OnionHost is uninstalled.

APK Build Problems

Verify:

JDK 17
Android SDK API 34
ANDROID_HOME
Gradle configuration

Then run:

.\gradlew.bat :app:assembleDebug

🛡️ Responsible Use

OnionHost is intended for legitimate:

  • Privacy-preserving hosting

  • Development

  • Testing

  • Security research

  • Education

  • Communication

Users are responsible for everything they publish or distribute through their own Onion Service.

The developers and maintainers do not endorse or authorize unlawful use of the software.

Security testing should only be performed against systems and content that you own or have explicit authorization to test.

🤝 Contributing

Contributions are welcome through:

  • Issues

  • Pull Requests

  • Documentation improvements

  • Bug reports

  • Security improvements

  • Testing

  • Feature proposals

When reporting an issue, provide:

Android version:
OnionHost version:
Device:
Steps to reproduce:
Expected behavior:
Actual behavior:
Relevant logs:

Never include:

  • Private keys

  • Passwords

  • Credentials

  • Private Onion links

  • Sensitive hosted content

in public issues.

For security-sensitive vulnerabilities, avoid publicly exposing sensitive details before maintainers have had an opportunity to investigate.

📜 License

OnionHost is not released under an unrestricted MIT or Apache license.

The project uses the repository's OnionHost Source-Available License.

The license places restrictions on copying, publishing, redistribution, modification, separate-product forks, and commercial use without prior written permission from Security Talent, subject to the exact license terms.

Contributors retain copyright in their original work while granting the project the rights specified by the contribution terms.

See the repository's LICENSE file for the authoritative license.

This documentation is not legal advice.

🏢 Security Talent

OnionHost is created and maintained by Security Talent.

Project

GitHub:
https://github.com/SecurityTalent/OnionHost

Website:
https://securitytalent.net

📚 Documentation Summary

OnionHost
│
├── Android Application
│
├── Static Website Hosting
│
├── File & Media Hosting
│
├── Tor v3 Onion Services
│
├── Anonymous Personal Chat
│
├── Anonymous Group Rooms
│
├── QR Code Sharing
│
├── Privacy-Preserving Analytics
│
├── Application / HTTP / Tor Logs
│
├── Security Controls
│   ├── Private Storage
│   ├── Path Traversal Protection
│   ├── MIME Validation
│   ├── Rate Limiting
│   └── Security Headers
│
└── Android Development & Release Tooling
    ├── Debug Build
    ├── APK Publishing
    └── Production Signing

OnionHost — A private static hosting and communication platform for Android, powered by Tor v3 Onion Services.

# OnionHost

Host Websites. Share Files. Communicate Privately. Over Tor.

OnionHost is an Android application that transforms an Android phone into a private static-content server published through a Tor v3 Onion Service.

Import a website, document, media file, archive, or individual file, start hosting, and share the generated .onion address with visitors using Tor Browser.

OnionHost also includes anonymous one-to-one conversations and named group chat rooms served directly through the same Onion Service.

📌 Project Overview

Property Details
Project OnionHost
Platform Android
Language Kotlin
Minimum Android Android 8.0 / API 26
Build SDK Android API 34
Tor Tor v3 Onion Services
Current Source Version 1.1.1
Version Code 5
Organization Security Talent
License OnionHost Source-Available License

🚀 Features

🌐 Static Website Hosting

Turn an Android phone into a Tor-accessible static web server.

OnionHost supports importing:

  • Complete static websites
  • HTML files
  • Documents
  • Images
  • Videos
  • Audio
  • APK files
  • ISO files
  • Other supported static files
  • ZIP-based websites

Imported content is copied into private application storage before it is served.

🧅 Tor v3 Onion Services

OnionHost publishes hosted content through a Tor v3 Onion Service.

The application waits until Tor reports that the Onion Service descriptor has been published before presenting the Onion address as ready to share.

The generated address can then be opened using Tor Browser.

Example:

http://your-onion-address.onion/

📁 Content Import

OnionHost provides three primary import methods.

Choose Folder

Use this for a complete static website.

website/
├── index.html
├── css/
│   └── style.css
├── js/
│   └── app.js
└── images/
    └── logo.png

Choose ZIP File

Import a static website packaged as a ZIP archive.

OnionHost extracts the archive into application-private storage.

Choose Single File

Useful for hosting individual:

  • HTML files
  • Documents
  • Images
  • Videos
  • Audio
  • APK files
  • ISO files
  • Media files

🌍 HTTP Server

The embedded HTTP server supports:

  • Static-file serving
  • Directory listings
  • Safe MIME types
  • Download headers
  • Byte-range requests for supported media
  • Optional basic authentication

If an index.html file does not exist, directory listings can be displayed.

💬 Anonymous Chat

OnionHost includes a built-in anonymous communication system.

No third-party chat server, phone number, or visitor account is required.

There are two separate chat modes:

Chat
├── Personal Chat
└── Rooms

👤 Personal Chat

Personal Chat is designed for one-to-one conversations.

Create a Personal Chat

  1. Open Chat.
  2. Select Personal chat.
  3. Select New personal chat link.
  4. Copy the generated link.
  5. Share it with the intended person.
  6. Open the saved chat to communicate.

Personal conversations remain separate from group rooms.

👥 Group Chat Rooms

Rooms provide group conversations.

Create a Room

  1. Open Rooms.
  2. Enter a room name.
  3. Press Create.
  4. Open the newly created room.
  5. Copy the room's unique link.
  6. Share the link with participants.

Example room names:

friends
team
project
research

A room URL follows this structure:

http://your-onion-address.onion/chat/room-room1

Each room has a separate URL.

💬 Chat Capabilities

The chat system supports:

  • Automatically generated anonymous browser names
  • Text messages
  • Personal conversations
  • Group rooms
  • Activity indicators
  • Message deletion
  • Message history
  • Attachments
  • Loading/reconnection indicators

Message Limit

Text messages support up to:

1,000 characters

Supported Attachments

PNG
JPEG
GIF
WebP
MP4
WebM
MP3
OGG
WAV

Maximum attachment size:

5 MB

💾 Chat Persistence

Chat data is stored in the application's private storage.

A primary archive and local backup archive are maintained for chat changes.

If an interrupted write damages the primary archive, the backup can be restored during the next application launch.

Chats survive:

  • Hosting restarts
  • Application restarts
  • Normal device restarts

Chats are removed when:

  • Android application data is cleared
  • OnionHost is uninstalled

Each room retains the latest:

200 messages

🔗 Private Chat Links

A private chat or room URL is an access secret.

It should not be considered equivalent to end-to-end encryption.

For private rooms:

  • Use unpredictable room names.
  • Do not publish private links.
  • Share links only with intended participants.

📷 QR Code Sharing

The Home screen displays a QR code for the active Onion address.

Users can:

  • Tap the QR code
  • Download the QR code as PNG
  • Copy the Onion address

The address copy button copies only the website address.

Chat links are managed separately from the Chat screen.

📊 Analytics

OnionHost provides local hosting analytics.

Analytics include:

  • Visits
  • Downloads
  • Requested paths
  • Daily statistics

The analytics system does not store:

  • IP addresses
  • User-agent strings

Analytics are intended to provide useful local statistics while minimizing stored visitor information.

📝 Logs

The Logs screen provides diagnostic information for:

  • Application events
  • HTTP activity
  • Tor status
  • Hosting problems
  • Onion Service publication problems

Logs can be useful when diagnosing startup and connectivity issues.

⚙️ Application Screens

Screen Purpose
Home Start/stop/restart hosting, view Onion address and QR code
Chat Personal chats and group rooms
Websites Manage imported websites and active content
Analytics Local visits, downloads and statistics
Logs Application, HTTP and Tor diagnostics
Settings Hosting and application preferences
About Application information

🔐 Security & Privacy

OnionHost uses multiple security controls to protect hosted content and application data.

Private Storage

Imported content is stored in application-private storage before being served.

Path Traversal Protection

The server prevents requests from escaping the configured hosted content root.

Conceptually:

Hosted Content
├── index.html       ✓
├── assets/app.js    ✓
└── ../private.db    ✗

MIME Validation

MIME validation restricts the types of content that can be served and uploaded through supported interfaces.

HTTP Security

Chat pages and APIs use:

  • no-store cache headers
  • Restrictive Content Security Policy

Request Rate Limiting

The embedded server rate-limits requests based on the observed source address.

Tor Key Management

Tor creates and owns the v3 Onion Service key material.

OnionHost does not generate a fake Onion address.

The Onion hostname corresponds to the Tor-managed service.

Onion Service Publication

The Onion address becomes shareable only after Tor reports that its service descriptor has been published.

This prevents the application from presenting an unpublished service as ready.

🏗️ Architecture

The project is organized into several major components.

                         ┌─────────────────────┐
                         │     OnionHost UI    │
                         │   Jetpack Compose   │
                         └──────────┬──────────┘
                                    │
               ┌────────────────────┼────────────────────┐
               │                    │                    │
               ▼                    ▼                    ▼
          Hosting Layer        Chat Layer           Settings
               │                    │
               └──────────┬─────────┘
                          ▼
                  Embedded HTTP Server
                          │
                          ▼
                    Tor Integration
                          │
                          ▼
                  Tor v3 Onion Service
                          │
                          ▼
                     Tor Browser

Component Responsibilities

Component Responsibility
ui/ Compose screens, navigation, hosting controls, chat and QR UI
hosting/ Foreground service and boot receiver
http/ Static routes, chat pages/API, headers and media validation
tor/ Tor process, Onion Service configuration and hostname handling
storage/ Content import and ZIP extraction
security/ MIME checks, path safety and rate limiting
database/ Local website configuration and application data
analytics/ Privacy-preserving local statistics

🔄 Hosting Workflow

                 User
                  │
                  ▼
           Import Content
                  │
                  ▼
       Application Private Storage
                  │
                  ▼
           Start Hosting
                  │
                  ▼
        Foreground Service
                  │
                  ▼
        Embedded HTTP Server
                  │
                  ▼
             Tor Bootstrap
                  │
                  ▼
       Onion Service Publication
                  │
                  ▼
          .onion Address
                  │
                  ▼
             Tor Browser

🛠️ Build From Source

Requirements

Development requires:

  • Android SDK API 34
  • JDK 17
  • Android 8.0+ device for runtime testing

Clone Repository

git clone https://github.com/SecurityTalent/OnionHost.git
cd OnionHost

Configure Android SDK

On Windows PowerShell:

$env:ANDROID_HOME = "C:\Users\<you>\AppData\Local\Android\Sdk"

Build Debug APK

.\gradlew.bat :app:assembleDebug

The debug APK will be generated at:

app/build/outputs/apk/debug/app-debug.apk

📦 APK Publishing

OnionHost uses the following repository path for the latest downloadable APK:

releases/OnionHost-latest.apk

This allows the download link to remain unchanged between releases.

Publish Latest APK

After building and testing:

.\gradlew.bat :app:publishLatestApk

The task updates:

releases/OnionHost-latest.apk

🔑 Production Signing

Production releases should always use a persistent private signing key.

Create an untracked:

keystore.properties

in the repository root.

Example:

storeFile=C:\secure\onionhost-release.jks
storePassword=your-store-password
keyAlias=onionhost
keyPassword=your-key-password

Never commit:

*.jks
*.keystore
keystore.properties

Publish Production APK

.\gradlew.bat :app:publishProductionApk

The task publishes the signed APK as:

releases/OnionHost-latest.apk

If signing properties are missing, the release publishing task intentionally does not publish the production APK.

🐛 Troubleshooting

Onion Service Is Not Live

Check:

  1. Internet connectivity.
  2. Tor status in Logs.
  3. Tor bootstrap progress.
  4. Onion Service publication status.
  5. Device connectivity.
  6. Battery optimization restrictions.

Do not share the Onion address until the service is reported as live.

Website Does Not Load

Verify:

  • Hosting is running.
  • The Onion address is correct.
  • Tor Browser is being used.
  • Website content was imported successfully.
  • index.html exists when expected.
  • Logs do not report an HTTP/Tor error.

Chat Does Not Load

Check:

  1. Onion Service status.
  2. Tor Browser connection.
  3. Correct chat URL.
  4. Hosting status.
  5. Application logs.

Chat History Disappeared

Normal hosting or device restarts should not remove chat history.

Chat data is removed if Android application data is cleared or OnionHost is uninstalled.

APK Build Problems

Verify:

JDK 17
Android SDK API 34
ANDROID_HOME
Gradle configuration

Then run:

.\gradlew.bat :app:assembleDebug

🛡️ Responsible Use

OnionHost is intended for legitimate:

  • Privacy-preserving hosting
  • Development
  • Testing
  • Security research
  • Education
  • Communication

Users are responsible for everything they publish or distribute through their own Onion Service.

The developers and maintainers do not endorse or authorize unlawful use of the software.

Security testing should only be performed against systems and content that you own or have explicit authorization to test.

🤝 Contributing

Contributions are welcome through:

  • Issues
  • Pull Requests
  • Documentation improvements
  • Bug reports
  • Security improvements
  • Testing
  • Feature proposals

When reporting an issue, provide:

Android version:
OnionHost version:
Device:
Steps to reproduce:
Expected behavior:
Actual behavior:
Relevant logs:

Never include:

  • Private keys
  • Passwords
  • Credentials
  • Private Onion links
  • Sensitive hosted content

in public issues.

For security-sensitive vulnerabilities, avoid publicly exposing sensitive details before maintainers have had an opportunity to investigate.

📜 License

OnionHost is not released under an unrestricted MIT or Apache license.

The project uses the repository's OnionHost Source-Available License.

The license places restrictions on copying, publishing, redistribution, modification, separate-product forks, and commercial use without prior written permission from Security Talent, subject to the exact license terms.

Contributors retain copyright in their original work while granting the project the rights specified by the contribution terms.

See the repository's LICENSE file for the authoritative license.

This documentation is not legal advice.

🏢 Security Talent

OnionHost is created and maintained by Security Talent.

Project

GitHub: https://github.com/SecurityTalent/OnionHost

Website: https://securitytalent.net/

📚 Documentation Summary

OnionHost
│
├── Android Application
│
├── Static Website Hosting
│
├── File & Media Hosting
│
├── Tor v3 Onion Services
│
├── Anonymous Personal Chat
│
├── Anonymous Group Rooms
│
├── QR Code Sharing
│
├── Privacy-Preserving Analytics
│
├── Application / HTTP / Tor Logs
│
├── Security Controls
│   ├── Private Storage
│   ├── Path Traversal Protection
│   ├── MIME Validation
│   ├── Rate Limiting
│   └── Security Headers
│
└── Android Development & Release Tooling
    ├── Debug Build
    ├── APK Publishing
    └── Production Signing

OnionHost — A private static hosting and communication platform for Android, powered by Tor v3 Onion Services.

Clone this wiki locally