Tella Desktop

A desktop version of the Tella app made to share files offline via Nearby Sharing. This application enables secure, encrypted file transfers between devices without relying on external servers, prioritizing privacy and security for sensitive data exchange.

Platform and availability

Nearby Sharing is available for Tella Android, Tella iOS and Tella Desktop.

User facing documentation:

• about the Nearby Sharing in general: https://tella-app.org/nearby-sharing
• about Tella Desktop: https://tella-app.org/get-started-desktop/

Prerequisites (to contribute to the project)

• Go 1.24 or later
• Node.js 20.11.1 or later
• Wails CLI (v2.10.1+)

To install Wails:

go install github.com/wailsapp/wails/v2/cmd/wails@latest

Development

1. Clone the repository
2. Install frontend dependencies:

cd frontend
npm install --include=dev

3. Run in development mode:

wails dev

For Linux systems, you may need to use:

wails dev -tags webkit2_41

This will start both the backend server and frontend development server with hot reload.

Note: during development (running with wails dev) the application will output debug logs that are not visible when running a release build.

Folder hierarchy

Frontend files (React) can be found at frontend/src/. The vast majority of all the React code resides in frontend/src/Components.

Backend files reside in backend split across folders app, core, and utils.

• app: Logic to bootstrap the application. Also declares public methods on the backend which can be called by the frontend.
• core: Holds majority of the code - all logic, database operations, http handlers and routes, and any other server-side handling.
• utils: Various utilities dealing with auth, file storage, network, and TLS.

The backend is divided logically across different "services" for the following domains:

• Database: everything related to the database
• Authentication: deals with user authentication and local encryption
• Registration: handles setting up a new transfer session
• Transfer: takes care of an ongoing transfer session
• Server: the HTTPS server
• File storage: bundles together all file storage and file manipulation functions

Each service package has the following structure:

• handler.go: sets up any HTTP handlers if needed / instantiates the service.
• ports.go: declare the public interface of the server.
• service.go: the concrete implementation of the specific service.
• models.go: declares struct types.

Building

To build a production version:

wails build

The built application will be in the build/bin directory.

Building for Windows

We can leverage the Zig toolchain to easily cross-compile golang projects with CGO dependencies, as demonstrated in article 1, article 2 and combine that with Wails manual builds.

• Install the Zig compiler
• Run the script build-for-windows.sh

The Windows executable will be saved as tella.exe.

build-for-windows.sh

#!/bin/bash
CGO_ENABLED=1 GOOS=windows GOARCH=amd64 CC="zig cc -target x86_64-windows" CXX="zig cc -target x86_64-windows" wails build -ldflags "-w -s" -o tella.exe

Configuration

A basic configuration file exists called desktop-settings.toml. It currently controls the following settings:

# the maximum allowed file size to be sent. currently 3GB
maxFileSizeBytes = 3000000000
# maximum amount of files allowed to be sent in a single transfer session
maxFileCount = 1000
# the default port used 
defaultPort = 53320

The config file can be found at:

• Linux: ~/.config/desktop-settings.toml
• Windows: ~\AppData\Local\Tella\desktop-settings.toml
• OSX: ~/Library/Application Support/Tella/desktop-settings.toml

If you need to change the default port, changing this file is how you can accomplish it currently. In the future a settings pane will be added for changing settings directly in the application.

Protocol Support

The application implements the Tella Nearby Sharing protocol with the following endpoints:

• Default Port: 53320
• POST /api/v1/ping - Initial handshake for manual connections
• POST /api/v1/register - Device registration with PIN authentication
• POST /api/v1/prepare-upload - Prepare file transfer session
• PUT /api/v1/upload - File upload with binary data

• POST /api/v1/close-connection

Platform-Specific Notes

macOS Code Signing

The application is configured for code signing and notarization on macOS for distribution outside the App Store:

• Uses Developer ID Application certificate for notarization
• Includes hardened runtime options for security
• Requires valid Apple Developer account for signing

The GitHub Actions macOS build expects these repository secrets:

• MACOS_CERTIFICATE_BASE64 - Base64 encoded .p12 certificate
• MACOS_CERTIFICATE_PASSWORD - Password for the .p12 certificate
• KEYCHAIN_PASSWORD - Temporary CI keychain password
• APPLE_ID - Apple ID email with access to the developer team
• APPLE_APP_SPECIFIC_PASSWORD - App-specific password for notarization

The certificate identity is configured in wails.json as Developer ID Application: Horizontal (6ZG9T42688).

Compatibility

• Mobile: Compatible with Tella iOS and Android apps using the same P2P protocol
• Network: Requires devices to be on the same local network (Wi-Fi)