[GH-ISSUE #4204] Sharing files with netbird #8700

Open
opened 2026-08-05 01:19:13 -04:00 by saavagebueno · 7 comments
Owner

Originally created by @aliamerj on GitHub (Jul 23, 2025).
Original GitHub issue: https://github.com/netbirdio/netbird/issues/4204

Implement a Taildrop-like file transfer feature for NetBird, we need to create a secure, peer-to-peer file-sharing system that integrates naturally into NetBird’s infrastructure allowing users to send files between their personal devices on a Netbird network.

Overall Implementation Core Logic:

Build the file transfer functionality to work over NetBird’s peer-to-peer connections.

  • Platform-Specific Code:
    • macOS/iOS/Android: Integrate with the share menu (e.g., “Share via NetBird”).
    • Windows: Add to the share context menu or NetBird client interface.
    • Linux: Develop a command (e.g., netbird send <file> <device/ peer-id>)

TASK 1: File Transfer Activation, Permissions, and Default Save Path

In this first step, I’ll implement the core logic for peer-to-peer file transfer inside the NetBird agent — following a model similar to SSH’s controlled file copy behavior.

🧩 What I’ll Do

  • Introduce a new management-side config flag (e.g., enableFileTransfer: true)

    • that governs whether the agent is allowed to participate in file transfer at all.
    • This is synced to the agent and acts as a hard gatekeeper
      If disabled, the feature is entirely inactive regardless of CLI flags or user actions
  • Agent Startup Check:

    • On startup, the NetBird agent checks the management config for the EnableFileTransfer flag.
    • If disabled, the feature remains entirely off — no listeners, no UI, no CLI options exposed.
  • Local Listener with Optional Runtime Signal
    Once management has enabled it, the agent can start a local listener for file transfer requests:

    • Either automatically on startup (based on CLI/config flag like --file-transfer)
    • Or dynamically triggered at runtime via a dedicated internal signal message (e.g., start_file_transfer_listener)
  • Protobuf-Based Control Messages (used in peer-to-peer communication) to support new message types for file transfer:

    • file_offer → initiate
    • file_accept / file_deny
    • file_meta → metadata (size, name)
    • file_chunk → actual data
    • transfer_complete / transfer_error
  • User Authorization Flow — When someone tries to send a file:

    • Receiver gets a request with file metadata (size, name, sender)
    • Receiver must approve via CLI/desktop UI
    • Optionally allow auto-accept from trusted peers via config
  • Default Save Path via Agent Settings

    • Add support for a default download directory (e.g. ~/NetBirdTransfers)
    • Allow override via CLI flag or agent config
  • Handle file streaming over the established tunnel:

    • Once approved, file chunks will be streamed directly over the existing encrypted tunnel using a TCP/Unix socket connection negotiated internally.
      • No extra open ports
      • Data stays within the mesh tunnel
      • Uses same NAT traversal as other NetBird traffic
  • CLI prototype for Linux to send and receive files using the command:

netbird send <file-path> <peer-id>
  • Works only if both peers are management-enabled and listening
  • Prints real-time status in teminal

TASK 2: Cross-Platform File Sharing UX Integration

Now that we have the internal file transfer logic working (from Task 1), this task focuses on making it usable and accessible across major platforms by integrating with native OS interfaces.

🧩 What I’ll Do

  • Linux ( already done in Task 1)

    • Extend the CLI UX (from Task 1) with optional interactive prompts.
    • Optionally create a minimal GTK or terminal UI to make selection easier.
  • macOS / iOS / Android

    • Create component (i.e. "Share via NetBird").
    • When a file is shared, it triggers a background call to netbird send using the CLI or internal bindings.
  • Windows

    • Add a menu item ("Send with NetBird")
    • Under the hood, it calls the same file-sending command.

🔁 How It Works Technically

  • All platforms will reuse the message handlers and transfer logic from Task 1 — no new protocol or backend work is needed.
  • UI or shell integrations simply act as wrappers around the core agent, either invoking a CLI command or talking directly to the local NetBird service (via Unix socket or similar, if exposed).

TASK 3: Nice to have

  • Add optional settings like transfer history, and permissions.
  • Notify users when a new file is received.
Originally created by @aliamerj on GitHub (Jul 23, 2025). Original GitHub issue: https://github.com/netbirdio/netbird/issues/4204 Implement a Taildrop-like file transfer feature for NetBird, we need to create a secure, peer-to-peer file-sharing system that integrates naturally into NetBird’s infrastructure allowing users to send files between their personal devices on a Netbird network. ## Overall Implementation Core Logic: ### Build the file transfer functionality to work over NetBird’s peer-to-peer connections. - **Platform-Specific Code**: - **macOS/iOS/Android**: Integrate with the share menu (e.g., “Share via NetBird”). - **Windows**: Add to the share context menu or NetBird client interface. - **Linux**: Develop a command (e.g., `netbird send <file> <device/ peer-id>`) ## TASK 1: File Transfer Activation, Permissions, and Default Save Path In this first step, I’ll implement the core logic for peer-to-peer file transfer inside the NetBird agent — following a model similar to SSH’s controlled file copy behavior. ### 🧩 What I’ll Do - **Introduce a new management-side config flag (e.g., `enableFileTransfer: true`)** - that governs whether the agent is allowed to participate in file transfer at all. - This is synced to the agent and acts as a hard gatekeeper If disabled, the feature is entirely inactive regardless of CLI flags or user actions - Agent Startup Check: - On startup, the NetBird agent checks the management config for the `EnableFileTransfer flag`. - If disabled, the feature remains entirely off — no listeners, no UI, no CLI options exposed. - **Local Listener with Optional Runtime Signal** Once management has enabled it, the agent can start a local listener for file transfer requests: - Either automatically on startup (based on CLI/config flag like` --file-transfer`) - Or dynamically triggered at runtime via a dedicated internal signal message (e.g., `start_file_transfer_listener`) - **Protobuf-Based Control Messages** (used in peer-to-peer communication) to support new message types for file transfer: - `file_offer` → initiate - `file_accept` / `file_deny` - `file_meta` → metadata (size, name) - `file_chunk` → actual data - `transfer_complete` / `transfer_error` - **User Authorization Flow** — When someone tries to send a file: - Receiver gets a request with file metadata (size, name, sender) - Receiver must approve via CLI/desktop UI - Optionally allow auto-accept from trusted peers via config - **Default Save Path via Agent Settings** - Add support for a default download directory (e.g. `~/NetBirdTransfers`) - Allow override via CLI flag or agent config - **Handle file streaming over the established tunnel**: - Once approved, file chunks will be streamed directly over the existing encrypted tunnel using a TCP/Unix socket connection negotiated internally. - No extra open ports - Data stays within the mesh tunnel - Uses same NAT traversal as other NetBird traffic - **CLI prototype for Linux to send and receive files using the command**: ```bash netbird send <file-path> <peer-id> ``` - Works only if both peers are management-enabled and listening - Prints real-time status in teminal ## TASK 2: Cross-Platform File Sharing UX Integration Now that we have the internal file transfer logic working (from Task 1), this task focuses on making it usable and accessible across major platforms by integrating with native OS interfaces. ### 🧩 What I’ll Do - Linux ( already done in Task 1) - Extend the CLI UX (from Task 1) with optional interactive prompts. - Optionally create a minimal GTK or terminal UI to make selection easier. - macOS / iOS / Android - Create component (i.e. "Share via NetBird"). - When a file is shared, it triggers a background call to netbird send <file> <target-device> using the CLI or internal bindings. - Windows - Add a menu item ("Send with NetBird") - Under the hood, it calls the same file-sending command. #### 🔁 How It Works Technically - All platforms will reuse the message handlers and transfer logic from Task 1 — no new protocol or backend work is needed. - UI or shell integrations simply act as wrappers around the core agent, either invoking a CLI command or talking directly to the local NetBird service (via Unix socket or similar, if exposed). ## TASK 3: Nice to have - Add optional settings like transfer history, and permissions. - Notify users when a new file is received.
Author
Owner

@aliamerj commented on GitHub (Jul 23, 2025):

The goal in mind is to allow users to send files between their own devices over the existing encrypted tunnel, no extra ports or infra, but i am thinking now what if the user try to send big files is this will this bloat the agent?
Is it better to have extra port for this feature ? Any risks or architectural concerns I'm overlooking?

<!-- gh-comment-id:3107873059 --> @aliamerj commented on GitHub (Jul 23, 2025): The goal in mind is to allow users to send files between their own devices over the existing encrypted tunnel, no extra ports or infra, but i am thinking now what if the user try to send big files is this will this bloat the agent? Is it better to have extra port for this feature ? Any risks or architectural concerns I'm overlooking?
Author
Owner

@1nerdyguy commented on GitHub (Jul 23, 2025):

Is this a feature really needed/asked for?

Netbird already supports secure file transfers. It's called using whatever file transfer protocols you're already using, and doing it via the Netbird tunnel.

I worry this is a bit of scope creep into a region that shouldn't need to be done?

<!-- gh-comment-id:3108900855 --> @1nerdyguy commented on GitHub (Jul 23, 2025): Is this a feature really needed/asked for? Netbird already supports secure file transfers. It's called using whatever file transfer protocols you're already using, and doing it via the Netbird tunnel. I worry this is a bit of scope creep into a region that shouldn't need to be done?
Author
Owner

@nazarewk commented on GitHub (Jul 23, 2025):

I think this is more on the side of user experience/convenience and spreading adoption of good practices.

"How do I send a secret/sensitive file securely to coworkers?" seems to be the most prevailing and least addressed issues in my career.

Keeping that in mind, I would omit any scope creep of the feature beyond the bare minimum:

  • don't bother with local file history
    • just log it as an Audit Event with filename, size and hash of the file
  • always create the least privileged file on the given platform:
    • scoped to the user account accepting the transfer
    • put into whatever download/temporary directory is writeable
  • make it run by default & have an opt-out
    • otherwise people might not bother setting it up and therefore might not serve it's purpose
    • make opt-out both enforced company-wide and a separate machine-scoped

I'm not sure it should be convenient to share large or many different files through it at all, could probably do a double-acceptance of files larger than X MB with additional warning and omit handling multi-file transfers completely.
It should be thought of as a primary mode of sharing sensitive files, not just any files (photo albums, movies etc.)

<!-- gh-comment-id:3109354215 --> @nazarewk commented on GitHub (Jul 23, 2025): I think this is more on the side of user experience/convenience and spreading adoption of good practices. "How do I send a secret/sensitive file securely to coworkers?" seems to be the most prevailing and least addressed issues in my career. Keeping that in mind, I would omit any scope creep of the feature beyond the bare minimum: - don't bother with local file history - just log it as an Audit Event with filename, size and hash of the file - always create the least privileged file on the given platform: - scoped to the `user` account accepting the transfer - put into whatever download/temporary directory is writeable - make it run by default & have an opt-out - otherwise people might not bother setting it up and therefore might not serve it's purpose - make opt-out both enforced company-wide and a separate machine-scoped I'm not sure it should be convenient to share large or many different files through it at all, could probably do a double-acceptance of files larger than X MB with additional warning and omit handling multi-file transfers completely. It should be thought of as a primary mode of sharing sensitive files, not just any files (photo albums, movies etc.)
Author
Owner

@1nerdyguy commented on GitHub (Jul 23, 2025):

I agree on the proposed setup there, and the reasoning why.

I guess I worry about becoming the 'everything for everyone' kind of problem we see in other products, and instead just focus on the core of Netbird

<!-- gh-comment-id:3109387026 --> @1nerdyguy commented on GitHub (Jul 23, 2025): I agree on the proposed setup there, and the reasoning why. I guess I worry about becoming the 'everything for everyone' kind of problem we see in other products, and instead just focus on the core of Netbird
Author
Owner

@afonsofrancof commented on GitHub (Nov 24, 2025):

I use taildrop all the time and it is super convenient.

I think the scope creep argument doesn't work that well in this scenario because of SSH and RDP being a thing in netbird already. For those two protocols you could already do the manual way of just using an SSH or RDP client via the tunnel, but netbird makes it much easier to use.

Cross-system file sharing is somehow still an unsolved problem in 2025, so, for those using netbird, I really think this is a good feature to have.

<!-- gh-comment-id:3572645945 --> @afonsofrancof commented on GitHub (Nov 24, 2025): I use taildrop all the time and it is super convenient. I think the scope creep argument doesn't work that well in this scenario because of SSH and RDP being a thing in netbird already. For those two protocols you could already do the manual way of just using an SSH or RDP client via the tunnel, but netbird makes it much easier to use. Cross-system file sharing is somehow still an unsolved problem in 2025, so, for those using netbird, I really think this is a good feature to have.
Author
Owner

@afonsofrancof commented on GitHub (Feb 20, 2026):

Since my last comment, Netbird seems to be evolving into a larger-scoped project (reverse-proxy was just added, for example).

Practically speaking, a new file sharing solution (specially one in Netbird, that doesn't need the devices to be on the same physical network) is a far more common need than reverse proxying ( most people already have a reverse-proxy, but very few have reliable and simple file sharing).

Can we take another look at this feature request? (Not asking for this to be developed, just asking if it can be "accepted" so someone can work on it if they want)

<!-- gh-comment-id:3936646389 --> @afonsofrancof commented on GitHub (Feb 20, 2026): Since my last comment, Netbird seems to be evolving into a larger-scoped project (reverse-proxy was just added, for example). Practically speaking, a new file sharing solution (specially one in Netbird, that doesn't need the devices to be on the same physical network) is a far more common need than reverse proxying ( most people already have a reverse-proxy, but very few have reliable and simple file sharing). Can we take another look at this feature request? (Not asking for this to be developed, just asking if it can be "accepted" so someone can work on it if they want)
Author
Owner

@semp26 commented on GitHub (Jun 18, 2026):

I would also love to see this in netbird.

An idea i've had as well was to maybe implement a way of downloading files offered on the netbird mesh via a browser UI so I could initiate the sharing and then just send a download link to a the recipient. This would be kind of like a Bitwarden send and should not add that much overhead since features like the reverse proxy now exist.

Using the proxy one might also be able to share a file with clients that are not part of the current netbird mesh.

<!-- gh-comment-id:4738240517 --> @semp26 commented on GitHub (Jun 18, 2026): I would also love to see this in netbird. An idea i've had as well was to maybe implement a way of downloading files offered on the netbird mesh via a browser UI so I could initiate the sharing and then just send a download link to a the recipient. This would be kind of like a Bitwarden send and should not add that much overhead since features like the reverse proxy now exist. Using the proxy one might also be able to share a file with clients that are not part of the current netbird mesh.
Sign in to join this conversation.
No Label
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: DYNR/netbird#8700