Cloning a repository
A Git repository fills a workspace rather than landing in a folder inside one, so the workspace root is the repository root. On an empty workspace, choose Clone from GitHub — on the empty state, or under File actions — and pasteowner/repo or the repository’s URL. To bring a repository into a workspace that already has files, create and switch to a new workspace, then clone from its empty file explorer. The clone option only appears while a workspace is empty. Hidden files count, apart from leftovers Qualia knows are safe to clear (.DS_Store, .ipynb_checkpoints, .ipython); turn on Show hidden files to find any others. If a clone is refused, the message names what is in the way.
Cloning defaults to Latest commit only, which is much faster; turn it off when you need history. Cancelling part-way removes what had arrived, so the workspace is empty again. The repository’s .git folder is hidden from the file tree and skipped by search like other dot-folders. Private repositories need GitHub access — see MCP integrations.
Downloading files and folders
Right-click a file or folder and select Download. Large files are delivered through cloud storage instead of passing through the app, so downloads are not limited by the smaller in-app file-reading ceiling.- In cloud-storage-backed workspaces, a file download starts immediately.
- In hosted workspaces, a large file is prepared first. Keep the app open while the progress toast is visible; the download starts when preparation finishes.
- A folder is prepared as
<folder>.zip. Folder archives include regular files, omit symbolic links and workspace metadata or credential files, and report skipped entries when complete. - One file or folder download can prepare at a time per workspace. If transfers are busy, wait briefly and retry.
Prepared downloads remain available for a limited time. Starting the transfer before the link expires is enough; an in-progress download can continue afterward.
Uploading files
Add files to the workspace by dragging them from your machine into the file tree, or with File actions → Upload files. Folders can be dragged in the same way, or chosen with File actions → Upload folder — see Folder uploads. Dropping onto a folder uploads into that folder; the toolbar actions upload into the workspace root. While an upload runs:- A progress toast shows how many files have finished. Where the workspace uploads straight to cloud storage it also shows an overall percentage, plus throughput and an estimated time remaining for large uploads. On a hosted workspace that percentage covers the whole journey — the upload and the transfer into the workspace that follows it — so it no longer reads 100% while the second half is still running. You can dismiss the toast without affecting the upload.
- A thin progress line runs along the bottom of the Files header, so the upload stays visible while the section is collapsed.
- Each incoming file appears as a placeholder row at its destination and turns into a real file once it lands.
- Cancel upload stops it, either from the Files header or from the toast. Files that had already been handed over to the workspace stay; anything still in transit is discarded, and the toast reports how many made it. On a hosted workspace, where files are transferred into the workspace after uploading, a file whose transfer had not been handed over yet does not arrive at all.
- A single file can be cancelled on its own from the × on its placeholder row — the rest of the batch keeps uploading. The × is offered while the file is still in transit; once its row shows Confirming…, the bytes have been handed over and only the whole-upload cancel above still applies.
- A file whose transfer fails is retried automatically, and the toast names it while that happens (
Retrying data.csv…). This is the transfer being reattempted, which is different from the Retry sync below — that one asks the workspace again for a file whose bytes are already stored.
Switching workspaces mid-upload
An upload belongs to the workspace it started in, so opening a different folder or workspace waits for the one in flight to stop first — otherwise a single batch could end up split across two workspaces. Files already transferred stay where they were sent, and the toast says so. If an upload will not stop promptly, the switch goes ahead without it after a few seconds and reports what had finished by then.Uploading a file whose name already exists does not overwrite it. The server keeps both by renaming the new one (
data.csv becomes data (1).csv), and the upload toast tells you when this happened.Large uploads
Hosted workspaces upload straight to cloud storage, so a single file can be substantially larger than the relayed path allows — tens of gigabytes, with the exact ceiling set per deployment. A workspace that is a folder on the machine running Qualia has no such ceiling either: the file is copied into place rather than relayed, so its size is bounded by free disk space, and the toast says so if the disk fills. Only a workspace that runs elsewhere without cloud storage relays the file through the app, which caps a single upload at a few hundred megabytes and reports the limit on the toast when a file is too large. Very large files are sent in pieces rather than as one transfer, which mostly matters when something goes wrong: a network blip re-sends the affected piece instead of restarting the file. Such a file also uploads on its own rather than alongside others, since it already uses the whole connection — expect the toast to work through a batch of large files one at a time. Large uploads can take time to finish after all bytes have been sent. Wait for the upload’s completion confirmation before using the file. In hosted JuiceFS workspaces, uploads go directly into persistent workspace storage, including files over 5 GiB. The usual deployment limit is 30 GiB per file. Uploads can finish even when the running compute environment has a read-only workspace copy; that copy refreshes after the file is stored. Existing files are preserved if another upload takes the same name while yours is in progress. If a remote deployment has no direct-upload support, Qualia checks the relay limit before sending an oversized file and shows the limit in the upload error. During a long upload the rest of the explorer stays usable — only the destination folder, the folders above it, and the incoming files themselves are held back from being renamed, moved, deleted, duplicated, or downloaded until the upload finishes. Closing the browser tab mid-upload asks for confirmation first, unless switching workspaces has already stopped waiting on a stalled upload.An upload this size is bounded by your own connection more than by anything in the app: at a typical home upstream rate, 20 GB takes on the order of a couple of hours. Once the transfer finishes, the file still has to be pulled into the running compute environment before it appears — see Still syncing — which for a file this large is minutes, not seconds.
Still syncing
After an upload finishes, a file can take a moment to become visible while the running compute environment pulls it in. Its placeholder row shows Syncing… during that window, and once the pull starts reporting, the row shows its progress as a ring instead — hover it for the exact percentage. For a large file this second transfer takes about as long as the upload itself, and the header’s progress line keeps advancing through it rather than sitting at the end. If a sync takes unusually long without reporting progress, the row offers Retry sync, which re-requests the sync and re-reads the folder. A few uploads cannot be re-requested and are left for the environment’s next sync pass instead. The file’s data is already safely stored either way.Folder uploads
Whole folder trees upload the same way individual files do: drag a folder from your machine into the file tree, or use Upload folder from File actions or a folder’s context menu. The folder’s structure is recreated at the destination. Some contents are skipped rather than failing the upload:- Dependency and scratch directories (
.git,node_modules,.venv,venv,__pycache__,.ipynb_checkpoints) and.DS_Storefiles are left out. - A file or folder the browser cannot read is skipped and the rest of the upload continues.