Droppy: self-hosted file management and sharing guide

Droppy is a self-hosted file manager that runs in your browser. Upload files and whole folders, browse them in a fast list that updates live, view photos, video, audio, PDFs and web pages, edit text and code, mark up images, unpack archives, and send share links with optional passcodes, custom addresses and visitor uploads. Administrators manage users and folder permissions from the same screen, and a command-line client (droppy_cli) handles scripted uploads, downloads and links. This guide covers droppy.micstec.com.

What you can do at a glance

Sign in

1. Open droppy.micstec.com. The sign-in page shows the Droppy logo, Username, Password and Sign in.
2. Enter the username and password your administrator gave you and choose Sign in. Usernames are not case-sensitive.
3. If the details are wrong you see Wrong login! Wait two seconds between attempts; faster retries are refused.

Sign-in is remembered on that browser. A session that is not used for about a month expires and you sign in again. Choose Sign out (the arrow at the far right of the toolbar) on shared computers.

You only see the folders your account can use. A normal account always has its own home folder named after the username (for example /alice), where you can read, write and share. The administrator can give you access to other folders, possibly read-only. Administrators see and can change everything.

Find your way around

• Path bar: the house icon is the top level; each folder name after it is a step back up. The browser's Back and Forward buttons also move between folders, and every folder has its own address you can bookmark.
• Open a folder: select its name. Open a file: select its name; it opens in the matching viewer, or downloads if it cannot be shown.
• Columns: Name, Type, Owner, Modified and Size. Select a column heading to sort by it; select it again to reverse. Droppy remembers the sort order for each folder on this browser. Folder sizes include everything inside.
• Row buttons: Share (link icon), Download (or Download zip for a folder), Delete (bin) and Actions (⋮). Right-clicking a row also opens the Actions menu.
• Empty folders show a cloud icon with Add files; select it to upload.
• Live list: uploads, edits and deletions by anyone appear automatically. Reload View forces a refresh.

Toolbar

Hover over a button to see its name.

Upload and create buttons are greyed out in folders where you cannot write.

Upload files

While uploading, a bar at the bottom of the list shows the percentage, the file name (or the number of files), the time remaining and the speed; the browser tab title shows the percentage too. Select ✕ on the bar to cancel. When the upload finishes in a background tab, Droppy can show a desktop notification (Upload finished) if you allow notifications.

If some files already exist, Droppy asks Overwrite Files — "Some uploaded files already exist. Overwrite them?". Choose Overwrite to replace them. To keep both versions, rename one of the files before uploading.

Name a pasted image

1. Copy an image (for example a screenshot), open the destination folder and press Ctrl+V, or choose Paste clipboard image.
2. In Save pasted image, keep the suggested pasted-image-<date-time>.png or type a name. If you leave out the extension, Droppy adds it.
3. Choose Save (or press Enter). Cancel (or Esc) discards it.

If the browser blocks clipboard access, Droppy says so — press Ctrl+V inside the folder instead.

File names cannot contain < > : " | ? * or control characters, cannot be . or .., and cannot be longer than 255 characters. Your administrator may also set a maximum size per file.

Create, rename, copy, move and delete

The Actions menu (⋮ on the row, or right-click) lists only what applies to the item:

• Create a file or folder: choose Create file or Create folder, type the name in the new row and press Enter. Esc cancels. The row shakes and turns red if the name is not allowed or already exists.
• Rename: choose Rename. The name without its extension is selected; type the new name and press Enter (or click elsewhere). Esc cancels. Renaming or moving an item keeps its share links working.
• Copy or move with the clipboard: choose Copy or Cut, open the destination folder, then choose the Paste here button that appears. If an item with the same name is already there, the pasted copy gets a new name.
• Delete: choose Delete (or the bin on the row). Confirm in Delete Item with Delete. There is no recycle bin, and share links to the deleted item stop working.

Work in two folders at once

1. Choose Create new View. A second pane opens on the same folder; browse each pane separately.
2. Drag a file or folder from one pane and drop it on the other pane's list.
3. A small menu offers Move, Copy or View (open the dragged item in that pane). Hold Ctrl, Cmd or Alt while dropping to copy straight away, or Shift to move.
4. Choose Close this view in either pane to go back to one pane.

