Working with files in your instance

Every Syncropel instance has a filesystem — a place for your working files, published artifacts, connected drives, and files derived from your threads. The command-line guide covers managing it from your terminal. This guide covers the same filesystem visually, through the Files tab on your instance.

The Files tab is the same filesystem you reach with spl fs — anything you do here shows up there, and vice versa.

Open Files

Open your instance in a browser and click Files in the navigation rail. On mobile, tap the Files icon in the bottom navigation.

You'll see two columns:

• The tree on the left — the four areas of your filesystem (/files, /artifacts, /mnt, /threads), each expandable, with a Recent list at the top of the most recently opened files.
• The viewer on the right — empty until you pick a file. Once a file is open, the viewer renders it according to its type (markdown, code, images, PDFs, CSV tables, plain text, JSON, and more).

On mobile, the tree appears as a drawer and the viewer fills the screen when a file is open.

Browse

Click any folder to expand it. Click a file to open it in the viewer. The URL updates to include the open path, so you can copy and share a deep link to any file — opening that link drops you straight into the viewer.

When you navigate away and come back, the file you last had open is restored automatically, so you don't have to dig through the tree again.

View a file

Picking a file in the tree opens it on the right. The viewer chooses how to render based on the file's type:

Every viewer has a Download button to save the file to your computer, and a close (×) button to clear the selection.

Edit a file

Click Edit in the viewer chrome to switch into the editor. Editable kinds are markdown, code, JSON, CSV, and plain text — images, PDFs, and other binary files have no editor (replace them by uploading again instead).

The editor opens with your file's contents and the cursor ready. Code and JSON files get a real code editor with syntax highlighting, line numbers, bracket matching, find-and-replace, and undo/redo. Markdown and plain text get a simple text area.

Click Done to leave the editor and return to the viewer. Anything you typed is saved before closing.

Saving — how it works

You don't have to think about saving — your edits sync to your instance as you type. Concretely:

• Autosave — about 1.5 seconds after you stop typing, your changes save automatically. You'll see the indicator change from "Saving shortly…" to "Saving…" to "✓ Saved".
• Save now — if you want immediate confirmation, click the Save button or press ⌘S (macOS) / Ctrl+S (Windows / Linux).
• Saved on focus change — clicking outside the editor or switching to another browser tab saves any pending changes immediately. This is how mobile users save without a keyboard shortcut — tapping outside the editor area is enough.
• Saved on close — closing the editor (Done button) or the browser tab flushes a final save first.

The indicator next to the Save button always tells you the truth about unsaved changes:

Recovering unsaved work

If your browser quits unexpectedly while you were editing — a crash, a tab close, a connection drop — your unsaved changes are kept locally. The next time you open the same file you'll see a banner offering to Restore those changes (or Discard them).

When someone else changes the file

If another tab, another collaborator, or an agent writes to the same file while you have it open, your next save can't land cleanly — you'd unknowingly overwrite their changes. Instead, the editor shows a Conflict banner: your local edits stay on screen so you can copy them, and a Reload button discards them in favor of the latest version. Manually merge by copying your text aside first, reloading, then pasting.

Create files and folders

Right-click any folder in the tree to open a context menu:

• New file — opens an inline name input under the selected folder. Type the file name (e.g. notes.md, script.py, config.json), press Enter to create. The new file opens in the viewer; click Edit to start writing.
• New folder — same flow, but creates a folder.

The folder you right-clicked becomes the parent. To create at the root of /files, right-click the FILES heading.

Upload files from your computer

Drag any file from your computer's file manager onto the Files tab. As you drag over a folder, that folder highlights — drop to upload into it. Dropping on empty space in the tree uploads into the root of /files.

Uploads happen in chunks, so a large file resumes cleanly if your connection drops. An upload strip at the top of the tree shows progress; cancel or dismiss completed uploads from there.

Uploads are accepted only in /files and writable connected drives. Dropping on /artifacts or /threads is rejected (those are read-only).

Move files around

Drag a file (or folder) from one place in the tree to another. The destination folder highlights as you drag over it; release to move.

You can't move into /artifacts, /threads, or a read-only mount, and you can't move a folder into one of its own descendants — the editor catches both and shows a brief notice.

Rename and delete

Right-click any file or folder to Rename or Delete it.

• Rename — opens an inline input pre-filled with the current name. The filename part (before the extension) is selected so you can type a new one without retyping .md. Press Enter to commit.
• Delete — opens a confirmation dialog. Deleting a folder removes everything inside it.

Both actions use the file's current content as a safety check: if the file changed underneath you between when the tree last loaded and when you act, you'll see a notice and the tree refreshes.

/artifacts and /threads reject renames and deletes by design.

Quick find — ⌘K

Press ⌘K (macOS) or Ctrl+K (Windows / Linux) anywhere in your instance to open the quick-find palette. Type to filter; pick a result to jump straight to it.

Three sections appear in the palette:

• Commands — instance-level actions you can take.
• Threads — your recent threads, filtered by title.
• Files — your recently opened files, filtered by name.

Use the up/down arrows to move; Enter opens the highlighted result; Escape dismisses the palette.

Attach a file to a chat message

To reference a file in a thread, type @files in any chat composer. The quick-find palette opens in attach mode — pick one or more files (use Space to select multiple), then click Attach. The selected files appear as chips above the composer, and submitting the message attaches them to the record you emit.

The recipient of your message — another person, an agent, or an integration — gets a pin to the exact bytes of each file at the moment you attached it. Even if you later edit the file, the message stays pinned to that version.

You can also attach the file you're currently viewing without typing @files: every file viewer has a Use in chat button that adds it to your next message.

On mobile

The Files experience is built for small screens too, with one trade-off: mobile is optimized for checking files, not heavy organizing.

• The tree appears as a slide-up drawer. Tap Browse all files to open it from the Files screen.
• The default screen shows your recent files and any files an agent recently touched, so you can dive straight in without browsing.
• Editing works the same as on desktop — autosave, Save button, conflict handling all apply.
• The Save button is always visible in the editor chrome, so you don't need a keyboard shortcut.
• Tapping outside the editor area (the most natural "leave this screen" gesture) saves your changes.

For complex moves and reorganization, switch to desktop or use the command line. Mobile is the "read and quickly edit" surface; desktop is the "organize everything" surface.

Agent activity

When an agent writes to a file in your filesystem, the row gets a small accent dot in the tree. On mobile, those files also surface in a Modified by agent list above your recents. This lets you spot what your assistants have been doing without scrolling through threads.

What's next

• Files — the filesystem model: the four areas, the working-file → artifact lifecycle, and privacy.
• Working with files from the command line — the same filesystem via spl fs.
• Threads — where chat lives, and how attached files travel with your messages.