Skip to main content

​
Quickstart guide

Get up and running with Hoot in just a few minutes. This guide covers everything from building the application to sending your first message.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Rust 1.70 or later: Install from rust-lang.org
  • OpenSSL development libraries: Required for cryptographic operations
  • Perl: Required for the build process
On macOS, you can install OpenSSL via Homebrew: brew install opensslOn Ubuntu/Debian: sudo apt-get install libssl-dev perl

​
Installation

1

Clone the repository

git clone <repository-url>
cd hoot
2

Build the application

Build Hoot in release mode for optimal performance:
cargo build --release
This will compile the application with optimizations. The first build may take several minutes as it compiles all dependencies.
3

Run Hoot

Launch the application:
cargo run --release
The Hoot window will open with the onboarding interface.

​
Alternative: Using Nix

If you have Nix with flakes enabled: 
nix develop
This will set up a development environment with all required dependencies.

​
First-time setup

When you first launch Hoot, you’ll be guided through the setup process:
1

Account creation

Hoot will automatically generate a new Nostr keypair for you. Your keys are stored securely using platform-specific storage:
  • macOS: Keychain API via security-framework
  • Windows: Credential Manager
  • Linux: Secret Service API with file-based fallback
Your private keys never leave your device and are stored in your operating system’s secure credential storage.
2

Configure relays

Connect to Nostr relays to send and receive messages. The relay pool manages multiple WebSocket connections with:
  • Automatic reconnection every 5 seconds if disconnected
  • Keepalive pings every 30 seconds to maintain connections
Default relays are provided, but you can add your own.
3

Set up your profile

Add your display name and profile information. This creates a Nostr metadata event (kind 0) that others can see.

​
Sending your first message

Once setup is complete, you’re ready to send messages:
1

Compose a new message

Click the compose button to open a new message window. Hoot supports multiple compose windows open simultaneously.
2

Add recipients

Enter recipient Nostr public keys or npub addresses in the To field. You can also add:
  • CC recipients: Copy recipients who can see all other recipients
  • BCC recipients: Hidden recipients that others cannot see
3

Write your message

Add a subject and message content. Your message will be:
  1. Converted to a custom kind 2024 mail event
  2. Wrapped using NIP-59 gift wrap for privacy
  3. Sent as separate wrapped events to each recipient
Each recipient receives a unique gift-wrapped event. This ensures perfect forward secrecy - if one recipient’s key is compromised, other recipients’ messages remain secure.
4

Send

Click send. The message is transmitted to all connected relays. The relay pool ensures delivery by:
  • Sending to all connected relays simultaneously
  • Automatically retrying on failed connections
  • Maintaining connection health with keepalive pings

​
Understanding message flow

Here’s what happens when you send a message: 
// From mail_event.rs:24
pub fn to_events(&mut self, sending_keys: &Keys) -> HashMap<PublicKey, Event> {
    // Create gift-wrapped events for each recipient
    let wrapped_event =
        EventBuilder::gift_wrap(sending_keys, &pubkey, base_event.clone(), None)
            .block_on()
            .unwrap();
    event_list.insert(pubkey, wrapped_event);
}
Your message is converted to events and sent through the relay pool: 
// From relay/pool.rs:64
pub fn add_subscription(&mut self, sub: Subscription) -> Result<()> {
    let client_message = ClientMessage::Req {
        subscription_id: sub.id,
        filters: sub.filters,
    };
    self.send(ewebsock::WsMessage::Text(payload))?;
}

​
Next steps

Explore features

Learn about threading, contacts, search, and more

Development build

Build without optimizations for faster compilation:
cargo build
cargo run

​
Profiling

For developers who want to analyze performance: 
cargo build --features profiling
cargo run --features profiling
This starts a puffin profiler server on 127.0.0.1:8585 and attempts to launch puffin_viewer automatically.
Hoot uses the puffin profiler to track performance metrics. Enable the profiling feature during development to identify bottlenecks.

Build docs developers (and LLMs) love

Get started for freeTalk to us