# How Sponge works

Sponge has three parts: a computer that captures, a cloud account that carries text between your devices, and the places where you read. Each part does one job, and the split decides what Sponge can and cannot do.

```text
   Save a link                  Capture                        Read
   Chrome, Mac app, iPhone,     a computer running `sponge`    web library, Mac app, iPhone
   web Save, an agent           fetches the page and keeps     (each browser keeps its own
                                it in a local library          copy of the library)
        │                          ▲            │                    ▲
        └── save queue: the link ──┘            └── sync: text only ─┘
                         Sponge Cloud (account.sponge.computer)
```

## What each part does

| Part | What it does | What it holds |
| --- | --- | --- |
| A computer running `sponge` (macOS or Linux) | Captures articles and PDFs, runs local models, searches, exports, and builds your public pages | The library: a SQLite database and hashed files in `~/.local/share/sponge` |
| Sponge Cloud | Carries sync rounds between your devices, keeps the queue of links waiting to be captured, and serves the public pages your devices upload | Text only: saved Markdown, highlights, notes, reading state and summaries |
| The web library, the Mac app and the iPhone app | Reading, search, highlights, notes, filing and sharing | The browser's own copy of the library, in its private site storage |
| Sponge for Chrome, the Mac and iPhone share menus, the Clip API | Add a link to the queue | A save-only token that cannot read the library |

## Devices capture

Capture always runs on a computer you control. `sponge add URL --wait` fetches the page from that computer, extracts a readable copy, and writes it to the local library. Nothing is uploaded until you run `sponge sync`.

A link saved from anywhere else is a *save request*: an address waiting in your account. One of your signed-in computers claims it on its next `sponge sync`, captures it with the same pipeline, and syncs the result back. When several computers are connected, the cloud picks one to capture so they never race. If no computer is online, the link waits. [Ways to save](/docs/saving) lists every entry point.

Local models run on the same computers. Summaries, transcripts, CLI semantic search and the library map are produced there, and nothing you save is sent to an AI service. [Requirements and platforms](/docs/requirements) says which of these work where.

## The cloud holds synced text

`sponge login` connects a computer to your account and `sponge sync` exchanges changes. Sync carries captures, highlights, notes, reading state, summary drafts and reviews. It merges per field and keeps deletions, so two devices that edited the same item settle on one result.

The cloud does not hold everything:

- **Images are not downloaded.** A capture keeps each image's web address and the reader loads it from the publishing site, without a referrer.
- **PDF files do not sync.** A PDF with a public web address is kept as that address. A PDF from a local file or a signed-in session stays on the devices that already hold it.
- **Search indexes, model files, capture jobs, credentials and publishing keys stay local.**

The cloud keeps no searchable library of its own and runs no capture and no model. It stores the sync log and files, the save queue, account records, and the static public pages your devices upload.

## The browser is a device

The [web library](/docs/web-library) is not a view onto a server. A signed-in browser pulls the same sync rounds as the CLI and keeps its own SQLite copy in private site storage. Reading, keyword search, search by meaning and the highlights notebook all read that copy, so they work offline once it has loaded. An edit made offline waits in the browser and is sent when the connection returns.

Signing out removes the copy from that browser. A browser that cannot keep one, such as some private windows, cannot open the library.

The Mac app and the iPhone app show this same web library in a native window and add system ways to save.

## Without an account

An account is optional. The CLI captures, lists, shows, searches, highlights, exports and backs up a local library with no sign-in:

```sh
sponge add https://example.com --wait
sponge search "your topic"
sponge backup --output /absolute/path/library.sponge
```

The web library, the apps, the save queue and public pages need sync, and so an account.

## Limits to know

- Cloud copies are protected by TLS and the storage provider's protections. They are **not end-to-end encrypted**: the service can read synced text.
- An account syncs up to 4 GiB of text. The free plan holds 100 saved items in the cloud; see [Sponge Plus](/docs/billing).
- Deleting an item hides it and removes it from search. Its history stays in the sync log until you [delete the account](/docs/web-library#deleting-your-account). Keep your own backups.
- Capture needs a computer running `sponge`. A phone or a browser alone can queue links and read what is already synced, but cannot capture.
- Media transcripts, CLI semantic search and building the library map need native helpers that run only on Apple Silicon Macs with macOS 26; `sponge setup` installs them. See [Requirements and platforms](/docs/requirements).