Inter-Instance Transfer
Inter-Instance Transfer moves files and folders directly between your own QuickBox Pro instances, all from the dashboard. You pick what to send on one box, the receiving box reviews the request and chooses where it lands, and only then does the data stream across — verified per chunk, resumable, and encrypted in transit. No command line, no manual rsync, and no third-party relay.
Inter-Instance Transfer is an administrator feature and is disabled by default. It appears as Transfer under System in the sidebar only after an administrator has enabled the feature on the server. Both the page and every underlying action require administrator privileges.
Transfers are scoped to instances that belong to the same owner. You can only send to and receive from your own connected QuickBox instances. The server enforces this on every request, regardless of what is requested — there is no path to reach another customer’s box.
Key features
Multi-select send
Pick one file, a whole folder, or many files and folders across the tree, and send them as a single batch.
Approve before pull
The receiving instance reviews the offer and picks the destination — nothing moves until you accept.
Verified transfer
Per-chunk checksums and a whole-batch integrity check before any file is committed to its destination.
Resumable + live controls
Pause, resume, cancel, and re-cap bandwidth on a running transfer at any time.
Bandwidth + off-peak
Set a default bandwidth limit and an optional off-peak window so transfers stay out of your way.
Transfer alerts
Optional admin alerts when a request arrives, a send is offered, or a transfer completes or fails.
When to use it
Reach for transfer when…
- You are migrating a library from an old box to a new one
- You want to rebalance content across two of your own seedboxes
- You need to move a hand-picked set of files and folders in one batch
- You want a verified, resumable move that survives interruptions
- You prefer to drive the move from the dashboard, not the terminal
Use something else when…
- You are pulling from a remote you do not own — use rclone or a download client instead
- You want a continuous live sync rather than a one-time move
- You only need to move files within the same box — use the File Manager
Enabling the feature
Inter-Instance Transfer ships off. Until an administrator turns it on, the Transfer entry does not appear under System in the sidebar and the feature is unavailable.
An administrator enables it from Settings → General, with the Inter-Instance Transfer toggle. The setting is stored with all other runtime configuration in the database rather than in an environment file. Once enabled, Transfer appears under System for administrators and the workflow below becomes available.
Transfer works best when your instances are connected through the central directory, so they appear automatically in the recipient picker. If the directory is unavailable, you can still send by typing the destination’s instance id manually — the workflow does not depend on the directory being reachable.
The page at a glance
The Transfer page is organized into four tabs:
| Tab | What it does |
|---|---|
Send | Start a new transfer and watch your outgoing offers and their status. |
Incoming | Review, approve, or decline transfer requests arriving from your other instances. A badge shows how many are pending. |
History | A searchable, filterable, sortable record of every past transfer — both sent and received. |
Settings | Name this server, see your connected instances, and tune the transfer engine. |
The Send → Approve → Pull lifecycle
A transfer always flows the same way, and data only moves after the receiving instance approves it:
| Step | Where | What happens |
|---|---|---|
1. Offer | Sender | Choose the files and folders to send and the destination instance, then create the offer. Nothing leaves your box yet. |
2. Review | Receiver | The offer arrives in the Incoming inbox showing the sender, file count, total size, and any note. |
3. Approve | Receiver | Pick where the transfer should land, then accept. The receiver checks its own free space before approving. |
4. Pull | Receiver | The receiving box pulls the bytes, verifying each chunk and the whole batch before committing files to the chosen destination. |
The sender only makes an offer. The receiving instance does the actual pulling, which is why the destination is always chosen on the receiving side. Either side can cancel a transfer before it completes.
Sending files and folders
On the Send tab, choose New transfer to open the send dialog.
1. Choose the destination instance
Select one of your connected instances from the list, or type its instance id manually if the directory is not available. Instances are shown by their friendly name and an online/offline indicator.
2. Choose what to send
The file picker lets you build a batch — a “cart” of everything you want to send in one transfer:
- Check any combination of individual files and whole folders. Selecting a folder includes its entire contents.
- The running count and total size of your selection are shown as you go, and each item can be removed from the batch individually or cleared all at once.
- You can mix files and folders from different locations in a single batch. A batch can hold up to 5,000 items.
The picker offers two browsing modes:
| Mode | What you see |
|---|---|
My files | Navigate your own storage as a tree, confined to your home directory. This is the default for everyone. |
Browse the server | Navigate the wider server filesystem to pick a source. Available to administrators; how far it reaches depends on your access level (see below). |
When you switch to Browse the server, the picker shows files outside your own home directory and the dialog flags this clearly. Anything you check there will be sent off this server, so review your batch on the confirmation step before sending.
3. Choose where it lands on the remote
You can target the destination two ways (they are mutually exclusive):
- Deliver to a user (optional) — enter a username on the receiving server and, optionally, a subfolder under that user’s storage root. The username is verified by the receiving administrator when they approve. Leave it blank to deliver to your own storage root on the receiving server.
- Deliver to a path (administrators) — suggest an absolute path on the receiving server. This is advisory: it prefills the receiving administrator’s approval dialog, which still confirms or changes it before any data moves.
4. Pick a type and add a note
Choose a transfer type — Migration (move the content off this server) or Load balance (copy it to the other server to spread load) — and optionally add a note for the receiving end.
5. Review and send
Choosing Review & send opens a confirmation step that echoes exactly what will be sent, to which instance, where it will land, and the transfer type. Nothing is offered until you confirm here. The new offer then appears in Your outgoing transfers with a status badge and a Cancel action while it has not yet finished.
Receiving a transfer
Incoming requests arrive on the Incoming tab, where a badge shows the number of pending offers. Select Review on a pending offer to open the approval dialog:
- Review the request — the sender (shown by its name or instance id), file count, total size, any note, and the intended recipient if the sender addressed it to a specific user.
- Choose where it should land — pick a destination folder with the same picker used for sending. Administrators can switch to Browse the server to land the transfer at any folder they are permitted to reach. If the sender suggested a path, it is prefilled for you to confirm or change.
- Optionally set ownership — when the offer is addressed to a specific user, you can choose to hand the delivered files to that user once they are verified. This is off by default, which leaves the files service-owned.
- Accept & start to approve and immediately begin the pull, or Decline to reject the offer (with an inline confirmation).
A live progress view opens once the pull starts and survives a page reload.
Who owns the delivered files
Once a transfer completes, the delivered files are owned so that the right person can manage them without administrator help:
| Where it lands | Who owns the delivered files |
|---|---|
A user's storage (delivered to a user) | That user — so their apps and SFTP can use the migrated data immediately. |
A system path addressed to a specific recipient | The mapped recipient account — the migrated tree is theirs to move, manage, or delete normally. |
A system path with no recipient | The service account (the administrator owns the placement). Ownership can be re-applied to a chosen account afterward. |
When a migration lands in a user’s home, or lands at a system path but is addressed to a specific user, the delivered files are owned by that user. This means a migrated library is immediately manageable by the person who receives it — they never need root to reorganize or clean up their own data.
Live transfer controls
While a transfer is running, the receiving side can:
| Action | Effect |
|---|---|
Pause | Halts the running transfer; it can be resumed later. |
Resume | Continues a paused transfer from where it left off. |
Throttle | Re-caps bandwidth on the running transfer — applied mid-flight, no restart needed. |
Cancel | Aborts the transfer. Either the sender or the receiver can cancel before it completes. |
Live cockpit on the System Dashboard
Beyond the Transfer page, the System Dashboard carries a live Inter-Instance Transfers cockpit — a monitoring view of every transfer currently moving to or from this server. It complements this control page: you drive transfers (send, approve, pause) here, and you watch them at a glance from the cockpit.
The cockpit shows a summary strip (active transfers, aggregate speed, and bytes in flight), a live sender → receiver node-map of this server and its active peers, and a row per active transfer with the local user, direction, peer, size and percent complete, file count, elapsed time, average and live speed, and status. A Transfers page button jumps back to the full page, and — for peers that have opted in — a deep-link opens that peer’s own Transfers page.
The cockpit shows activity for this server and its paired instances — not a fleet-wide view. It is admin only, enforces same-owner scope, and shows peers by an opaque id or a friendly label, never by an address. See System Monitoring for the full panel reference.
Peer allowlist and Fail2Ban
A transfer moves data over a dedicated port between your two servers. A long or frequently-retried transfer can look like abuse to Fail2Ban and get the connecting server banned mid-flight, which would cut the transfer off. To prevent that, each end automatically allowlists the other server the moment a transfer is accepted, so paired servers never lock each other out.
Automatic on accept
When a transfer is accepted, both ends add the other server to the fail2ban allowlist for the transfer port — no manual step.
Persistent
The allowlist entry stays until an administrator removes it, so servers that transfer regularly never trip each other again.
This is handled entirely for you. For administrators who want to inspect or adjust the allowlist by hand, the same list is available from the command line with qb transfer peer-allow, qb transfer peer-deny, and qb transfer peer-list. See the qb transfer CLI reference for the full command set.
Allowlisting a peer only exempts its address from fail2ban on the transfer port. It does not grant any transfer authorization — the data path always requires a signed, single-use, expiring credential regardless of the allowlist.
Naming your servers
So you never have to recognize a server by a long opaque id, each instance can carry a friendly name. On the Settings tab, the Name this server section lets an administrator set the display name for the current instance.
Self-naming
You name your own server — the name you set is the name your other connected servers see for it.
Propagates automatically
The new name appears for this instance in your other instances' recipient pickers and history, instead of its raw id.
Enter a short name (up to 48 characters) and Save name. Clearing the field and saving reverts the server to its id-based default. You can only rename your own server, never one of your peers.
Transfer alerts
Administrators can be alerted to transfer activity through the dashboard’s notification system. The control lives on your Profile → Notification Settings page, under the Transfers group:
| Event | Alerts on | Default |
|---|---|---|
Transfer activity | An incoming request arriving, a send being offered, and a transfer completing or failing. | In-app on, email off |
The toggle is admin-only and, like every notification event, lets you choose which channels deliver it (in-app, and any other channels you have configured). Each alert deep-links straight to the Transfer page so you can act on it.
If you run frequent transfers and do not want an alert for each one, turn off Transfer activity under Profile → Notification Settings → Transfers, or limit it to in-app only.
History
The History tab is a complete, searchable record of every transfer that has touched your instances — both sent and received, in every state.
All statuses
Filter by Success, Paused, Cancelled, Failed, Declined, Active, or view All.
Both directions
Sent and received transfers in one table, each marked with its direction.
- Search by peer name, path, or note to find a specific transfer.
- Filter with the status chips across the top.
- Sort by peer, size, file count, status, or date by clicking the column headers.
- Page through results with the footer controls; the newest transfers are shown first by default.
Each row shows the direction, the peer (by its friendly name when known, otherwise its id), the total size, the file count, the status, and the date.
Throughput vs. host correlation
Open a completed transfer from the History tab to see a throughput-vs-host correlation chart. It overlays that transfer’s throughput against the host’s CPU, network, and disk-I/O utilization on a single time axis, so you can answer “was the transfer bottlenecked by the server?” — for example, throughput plateauing while disk I/O pegs at 100% points to the disk rather than the network as the limit. The disk-I/O series is drawn from the same durable metric the Telemetry History Store records, so the correlation stays available even after a restart.
Settings
Beyond naming your server, the Settings tab shows your connected instances and the tunable transfer engine.
Your instances
A list of your other QuickBox instances, each shown by its name, its instance id, and an Online / Offline badge. This is the same directory the recipient picker uses when you send a transfer. If no instances are listed, you can still send by entering an instance id manually.
Transfer engine
| Setting | Editable | What it does |
|---|---|---|
Default bandwidth limit | Yes | Bandwidth cap applied to new transfers — Unlimited, 5 MB/s, 25 MB/s, or 100 MB/s. Individual transfers can still be re-capped while running. |
Off-peak window | Yes | Optional daily time window (server local time) that restricts when transfers run. Toggle it on and pick a From / To hour. |
Chunk size | No (informational) | The size of each piece the engine pulls at a time. Shown for reference. |
Data port | No (informational) | The connection the data stream uses. Shows the dashboard default unless an operator has set a dedicated one. |
Saving sends only the settings you changed, and the new default bandwidth cap applies to transfers created after the change.
Who can do what
Inter-Instance Transfer is an administrator feature, and a few actions reach further the higher your access level:
| Capability | Who |
|---|---|
See and use the Transfer page at all | Administrators (once the feature is enabled) |
Browse your own files to pick a source or destination | Administrators |
Browse the server outside your home directory | Administrators — restricted from security-sensitive locations |
Browse the entire server filesystem | The highest access level (the operator account) |
When browsing the server, security-sensitive locations — credential, key, and operator-only directories — are kept off-limits to administrators. Only the operator account can reach the entire filesystem, and even then a built-in safeguard blocks secret-bearing paths.
Security and privacy
Inter-Instance Transfer is built so that neither the data nor the connection can be abused, and so that the two servers never learn more about each other than the move actually requires.
How the connection is secured
| Control | What it means |
|---|---|
Receiver-initiated pull | The receiving server dials the sender and pulls the data, so only the sender's address is ever needed and the receiver's stays private. A dropped connection resumes from where it left off, and the received data is checksum-verified. |
Single-use, 12-hour authorization | Each transfer is authorized by a cryptographically signed (Ed25519) grant minted by the QuickBox broker. The grant is single-use — consumed when the transfer completes — and expires after 12 hours: long enough to finish a large migration, but never a standing credential. |
Mutual TLS between the servers | Both servers pin each other's certificate fingerprint, carried inside the signed grant, so a stolen grant is useless to anyone who does not also hold the receiving server's private key. |
No address shown in the UI | The sender's endpoint travels only inside the signed grant. No screen — the Transfer page or the System Dashboard cockpit — ever renders a peer's IP, host, or port; peers appear as a friendly name or an opaque id. |
Because the connection is direct — no relay sits between your servers — the receiving machine necessarily learns the address it dials to reach the sender. That is unavoidable without adding a third-party relay, which the design deliberately omits. The privacy guarantee is that the other user never sees a peer’s address anywhere in the interface, and that a stolen authorization grant is worthless without the receiver’s private key. It is not a claim that the peer server never learns a reachable address.
Do
- Inter-Instance Transfer is gated by both an admin role and a server feature toggle — it is off until an administrator enables it.
- Transfers are restricted to the same owner. Every request is filtered to your own instances server-side, so you can never reach another customer's box.
- Data is only pulled after the receiving instance approves and chooses the destination — nothing is pushed unsolicited.
- The transfer travels over a secure, authorized, encrypted channel, and every piece is checksum-verified before the batch is committed to its destination.
Don't
- A peer's server address is never exposed in the dashboard — instances appear only by a friendly name and an instance id, so never expect to see or enter an IP address.
- In My files mode the picker is confined to your own storage — paths outside it cannot be selected, so do not expect to reach arbitrary locations there.
- Do not use transfer to reach a box you do not own — same-owner scope is enforced and there is no override.
Frequently asked questions
Related documentation
Configure transfer alerts and other notification preferences.
Command-line reference for the transfer peer allowlist.
Manage WireGuard and OpenVPN from the dashboard.
Manage uploads, backups, and brand assets.
Review dashboard and system activity.
Join the Community
Media server operators sharing configs, getting support, and shaping the future of QuickBox Pro.