Files

Every Syncropel instance has a filesystem — a place to keep files. You browse it, upload to it, and organize it much like the filesystem on your own computer, except it lives with your instance and follows you wherever you reach that instance from.

Files are kept separately from records. Records are the small, immutable facts that make up your coordination history; files are the bytes — documents, datasets, images, exports. Keeping them apart means a large upload never slows down your record history, and your records stay a clean, fast log.

The four areas

The filesystem has four top-level areas, each with its own rules:

You'll spend most of your time in /files. The other three areas each have a specific job, described below.

Working files and artifacts

/files is your working area. Put anything there — a draft, a dataset you're cleaning, a report in progress. You can change or delete a working file at any time; nothing is fixed until you decide it is.

When a file is finished, you publish it. Publishing copies the file into /artifacts and gives it a permanent address based on its exact contents — a content hash. That address never changes and always points at exactly those bytes. An artifact is read-only: it can never be altered or quietly swapped, so it's safe to share, cite, or depend on.

# work on a file
spl fs cp ./report-draft.md /files/report.md

# when it's done, publish it
spl fs publish /files/report.md
# → published; content hash: 9565f5d1cf0a...

The working file stays in /files; the published copy is now an immutable artifact. Publishing draws a clean line between work in progress and finished, shareable output — you work freely in /files, then promote a file to something fixed when it's ready.

Connected drives

/mnt is where connected drives appear — external storage you mount into the instance so you can browse it alongside your own files. A connected drive shows up as /mnt/<name>, and whether you can write to it depends on the drive itself.

spl fs mounts lists the drives currently connected to your instance.

Files from your threads

/threads holds files that belong to your threads — attachments and outputs produced in the course of a conversation or a task. It is read-only: these files are a view of what your threads contain, and the thread is where they're actually managed.

Using your files

There are two ways to work with the filesystem:

• The command line — spl fs browses and manages the filesystem from your terminal: ls, cat, cp, mkdir, mv, rm, publish, and more. The command-line guide is a full walkthrough.
• The Files tab — when you open your instance on the web, the Files tab is a full visual browser AND editor: open and edit markdown, code, JSON, CSV, and text directly, drag files in from your computer to upload them, drag files between folders to move them, and right-click to create or rename. Edits autosave as you type, with a manual save shortcut and an always-visible Save button. The Files in your instance guide walks through it end to end.
• The SDK — read and write files from your own code with client.data.* in the TypeScript SDK: write (with safe compare-and-swap edits), read, list, publish, and search. The Files & blobs guide is the full walkthrough.

All three reach the same files. Anything you upload from the terminal is there in the Files tab and through the SDK, and vice versa.

Made by you

Every file remembers who made it and when. A file you create — from the terminal, the Files tab, or the SDK — reads as yours, not as something "adopted" from elsewhere. That authorship travels with the file: when you look at it later, or hand your instance to a teammate, the record of who produced it is right there. Files brought in from a connected drive or another instance carry their origin instead, so it's always clear where something came from.

Privacy

Your filesystem belongs to you. Each instance's files are isolated — reaching an instance gives you its filesystem, and only its filesystem. Browsing, uploading, and downloading all require a valid credential, exactly like the rest of the instance; see Authentication.

What's next

• Working with files from the command line — a hands-on walkthrough of every spl fs command, from your first upload to publishing an artifact.
• Working with files in your instance — the same filesystem in a browser: tree, viewer, editor, drag-upload, and quick find.
• CLI reference: Files — the complete spl fs command list.
• Files & blobs (SDK) — read and write the filesystem from your own code with client.data.*.
• Threads — the conversations and tasks the /threads area draws its files from.