Docs › Sharing a worker's folder with the hub

Sharing a worker's folder with the hub

sparehand files makes one folder of a worker show up in the hub's Finder under the machine's name, so you can drag files to and from a build machine like any other folder. Everything is set up from the hub; you don't touch the worker.

sparehand files gaming-pc on         # share a new "Sparehand" folder in its home folder
sparehand files gaming-pc open       # connect it, add it to Finder's sidebar, open it
sparehand files gaming-pc            # is it on? where is the folder? anything risky?
sparehand files gaming-pc close      # disconnect it from Finder (eject); it stays shared
sparehand files gaming-pc off        # stop sharing (the folder and its files stay)

The folder appears on the hub at ~/Sparehand/gaming-pc and in Finder's sidebar under Favorites. The first open adds the favorite; later ones put it back if Finder dropped it.

Choosing another folder

sparehand files gaming-pc browse                    # the folders in its home folder
sparehand files gaming-pc browse ~/Music            # or any other folder
sparehand files gaming-pc mkdir ~/Projects/shared   # make one
sparehand files gaming-pc on ~/Projects/shared      # share it instead

Write the folder the way the machine does (C:\Users\you\Music on Windows, ~/Music on Mac and Linux). One folder is shared at a time; sharing another replaces the first. On a Mac or Linux machine the folder must be in the home folder or on a mounted drive; on Windows it must be on a drive but not a Windows system folder (C:\Windows, Program Files, the root of C:...). System folders are refused.

What it does on each kind of machine

Setting up needs administrator rights on the worker once. On a Mac or Linux machine, sparehand files NAME on asks for that account's password in your terminal (the app has its own password box); it is sent over SSH and not stored. On Windows, the account Sparehand logs in with must be an administrator.

From any device: the dashboard's Files tab

The dashboard (also on a phone or tablet, through Tailscale) has a Files tab once a machine shares a folder: open folders, download a file by tapping it, upload files, make folders. It goes through the hub over the SSH connection Sparehand already uses, so the device needs no file-sharing sign-in, and it reaches only the shared folder: paths are resolved on the machine (.., links) and anything outside the folder is refused. Files can also be dropped onto the list to upload them, and each row has Rename and Delete (a deleted file or folder is gone for good: there is no bin on the machine to get it back from). Uploading a name that is already there asks before it replaces the file; an upload you stop, or one the connection cuts short, replaces nothing (the machine keeps the file only when every byte arrived). The same from a terminal:

sparehand files gaming-pc ls ""             # list the shared folder (or "photos/2026")
sparehand files gaming-pc get notes.txt > notes.txt
sparehand files gaming-pc put report.pdf < report.pdf
sparehand files gaming-pc newdir photos
sparehand files gaming-pc rm photos/old.jpg          # a file, or a folder with what is in it
sparehand files gaming-pc mv notes.txt notes-2026.txt   # rename, within its folder

What it allows, and what it doesn't

• Windows: only the hub can connect; Windows' firewall refuses everyone else.
• Linux: Sparehand's share answers only the hub (hosts allow, and ufw when it's on). When Sparehand set Samba up from scratch, the whole server answers only the hub; when Samba was already configured, your other shares keep their own settings.
• Mac: File Sharing answers anyone on your network, like any Mac with File Sharing on. They still need that Mac's username and password, and guests are refused. To limit it further, use the Mac's firewall (System Settings → Network → Firewall).
• The connection is encrypted (SMB encryption is required).
• Only the chosen folder is shared, never the whole disk, and system folders can't be chosen.
• off removes the share, the sparehand-files account, the firewall rule and the saved password, and disconnects the folder on the hub. Files in the folder are never deleted.
• If the worker's address changes, run sparehand files NAME on again so the firewall follows.
• A hub that isn't a Mac can set shares up, but open only prints the address to connect to (smb://...) and the user name; the generated password is kept in ~/.local/state/sparehand/files/NAME.secret.
• sparehand files NAME warns about other shares on the machine that guests can open without a password, and lists other shares it finds.

Troubleshooting

• "needs the password" / "needs administrator rights": run the command in a terminal on the hub (it asks), or use an administrator account on the worker.
• "wrong password": the worker account's password was mistyped; run it again.
• "isn't reachable": file sharing uses port 445 of the worker's address. Check the cable or network, and that the machine is awake.
• "the sign-in isn't in this Mac's Keychain": run sparehand files NAME on again; it makes a new password and saves it.
• The folder is empty or stale in Finder: sparehand files NAME open reconnects it.
• Linux: "setting up Samba failed": the machine needs a supported package manager and internet access to install Samba, or install samba yourself first.
• "that folder can't be shared": pick a folder in the home folder or on a drive; see sparehand files NAME browse.

See also security.md and adding-a-worker.md.