# Notifications & Inbox

Swarmfile tells you when something needs your attention - an upload failed, a file you have was changed by someone else, someone mentioned you in a comment - rather than leaving you to notice it yourself. Notifications are per-user: everyone on the org gets their own, based on their own activity and preferences.

There are three surfaces, and they show the same events:

- **The web dashboard's notification bell**, with an inbox you can scroll back through.
- **Desktop App toasts** on the desktop, for the same events as they happen on the machine you're working on.
- **`swarmfile notifications`** from the CLI - `list`/`unread-count`/`read`/`read-all` against the same inbox, for a script or a headless machine that needs to check (or clear) what's waiting without a browser or the Desktop App open. See [the CLI reference](https://swarmfile.com/docs/cli/swarmfile#notifications).

## What generates a notification

You'll get a notification for:

- **A failed upload** - a save that couldn't be uploaded after retries. Because saving is asynchronous, this is how you find out something didn't land from anywhere; in the Desktop App the header also counts failed changes until they're dealt with (see [Working with Files](https://swarmfile.com/docs/guides/working-with-files)).
- **Quarantine** - the *applied* notice goes to the org's owners, deliberately not to the quarantined account; the person released gets the release notice. If your own saves start being refused, the Desktop App's "Why did my save fail?" shows the reason. See [Security](https://swarmfile.com/docs/admin/security) for what triggers quarantine.
- **A quota or billing block on upload** - an upload refused because the org hit a storage limit or has a lapsed subscription, so you know why writes started failing rather than seeing an opaque error.
- **A file you have was changed by someone else** - the project-wide "someone edited this" signal.
- **Comments and `@`-mentions** - a new comment on a file, or someone tagging you specifically.
- **Watched files and folders** - a change to something you explicitly subscribed to with [watch](https://swarmfile.com/docs/guides/sharing-and-collaboration).
- **Unlock requests** - someone asking you to release a lock on a file you're holding.
- **Merge Request activity** - one opened, reviewed (approved, changes requested, or just commented on), merged, closed, or reopened; a draft becoming ready for review; you being assigned, asked to review, or unassigned (and a review request withdrawn); and labels being added or removed. See [Branches & Merging](https://swarmfile.com/docs/guides/branches-and-merging#merge-requests).
- **A hosted-CI run failing** - the run's starter is told when a run ends in failure (a timeout, a cancel, a queue expiry, a blocked start or an infrastructure fault included); on a protected branch the branch's recent committers get it too. Bell/tray and the personal webhook, not email. See [Hosted CI](https://swarmfile.com/docs/guides/hosted-ci).
- **A project nearing its storage limit** - sent to the org's owners and admins when a project's file information and history pass the early-warning mark, again if new files and versions get paused at the limit, and once more when it recovers. The project's **Metadata** tab explains what to do. See [Project storage limit](https://swarmfile.com/docs/admin/operations#project-storage-limit).
- **A teammate asking for git access** - sent to the org's owners and admins when someone tries `git clone`/`git push` on a project that hasn't been enabled for git yet. It arrives once per project, not once per attempt, and names the fix: [Clone a project with git](https://swarmfile.com/docs/guides/git-clone#turning-on-git-access).
- **Your org's dedicated storage finishing provisioning** - sent to the person who enabled the switch (or created the first project on a paid plan) when the bucket is live, since that can complete well after the request returned. See [Dedicated Storage Isolation](https://swarmfile.com/docs/admin/dedicated-storage).
- **Your org's request budgets or spend cap changing** - the org's owners and admins get a bell/tray notice when an owner or admin changes the org's request budgets or [spend cap](https://swarmfile.com/docs/admin/billing-and-plans), including when a spend-cap threshold is crossed or a metered write is refused. Bell/tray only; the Activity feed and audit log are the trail.
- **A commit dispute**: two derivations of the same commit disagree. The org's owners and admins are told (bell/tray only) while git holds that commit back, and told again when Swarmfile settles it on its own, usually within a minute or two. When a differing derivation arrives for a commit that is already confirmed, the notice says the confirmed commit is still served and nothing is held back. See [Clone a project with git](https://swarmfile.com/docs/guides/git-clone).
- **An org webhook being auto-disabled** - when a webhook is turned off after repeated delivery failures, the org's owners and admins are told by bell and email. See [Webhooks](https://swarmfile.com/docs/admin/webhooks).

One event is desktop-only: when a found update has sat uninstalled for a week, the Desktop App raises a one-time notification reminding you. It doesn't appear in the bell or by email, and nothing ever installs on its own - see [Release Channels & Updates](https://swarmfile.com/docs/reference/release-channels-and-updates).

## Email notifications

Some notifications can also be delivered by email, so an important one reaches you when you don't have the dashboard open or the Desktop App running. The email-able events are the ones you'd want to know about while away from your desk: **failed uploads, quarantine (the applied notice to owners, the release to the affected user), a quota/billing block, a file changed by someone else, a public access request or public RFI filed on a project you own or administer, comments, `@`-mentions, being assigned to a merge request, having your review requested on one, having changes requested on one you opened, RFI/submittal activity (created, assigned, response posted, revisions requested, due soon, overdue, closed, voided, and the ball-in-court digest), a project nearing or hitting its storage limit, an org webhook being auto-disabled, and your org's dedicated storage finishing provisioning.** Every other Merge Request event - it being opened, approved, merged, closed, or reopened - stays bell/toast-only; those happen often enough on an active project that emailing every one of them would be noise, not signal.

Watched-file changes and unlock requests are **in-app only** - they show in the bell and as Desktop App toasts, but aren't emailed.

Email is on by default for the events listed above, with two exceptions: **"a file you have was changed by someone else"** and **new comments on a file** ship muted - on an active project those fire for ordinary teammate activity, and emailing every one of them is noise. The bell still records both. You control every kind individually, so you can turn those two on, or mute others; mentions, failed uploads, quota blocks, quarantine and the other attention kinds stay on unless you mute them.

### Quiet hours

You can set a quiet-hours window - a start and end time in your own timezone - during which we won't email you, so an overnight render failure doesn't wake you. A notification raised during quiet hours still appears in the in-app inbox immediately; only the email is suppressed for the window.

### Where to configure it

Email preferences live in the web dashboard's **Settings → Notifications**: the master on/off switch, quiet hours, your timezone, and the per-kind toggles (including the RFI/submittal kinds, each of which can be muted without touching the rest). The table lists every notification kind - kinds that never send email (watched-file changes, unlock requests, MR opened/merged/closed/reopened, CI runs, and the other bell-only events listed above) show a dash in the Email column, and a configured personal webhook is their per-kind control. Set them once and they apply to your account across every machine you sign in on. `swarmfile notifications preferences get`/`set` reads and writes the on/off switch, quiet hours and timezone from the CLI (clearing either of the latter is dashboard-only - the CLI has no null form), and `preferences set --kind file_changed_by_other=off` sets a per-kind override (repeat `--kind` to set several; `default` clears that kind's override - email and webhook - back to the kind's defaults: the master switch plus that kind's own default, which is off for the two high-volume kinds above and on for the rest). The dashboard remains the friendliest place to see them all at once.

## Personal webhook

A third delivery surface, alongside the bell and email: a signed HTTP callback to a URL only you configure, with the same per-kind mute controls email already has. It's a fire-and-forget best-effort channel - no delivery log or retry, held to the same bar as email rather than the fuller treatment an org-wide webhook gets. See [Webhooks](https://swarmfile.com/docs/admin/webhooks) for setup and how to verify the signature. One asymmetry worth knowing: a per-kind email override turns that kind's email on even when the email master switch is off, but the webhook's own on/off switch is a hard gate - its per-kind rows only apply while the webhook is enabled.

## Notifications vs. the activity feed

The notification inbox is **yours** - the events relevant to you personally. It's distinct from the org **Activity** feed, an org-wide audit log open to any member (ACL-filtered - you see events on entries you can read; quarantine incidents and org-policy events stay owner-only within it). Its CSV export is more restricted still: owner-only, and it needs the Pro plan's `audit_log` entitlement. If you're looking for a complete record rather than your own attention queue, that's [Operations → Audit log](https://swarmfile.com/docs/admin/operations), not this.

That Activity feed is the same stream wherever you meet it - three surfaces onto one feed:

- **The web dashboard's Activity view** - the full, scrollable, ACL-filtered record described above.
- **The Desktop App's activity feed** - the right-rail, cross-machine feed of what's happening in the project you're currently working in. Scoped to the active project rather than the whole org, it's the at-a-glance version for while you're at your desk. Runs of the same person doing the same thing collapse into one row you can expand; updates to system files (`.DS_Store`, Office lock and temp files, macOS safe-save `*.sb-…` leftovers) stay hidden behind a **Show system-file updates** toggle rather than being deleted. If you select a file, the feed narrows to that file's events.
- **`swarmfile activity` (`list` / `export` / `tail`)** - the terminal equivalent: `list` is point-in-time, `tail` follows the feed live (by polling), and `export` writes the owner-only CSV. See [the CLI reference](https://swarmfile.com/docs/cli/swarmfile#activity).

Same events underneath; pick whichever surface fits what you're doing.

> Not to be confused with [`swarmfile tail`](https://swarmfile.com/docs/cli/swarmfile#tail), which streams the engine's **local** event bus for the mounted project (comments, watched-file changes, lock conflicts) rather than this org-wide Activity feed.

## Where to go next

- [Sharing & Collaboration](https://swarmfile.com/docs/guides/sharing-and-collaboration) - comments, mentions, and watch, which are what generate most notifications.
- [Working with Files](https://swarmfile.com/docs/guides/working-with-files) - asynchronous saves and the upload queue, which the failed-upload notification reports on.
- [Webhooks](https://swarmfile.com/docs/admin/webhooks) - the personal webhook channel in full, plus the org-wide version an owner can set up.