A Thumper repository holds code and weights together. Source files live in text lanes that merge at the character level; large binaries are chunked and deduplicated into the object store. Every listing on the catalog is backed by one repository, and the same address serves both: the public page at /apps/<owner>/<name> and the developer view at /apps/<owner>/<name>/dev. The kinds are app, lib, model, modelpack and dataset.

Repository classes

A repository is created as private plaintext, published public, private end-to-end encrypted, or a public fork. Public repositories are readable by anyone signed in; private E2EE repositories are opaque to the server, which stores and routes authenticated updates it cannot read.

The developer view

Thumper does not replace git. A synced folder can be a git repository at the same time: git keeps its objects in .git/, Thumper keeps its own state in .thumper/, and neither directory is ever uploaded. thumper push walks the working copy, moves the branch's live frontier one file at a time (each update signed by this machine's registered device key) and then seals the frontier into a signed, content-addressed commit — the seal is what Code, Commits and clones read.

Ignore precedence

Four sources are merged, highest first: .thumperignore, .stignore, .gitignore, then the built-in defaults. Inside one file the last matching line wins, so !keep.txt can re-include a file an earlier *.txt excluded. A trailing slash limits a pattern to directories; a pattern without a slash matches at any depth.

# outputs regenerate; do not sync them
outputs/
*.log
# but keep the one sample the README links to
!outputs/sample.png

Built-in defaults

.DS_Store Thumbs.db desktop.ini $RECYCLE.BIN/ *.swp *.swo *.tmp *~ .git/ .hg/ .svn/ .idea/ .vscode/ node_modules/ .npm/ .yarn/ .pnpm-store/ dist/ build/ target/ .venv/ venv/ __pycache__/ *.pyc .pytest_cache/ .mypy_cache/ .ruff_cache/ *.egg-info/ .tox/ .thumper/ .oxen/

How file types are stored

There is no extension list to configure. Thumper decides by content and size: text files become text lanes, everything else is chunked bytes. The rules below are the shipped constants.

Every branch has two heads. The live frontier moves on every edit from any authorised device or agent. The sealed head is an immutable seal: a signed commit with parents, a content digest, and provenance (who, from which device, under which capability). Auto-checkpoints between seals are cheap and disposable; a seal squashes the run since the last seal into one named commit.

A listing is a catalog row that points at a repository. Publishing a listing without signed publication files is allowed: the page exists, the download button does not. Signed publications appear under Releases and make the app installable from the desktop app.

Settings panels

General (default branch, handle), Listing (name, category, screenshots, README image policy), Upstream source (link a GitHub or Hugging Face repository; pulls are staged as drafts every hour), Marketplace (list for sale), Access (collaborators and invitations), Automation and Checks (checks that must pass), Lifecycle (make public or private, archive, delete).

README, licence and stars on the public page

The public page renders the upstream README with images stripped by default (the publisher can allow images from the upstream repository, or all images), the SPDX licence, and the upstream star count. All three refresh on the hourly upstream poll.

Repository routes live under /api/v1/repos. Every route checks the session, the repository's visibility and the caller's capability before it does anything; a repository you may not see answers the same 404 as one that does not exist. Mutations with a bearer token must be request-bound.

The thumper CLI

Sign in once per day from the terminal: thumper login prints a key fingerprint and opens /cli/authorize in your browser; approving there gives this terminal a session that is a child of your browser session (same account, same limits, expires with it). The first push registers the machine's device key; every change and every seal is signed with it — no password or token ever sits in the terminal.

# install (Linux, macOS): picks the build for your platform from /cli/release.json and verifies its SHA-256 first
curl -fsSL https://app.thumper.run/cli/install.sh | sh
# install (Windows PowerShell)
irm https://app.thumper.run/cli/install.ps1 | iex
# from source, any platform: cargo build --release -p thumper-ctl --no-default-features
# later: thumper upgrade --check  /  thumper upgrade
# sign in (device code; the browser approves)
thumper login
# create a public repository and link this folder
thumper repo create my-app --public
# or link a folder to a repository you already have
thumper repo init OWNER/NAME
# push: signed per-file updates, then a signed seal
thumper push -m "first import"
thumper repo status
# clone the sealed tree of a public repository
thumper repo clone OWNER/NAME [-b BRANCH]
# or plain git through the remote helper the installer links (one git commit per seal, one seal per pushed commit; lightweight tags too)
git clone thumper://OWNER/NAME
git remote add thumper thumper://OWNER/NAME && git push thumper main v1.0.0
# this machine's device key, and raw API calls with the session
thumper repo device status
thumper repo api /api/v1/handles/me
# bring the sealed head down into a linked folder (refuses to overwrite local edits without --force)
thumper pull
# branches, proposals and issues from the terminal
thumper repo branch feature-x --from main
thumper pr create -R OWNER/NAME --head feature-x --base main -t "Add X"
thumper pr diff -R OWNER/NAME 7
thumper pr checkout 7                # switch the working copy to the proposal's branch and pull it
thumper pr checks 7 && thumper pr view 7 --web
thumper repo tag create v1.0.0 --branch main && thumper repo tag list
thumper repo branch-delete feature-x     # never the default branch
thumper repo edit -d "What this repository is" --default-branch main
thumper repo protect set main --require-review --lock-deletions --required-approvals 1
thumper repo collaborator add HANDLE --role write   # admin | write | triage | read
thumper repo access list                            # grant / decline requests by id
thumper pr merge -R OWNER/NAME 7 --delete-branch   # fast-forward the base (a seal signed by this device), accept, drop the branch
thumper pr merge 7 --squash                         # base moved: three-way merge sealed once (conflicts are listed, never auto-resolved)
thumper pr merge 7 --rebase                         # base moved: each branch seal replayed onto the base, messages kept
thumper pr merge 7 --merge                          # base moved: two-parent merge seal via the server's merge lane (gh's default; needs branches that edited different files)
thumper pr update-branch 7                          # merge the base INTO the branch first, so review sees current base content
thumper pr review 7 --approve -b "LGTM"      # approvals count toward protected-branch rules
thumper issue create -R OWNER/NAME -t "Crash on start"
thumper label create bug -c E60076 && thumper issue label add 12 bug
thumper issue edit 12 -t "Crash on start (Linux)"
# repository administration
thumper repo list
thumper repo visibility private --repo OWNER/NAME
thumper repo fork OWNER/NAME
thumper repo release create 1.0.0 -R OWNER/NAME --commit <seal>
thumper repo release upload 1.0.0 dist/app.tar.gz && thumper repo release download 1.0.0 -D ./out
thumper repo webhook create https://example.com/hook -R OWNER/NAME --events push,release
thumper --yes repo delete OWNER/NAME
# native check runs recorded against a repository
thumper repo run list --repo OWNER/NAME --limit 20
thumper repo run watch --repo OWNER/NAME 42 --timeout 600
thumper repo run rerun 42 -R OWNER/NAME && thumper repo checks list -R OWNER/NAME

git and gh coverage

Each surface is behind an environment flag on the node. A route behind a flag that is off answers 404, indistinguishable from a route that does not exist. /api/v1/client-config reports the flags a client should honour.