Repository navigation
Releases
0.1.11 - speak the Icedrive desktop API
The mobile API is gone; ColdSnake now speaks the desktop one
Icedrive retired /v3/mobile on 2026-10-26. Every request there - proof-of-work,
listing, even a still-cached bearer token - now answers:
{"error": true, "code": 3000, "message": "Please update app to latest version"}and it does so for any version in the iOS User-Agent (2.3.1 through 99.0), so a
version bump cannot fix it. A non-mobile User-Agent is refused with code 5001.
0.1.11 talks to https://apis.icedrive.net/v3/desktop the way Icedrive's own CLI
does, with User-Agent: icedrive-linux-cli/3.62 and
X-Icedrive-Api-Version: 2 on every request.
What changed
- Login -
POST /pow-newthenPOST /login(multipart; the device id carries a
::msuffix on the login call). The proof-of-work answer is unchanged, so no
change to the solver. - Stats -
/stats-storagereplaces/user-statsand answers a flat document;
it is normalised back to the nested shape callers already used. No bandwidth
figures any more. - Routes -
/move,/file-rename,/trash-add,/restore-trash./move
takesitems=file-<id>; the app'snitemsJSON field is refused with HTTP 400.
Verified live (2026-10-26)
Login, stats, pre-flight, listing, folder creation, whole-file and chunked upload
(20 MB round-tripped with a matching sha256), post-upload verification, idempotent
re-runs, move, rename, version history, download, trash, batch erase and scrub -
all re-run against a real account, and again end to end through the CLI on a
production host.
Known gap
coldsnake restore --id does not work on the desktop API yet. The route the
Icedrive app builds, POST /restore-trash?itemId=<id>&type=file, answers
2003 Invalid request, and every other spelling tried on the live account does
the same. Trashing, listing the trash and erasing all work; use the Icedrive app
to bring an item back until the route is found.
Upgrading
pip install --upgrade . # or: pipx upgrade coldsnake
coldsnake login # the cached token from 0.1.10 is not valid here180 unit tests, no dependencies beyond the standard library.
0.1.10
Documentation patch - but the documentation was operationally wrong, which bit the first live run.
scrub --folders Ncounts folders per mirror, not per run. The help text said the default 1500 was "~17 min"; with six mirrors it is about an hour. A first production run of the default took about an hour - 0 failures, 0 throttling - and the help text, README and unit comment now say so.- Throughput table: a full scrub pass covers every reachable folder (~60 min at the measured safe rate) - fewer than the raw directory count, because excluded, empty and hidden-name folders are not verifiable.
- CI also tests Python 3.14.
No behaviour change: same code as 0.1.9. The scrub -> mirror repair loop was confirmed end to end on a live account - a 36-byte dotfile that scrub found missing from the remote was re-queued and re-uploaded by the next mirror run.
0.1.9
Patch release: the package could not be imported at all on Python 3.11.
SyntaxErroron import under 3.11. The Discord embed built its text with quote reuse inside f-strings (f"{payload.get("command")}"), which only parses on 3.12+.requires-pythonsays>=3.11, so 0.1.6 through 0.1.8 were broken there: anyimport coldsnake.cli-login,ls,mirror, everything - raised before doing anything. The command name is precomputed now.- CI has been red since 0.1.6 for exactly this reason, on the 3.11 job only.
tests/test_compat.pynow parses every source file withast.parse(feature_version=(3, 11)), so a newer-than-declared construct fails the suite even without a 3.11 interpreter present.
Nothing else changed; 0.1.8's scrub and pacing are as released.
0.1.8
Adds remote re-verification, so a file lost on Icedrive's side no longer hides behind a "no changes" run forever.
coldsnake scrub- re-lists the folders whose recorded files have gone longest unchecked, compares sizes, and forgets anything missing or resized. The nextmirrorrun uploads it again. It is an oldest-first rotation, not a sample: every folder is verified once per cycle, and each run resumes where the last one stopped (sync-db.sqlitestores the per-folder check time). Costs one listing per folder, and folder ids are cached, so a folder's own listing also teaches us its childrens' ids.- Listings are paced. There is no whole-tree listing and the API throttles control calls, so going too fast costs a 90 s stall rather than a retry. Measured with the new
tools/throttle_probe.py: 1.39 calls/s held for 10 min and 2.08 calls/s for 3 min with no 429 and flat ~0.42 s latency, while 4.1 and 6.7 calls/s both answered429withRetry-After: 90.Clientnow spaces listings at 1.5 calls/s and slows further for the rest of a run if a 429 still happens. Uploads are unaffected. --folders N/--all/--remote NAME, plus--json/--report, andsystemd/coldsnake-scrub.{service,timer}at 03:00 - deliberately before the 05:00 mirror, since the throttle is shared.- Hidden folders are not reported as lost.
/collectionnever lists dot-prefixed folders, so.syncor.dtrashread as gone even when they exist; they are counted asunverifiableinstead. Hidden files inside visible folders are listed and verified normally. - Fixes:
name_keynow strips leading/trailing spaces, as folder-create does (a localLeading Spaceis stored asLeading Space, and used to read as a missing folder). The sync db and upload journal now live next to the config in use, so--configno longer writes the default state dir.
Verification: 179 tests green, and a full live sweep - the whole tree - finished with 0 failures and no throttling. Only real drift it found: one small dotfile missing from the remote.
0.1.7
Fixes mirror aborts where files under case-variant or colon-containing folder names failed every run with 2006 Folder exists (live account: dozens of files per run since 2026-10-12).
- name_key now replicates Icedrive's server-side name rules, verified live by probe:
- NFKC normalization (existing behavior)
- case-insensitive: remote
ARTISTmatches localArtist - folder-create strips
< > : " / \\ | ?(not*), soExample Title: Wild Huntexists remotely asExample Title Wild Hunt— now matched instead of re-created
- Existing remote folders are reused as-is; no renames, no re-uploads beyond the previously failed files.
- 168 tests green; live run on the test account:
done: 0 failure(s).
ColdSnake v0.1.6
Added
- Webhook notifications — optional [webhook] url in the config. One JSON
POST on run start, one on finish (mirror/check runs). The finished payload
carries ok, the error for every abort type (auth, service outage,
pre-flight refusal, unexpected), and every failed file under
mirrors[].failures as {path, error}. - Discord webhook support: payloads to discord.com/api/webhooks URLs are
flattened into one embed (green ok / red failed, error field, all file
failures collapsed into one field), and an explicit User-Agent header is
now sent (Discord 403s the default Python UA). Live-verified end to end
against a real Discord webhook.
Delivery is best-effort (10s timeout): a webhook that cannot send logs a
warning and never changes the run's exit code.
Full Changelog: 0.1.5...v0.1.6
ColdSnake v0.1.5
Added
- Optional 2FA support ([auth] twofa = true) for two-factor accounts: a
login that hits the 6000 confirmation challenge falls back to a confirm
step, reading the code from ICEDRIVE_2FA_CODE (or a prompt on a tty).
Live-verified against a 2FA-enabled account.
Note
- Unattended caveat: with the code in a systemd Environment= line any local
user on the machine can read it (it grants drive access); see README.
0.1.4 - verify mangled-name uploads by unique same-size entry
Bug-fix release.
Fixed
- Files with "difficult" names re-uploaded and failed verification every
night, forever. Icedrive silently mangles disliked filenames at upload
time (live-verified): unsupported emoji become?(😀😁😂.ogg→
?????.ogg), a leading space is stripped (leading-space….mp4→
leading-space….mp4), long names truncate. The upload itself always
landed with the exactly right size, but verification matched by name, so
the same a few dozen files were reported "missing after upload"
each run, never recorded in the sync db, and sent again the next night.
Verification is size-only anyway (the API has no hash), so it now falls
back to a unique same-size listing entry when the name cannot be
found. An ambiguous match (several entries of that size) or a missing
file still fails - the fallback cannot produce a false positive.
ColdSnake v0.1.3
Bug-fix release.
Fixed
Error handling upload partskilled large files.geo-fileserver-list
hands out several signed deposit nodes and chunks of one upload were allowed
to land on any of them; the server assembles a file only from parts on a
single node, so the final chunk of a large video was refused after its 115
earlier chunks had been accepted and journalled ("uploaded" files also showed
up as verify failures for the same reason). The node that accepts a file's
first chunk is now remembered (per upload) and every later chunk of that file
goes to it alone; if the node leaves the endpoint list the pin is dropped and
a fresh one is picked.- A file that still cannot be assembled no longer retries forever. Its
journal entry is dropped, so the next run re-sends the whole file to one node
instead of resending only the missing chunk against parts it can never
assemble (the upload id is derived from destination+size+mtime and parts are
overwritten by a full re-send, so the id itself is fine to reuse).
Changed
__version__is read from the installed distribution metadata instead of a
hardcoded string (coldsnake --versionreported 0.1.2 after installing
0.1.3).- README: the systemd units run a
Type=oneshotjob, sosystemctl start/
restartblock until the whole mirror run finishes - documented, with
--no-block.
ColdSnake v0.1.2
ColdSnake v0.1.2
Bug-fix release.
Fixed
- HTTP 429 throttling aborted runs. Repeated full listing passes (large
trees, several runs in an hour) trip Icedrive's rate limit, and the 1-4s
exponential backoff was too hot: the run aborted after 4 attempts. A 429 now
waitsRetry-After(capped at 300s, else 60s). - Server-side name normalization. Icedrive normalizes item names (NFKC):
a folder namedExample Album!(fullwidth!, U+FF01) already exists
remotely as the ASCIIExample Album!, so create answered2006 Folder existswhile the exact-match listing never found it and the mirror aborted
withcannot create remote folder. Folder matching, upload skip checks,
verification and prune now compare names through NFKC. - Empty files counted as failures. A legit empty local file (e.g.
Syncthing's.stignoremarker) was a per-run failure because the upload
refuses empty bodies. It is skipped with a log line and askippedcounter
in the summary and JSON document.
Added
- sqlite sync db (
~/.config/coldsnake/sync-db.sqlite): records files
that uploaded and verified as (size, mtime). The skip decision consults it
before the remote listing, and folder ids resolve lazily — a run with no
changes now makes no listing calls at all, which is what the 429 throttling
was punishing. First run after upgrading populates the db with one listing
pass; after that runs are API-quiet.--no-sync-dbor deleting the file
restores always-list-the-remote behavior (that is the resync).
Full changelog: v0.1.1...v0.1.2