Linux

Markdown · Agent index

A Linux computer can capture articles and PDFs, draft summaries, sync, and keep your save queue moving as a service. Use Node.js 24.20 or newer and the released @hraness/sponge package. Requirements and platforms compares Linux with macOS.

Join your account

If you already have a library on another computer, upload it from there first with sponge login, then sponge sync. On Linux:

npm install -g @hraness/sponge
sponge init
sponge login --label "Linux server"
sponge sync --join
sponge sync status

Open the printed link on any browser (your laptop or phone) and confirm the code. The terminal stores a private, revocable device credential. For a detached setup, use sponge login --no-wait followed by sponge login --finish after approval. There is no need for a browser on the Linux host.

An existing populated library with a different UUID cannot join. Back it up and initialize a separate empty directory using --library /absolute/new/library. Do not replace or copy a running SQLite database between hosts.

Local models

Capability	Linux support
Read, notes, FTS search, sync	Portable Node/SQLite implementation
Article and PDF capture	Built in; PDF extraction needs Poppler
Managed digest drafting	x64/ARM64 CPU llama.cpp, verified pinned archives
Existing local GPU model server	Explicit literal-loopback HTTP endpoint
Media transcripts, English speech recognition, CLI semantic search, map building	Not on Linux; these use Apple Silicon macOS helpers
Capture through a signed-in browser, worker install	macOS only; use worker foreground on Linux

The x64 runtime requires glibc 2.35 or newer; ARM64 requires glibc 2.39 or newer. Ubuntu 24.04 is the native CI qualification target for both architectures. Other compatible distributions must pass the same local preflight. Alpine/musl, Windows and GPU archive variants are not managed targets.

On Ubuntu 24.04, install the system prerequisites yourself:

sudo apt-get update
sudo apt-get install bubblewrap libgomp1 libssl3t64 libstdc++6 poppler-utils
sponge setup --digest
sponge run --drain

On x64 Ubuntu 22.04 the OpenSSL package is libssl3. The conservative glibc floor comes from upstream release dependencies; that distribution is not a separate live qualification claim.

setup --digest selects Qwen3.5-9B Q4_K_M with 16–32 GiB of effective RAM or Gemma 4 26B-A4B Q4_K_M with at least 32 GiB. The downloads are about 5.6 GB or 16.9 GB respectively, plus the small runtime. Container/cgroup memory limits count, even if the host has more physical RAM. Runtime threads respect available CPUs and quotas, capped at eight. Existing GGUF weights can be copied with --model-file /absolute/model.gguf; their exact pinned hash is still verified.

Bubblewrap must be able to create user and network namespaces. Managed inference fails preflight when host/container policy forbids them; Sponge does not change kernel settings or run the server without isolation. The server receives a read-only runtime/model and one owned scratch directory, communicates through a private Unix socket and is collected under the existing worker supervisor.

Ubuntu’s AppArmor user-namespace policy may require an administrator to admit /usr/bin/bwrap explicitly. Installing the package alone does not establish that permission. sponge setup --digest --debug reports prerequisite: user-network-namespaces when the probe is denied. The native CI runner installs a narrow, temporary profile for bubblewrap; it does not disable the global policy. Ask the host administrator for an equivalent reviewed policy when needed. Sponge never installs that profile on your host.

Below 16 GiB, choose and run a smaller model independently and use:

sponge digest ITEM --endpoint http://127.0.0.1:8080 --model MODEL_ID

The endpoint must implement Sponge’s llama.cpp-compatible model/health contract, and the model must appear at /v1/models. Quality is checked by the same digest validator; different weights, hardware or runtime builds are not a parity claim. Linux namespace/ELF tests do not measure full-model drafting quality or speed.

Keep work running

Two foreground commands have separate jobs:

sponge worker foreground   # captures and due local model/index jobs
sponge sync --watch        # exchange changes every 30 seconds

Use separate terminals or two systemd user services. For example, save the following as ~/.config/systemd/user/sponge-sync.service, replacing both absolute paths with your installed command and library. Node must be on the service PATH.

[Unit]
Description=Sponge private library sync
After=network-online.target

[Service]
ExecStart=/absolute/path/to/sponge sync --watch --library /absolute/path/to/library
Environment=PATH=/absolute/node/bin:/usr/bin:/bin
Restart=on-failure
RestartSec=30
UMask=0077
KillMode=control-group
TimeoutStopSec=90

[Install]
WantedBy=default.target

Create a second sponge-worker.service with ExecStart ending in worker foreground --library /absolute/path/to/library; keep the same process cleanup settings. Then enable them as your ordinary user:

systemctl --user daemon-reload
systemctl --user enable --now sponge-sync.service sponge-worker.service

worker foreground checks for a Sponge release once a day between jobs. After installing one it exits with an error, so Restart=on-failure starts it on the new version; sponge update auto off or Environment=SPONGE_NO_AUTO_UPDATE=1 turns that off. It checks only when the npm prefix it was installed into is writable by this user; a root-owned global install needs sudo npm install -g @hraness/sponge. With no worker, a one-off sponge sync (from cron or a timer) runs the same daily check after it syncs, when no other Sponge command or worker is running. A long-running sync --watch never updates; run sponge update yourself when only that runs. Keep any wrapper script outside npm’s bin directory: npm relinks <prefix>/bin/sponge on every install. Restart sponge-sync.service (or any sync --watch or MCP server) after an update.

Session/boot persistence depends on the host’s systemd user-manager policy; Sponge does not enable lingering or install a system daemon. worker install continues to manage only the macOS LaunchAgent. Inspect queue status, doctor, journalctl --user -u sponge-sync -u sponge-worker and the library’s service log. After a hard interruption, sponge queue recover preserves uncertain cleanup until it can prove that the old processes have stopped.

To draft an item received through sync, run sponge digest ITEM --draft, then sponge sync to send its draft back. Automatic drafting queues new captures made on that host; existing synced captures are drafted explicitly. Each host chooses its own model and processing settings. Summaries covers review.