Moving an item into the folder it is already in does nothing; copying a folder into itself is refused (Can't copy directory into itself).

Download files and folders

• One file: select Download on its row. Files Droppy cannot display (for example .docx or .exe) also download when you select their name.
• A whole folder: select Download zip on the folder's row. Droppy builds the ZIP on the fly, so the download starts immediately and has no size shown in advance.
• From the text editor or a rendered page: use DL / Download in that window.

Search

1. Select Search (magnifier) and type a word in Term.
2. Results appear after you stop typing for a second, or immediately when you press Enter.
3. The search covers file and folder names in the current folder and all folders below it. It ignores capitals and matches any part of a name. It does not search inside files.
4. Results show their path relative to where you searched; open, share or download them as usual. No results means nothing matched.
5. Press Esc in the box (or select the magnifier) to return to the folder.

View photos, video, audio and PDFs

Select a file to open it. Photos, videos and PDFs in the same folder form one gallery: the counter (for example 3 / 5) shows your position.

Keyboard: Space, →, ↓ or Enter for next; Shift+Space, ←, ↑ or Backspace for previous; F or Alt+Enter for full screen; Esc closes dialogs.

Supported types: photos — PNG, APNG, JPEG, GIF, BMP, ICO, SVG, WebP; video — MP4, M4V, MOV, WebM, MKV, OGV, 3GP and similar; audio — MP3, M4A, AAC, FLAC, OGG, Opus, WAV and similar; and PDF. Whether a particular video or audio file plays depends on your browser's codecs; if it cannot, Droppy says Your browser can't play this file — download it instead.

Video

Videos start playing on desktop (on phones, tap play). The player bar has play/pause, volume, a seek bar with time, mute, picture-in-picture, full screen and captions. If you close the viewer, switch tabs or switch apps while a video is playing, Droppy pops it into a small floating picture-in-picture window where the browser supports it, so you can keep watching while you browse. Playback also appears in your system's media controls.

Audio

Select an audio file (or Play in its menu). An audio bar appears at the bottom of the folder with volume (select the speaker to show the slider; the mouse wheel also adjusts it), previous, pause/play, stop, shuffle and next, plus the title, elapsed and total time. Click anywhere on the bar to jump to that point. When a track ends, the next audio file in the folder plays, and the list wraps around to the first.

PDF

PDFs open in the same viewer with every page drawn one under another. Scroll to read, use Zoom in / Zoom out, and download the original with the row's Download button.

Edit images

1. Open a photo and choose Edit image (pencil) in the viewer.
2. Use the toolbar:

All edits are applied at the image's full resolution. After saving, the viewer reopens on the updated image. JPEGs are saved with a white background where the image had transparency. If you cannot write to the folder, the editor shows Read-only: you have no write access here and saving is disabled.

Edit text and code

Select any text file (Droppy checks whether a file is text) or choose Edit in a file's menu. The sidebar on the right has:

While a file has unsaved changes, its name in the path bar is marked; after Save it briefly turns green (saved) or red (failed). The highlighting language is chosen from the file extension or a #! first line. The editor uses Sublime Text-style keys; Ctrl+Space comments or uncomments lines, and Tab indents with your preferred tabs or spaces. Windows (CRLF) line endings are kept. Change the theme, font size, indentation and wrapping in Preferences.

Render HTML and Markdown

Choose Render in the menu of an .html, .htm, .md or .markdown file. It opens in a floating window titled with the file name:

• drag the title bar to move it, and drag the bottom-right corner to resize it;
• Download, Fullscreen and Close are at the top right; Esc also closes it;
• the window does not block the list, so you can keep browsing behind it.

Markdown is formatted with headings, tables, code blocks and lists, and follows your system's light or dark setting; links open in a new tab. HTML pages load their own images, styles and scripts from the same folder, inside a sandbox.

Extract archives

1. Open the archive's menu and choose Extract.
2. Droppy shows Extracting …, then Extracted to and, if the tab is in the background, a notification.
3. If the archive contains a single top-level folder or file, it lands next to the archive. Otherwise a new folder named after the archive is created. Existing files are never overwritten — a clashing name gets a new one.

Supported: ZIP, 7z, RAR, TAR (including .tar.gz, .tgz, .tar.bz2, .tar.xz, .tar.zst and similar), CAB, ISO, CPIO and LZH/LHA, plus single compressed files (.gz, .bz2, .xz, .zst, .lzma). You need write access to the folder. The archive itself is kept.

Share links

Anyone who has a share link can open it without a Droppy account. You need share permission on the item (your home folder always has it).

1. Select Share (link icon) on a row, or Share in its menu. Droppy creates a short link such as …/s/aB3xK and selects it.
2. Use the options on the right:

3. Close the dialog by clicking outside it, then send the link. Send any passcode separately.

Good to know:

• Is DL starts in the state set by Preferences → Sharelink download (Default On unless you change it).
• Sharing the same item again with the same settings gives you the same link rather than a new one.
• Custom addresses are unique and not case-sensitive: /s/Holiday and /s/holiday are the same link. If one is taken you see Custom URL "…" is already taken.
• Changing a link's address breaks the old address; visitors to a locked link must enter the passcode again.
• A link stops working when you revoke it, delete the item, or lose access to it. Renaming or moving the item keeps the link working. A dead link sends visitors to the sign-in page.

What visitors see

• Locked links show Protected share — "Enter the passcode to view this shared item." — and Unlock. A wrong entry shows Incorrect passcode. After unlocking, that browser stays unlocked for that link (including its subfolders) until the passcode changes.
• Files open in the browser (photos, video, PDFs, text) or download, depending on Is DL. Shared Markdown files open as a formatted page.
• Folders open as a simple list with the folder path as clickable steps and a Download zip button; select a subfolder to go in, or a file to open it in a new tab.
• On the command line, curl -OJ <link> or wget --content-disposition <link> saves a shared file under its real name.

Collect files with an upload link

Administrators can let people send files to a folder without an account:

1. Share a folder, turn Is DL off, and tick Uploads. Optionally set a URL and a Lock passcode.
2. Visitors see Drop files here or click to choose. and an Upload button above the folder's list.
3. During the upload they see a progress bar with percentage, size, speed, time remaining and Cancel; afterwards Uploaded N files.

A visitor can send up to 50 files per upload, and one upload per second. Files whose names already exist are saved under a new name, so nothing is overwritten. Visitors can also see and download what is in the folder, so use a dedicated folder.

Manage your links

Open Preferences → Share Links. Each row shows the shared path, an Inline or Download badge, Locked for passcode-protected links, and the full address. The buttons are:

• Rename / set custom URL — type a new address and Rename (or Cancel);
• Set passcode / Change or clear passcode — Save a new passcode, or Remove it;
• Copy URL — copies the address (the tooltip briefly says Copied!);
• Revoke link — confirm in Revoke Link; the address stops working immediately.

You only see links you created. "No share links yet. Create one from a file's menu." means you have none.

Embed a share on another website

Site owners can open a Droppy share in a pop-up window on their own pages. Add <script src="https://<droppy-address>/!/res/embed.js"></script> to the page, then give any button the attribute data-droppy-share="<link-name>" (optionally data-droppy-title). Clicking it opens the share — including passcode and upload forms — in an overlay with Open ↗ and ×; Esc or clicking the backdrop closes it. Passcode-protected embeds need HTTPS.

Run server-side agents

Agents runs longer jobs on the server. Every signed-in user can use them, but only on folders they are allowed to use.

1. Open the folder you want to work on and choose Agents. Each agent's Folder field is pre-filled with that folder.
2. Adjust the fields and choose Run.
3. Under Recent jobs, each job shows queued, running, succeeded, failed or canceled and a summary. Select a job to show its log; select the stop button to cancel a running job. The list refreshes while jobs run.

Jobs are private to you and are lost if the server restarts. Processed files are never picked up twice because orig/ and compressed/ are skipped. Download or process only content you have the right to use. The list of agents on a given installation may differ; agents that need tools the server does not have will fail with a message in their log.

Preferences

Choose Preferences (gear). Changes save immediately; the window can be moved by its title bar on desktop.

General settings (stored in this browser):

Theme (light or dark) is switched with Toggle theme in the toolbar; Droppy starts with your system setting and remembers your choice on this browser.

API tokens

An API token lets droppy_cli or a script act as you, with exactly your permissions. Tokens start with drp_. Preferences → API Tokens lists your tokens (name, user, creation time); select the bin to revoke one (Revoke Token). The quickest way to create a token is droppy_cli login (see below), which signs in with your password and saves a new token; administrators can also create tokens on the server. A token's full value is shown only once. Token names are unique on the server, so a second laptop becomes laptop-2.

Users and permissions (administrators)

Open Preferences → Users & Access.

• Add a user: choose Add or update a user, enter the username and password when asked, then answer Make this user privileged? with Privileged (administrator) or Cancel (normal user). A normal user automatically gets a home folder /<username> with full access.
• Change a password: add the same username again with the new password.
• Delete a user: the bin next to the name, then Delete. You cannot delete yourself. The user's sessions and tokens are removed.
• Grant a folder: Grant folder under a user, type the folder path (for example /Projects), then answer Allow writes? and Allow share links?. Read access is always included.
• Change a grant: tick or untick R (read), W (write) and S (share). Unticking all three, or the bin on the row, removes the grant.

A grant covers the folder and everything inside it. Users see only the folders they have grants for, plus the path leading to them. Normal users can also create a new folder at the top level, which then belongs to them (shown in the Owner column). Administrators have full access everywhere, and only administrators can create upload-enabled share links. Share links stop working if their creator loses read or share access to the item.

Install and use on a phone

• Install: choose Install app in the toolbar when your browser offers it (Chrome, Edge, Android), or use the browser's Add to Home Screen (Safari on iPhone and iPad). The installed app opens full screen. On droppy.micstec.com it is named after the installation's app name, Micstec.
• Narrow screens show only Name and Size by default; change this with the Mobile … column preferences.
• Tap a name to open it; tap ⋮ for the Actions menu. Swipe through photos and pinch to zoom.
• Upload with Upload files from disk, which offers the camera and photo library. Keep the screen on and Droppy open until large uploads finish.
• Videos can continue in picture-in-picture when you switch apps, where the phone supports it.

The droppy_cli command-line client

droppy_cli (also built as droppy-cli) manages your files from a terminal or script over HTTPS, using an API token. Standalone binaries exist for Linux (x64, arm64), macOS and Windows; ask your administrator where to download one.

Sign in and profiles

droppy_cli login --url https://droppy.micstec.com   # asks for username and password
droppy_cli whoami                                   # active profile, server and user
droppy_cli ls /

login creates a token and saves it as a profile in ~/.droppy-cli/profiles/<name>.json (readable only by you). A profile holds one server, one user and one token, so you can keep several:

For scripts, DROPPY_URL and DROPPY_TOKEN (environment or a .env file), or --url and --token, override any profile.

Files

In browse: ↑/↓ move, Enter opens, Backspace goes up, n new folder, u upload, d download, r rename, m move, c copy, D delete, p go to a path, R refresh, ? help, q quit.

Share links

droppy_cli share /alice/report.pdf                    # inline link; prints the URL
droppy_cli share /alice/photos --download             # folder downloads as a ZIP
droppy_cli share /alice/report.pdf --slug q3-report --passcode "open-sesame"
droppy_cli share list                                 # 🔒 marks locked links
droppy_cli share rename q3-report q3-final
droppy_cli share passcode q3-final --clear
droppy_cli share revoke q3-final

Administrators can add --upload to a folder link (visitor uploads), or change it later with share update LINK --upload/--no-upload. Without --download, CLI links open as previews. Administrators also have user list|add|del|grant|revoke and acl.

A menu-driven helper, droppy_cli_tui.sh, wraps these commands with a Setup wizard, a Remote file browser, Server/Admin droppy commands, Profiles & login, Settings and a Command reference.

Run your own Droppy (administrators)

Droppy is open source (BSD licence, based on silverwind/droppy) and runs on Node.js or in Docker.

• Start: droppy start -c /srv/droppy/config -f /srv/droppy/files. It listens on port 8989; put it behind HTTPS.
• First sign-in: a new installation creates the account admin / admin and immediately asks you to Set a new admin password.
• Server commands: droppy list, add <user> <pass> [p] (p = administrator), del, grant <user> <path> read,write,share, revoke, acl, and token add|list|revoke. In Docker run them with docker exec <container> droppy … -c /config -f /files.
• Useful settings in config/config.json: appName, readOnly (no changes allowed), public (no sign-in, read-only), maxFileSize, linkLength (default 5 characters), ignorePatterns and listeners (ports and TLS).
• Archive extraction needs bsdtar and 7z; the agents need tools such as ffmpeg, ImageMagick and yt-dlp on the server. The Docker image includes them.

Privacy and security

• Files stay on the Droppy server; Droppy does not send them anywhere else. Search engines are told not to index the site.
• Passwords and API tokens are stored only as salted hashes. Treat tokens like passwords and revoke any you no longer use.
• A share link is public to anyone who has it. Use Lock for anything sensitive, send the passcode through a different channel, and revoke links when you are done.
• Upload links let strangers add files; use a dedicated folder and review what arrives.
• The administrator of an installation can see every file on it.
• Sign out on shared computers.

Limits

FAQ

Can I recover a deleted file? Not from Droppy — there is no recycle bin. Ask the administrator whether the server is backed up.

Why can't I upload, rename or delete in a folder? You have read-only access there, or the whole installation is read-only. The buttons are greyed out or you see Permission denied.

Why does my share link download instead of opening? Is DL is on. Open the share dialog again and turn it off, or set Sharelink download to Default Off.

Do people need an account to open my link? No. They need only the link (and the passcode if you set one).

Can visitors change files through an upload link? They can add files; existing files are not overwritten.

Does search look inside documents? No, only at file and folder names.

Can I use Droppy offline? No. It needs a live connection to the server; the installed app is a shortcut to the website.

Troubleshooting