Use donated tokens in your project

Donors give your project a monthly token limit on their own LLM API accounts. You and your members use those tokens from the tools you already have: any MCP client or agent, and any tool that lets you set a provider base URL. Prompts and code are encrypted on your machine and decrypted only on the donor's device that serves the request.

Once a first donor is accepted, getting an agent running on donated tokens takes about 3 minutes.

Only public repositories can be registered.

1. Install and sign in#

Install the Moochy app as in the donor guide, then:

moochy login --roles gateway
moochy up

Confirm the printed code in your browser (GitHub or GitLab sign-in). The first time, you choose your handle (rules in the donor guide). --roles gateway lets this device use donated tokens.

2. Register your repository#

1. Create your owner key, once per account:

   moochy owner init
   

   Copy

   It is a separate key that signs only your decisions as an owner (claims, accepted donors, members). It is encrypted with its own passphrase, which you type in the terminal, and it is used only by the commands below, never by the app running in the background. Keep the passphrase somewhere safe. moochy owner rotate replaces a key you still have; if you lose the key or its passphrase, it can be revoked after you sign in again on moochy.dev, and you create a new one with moochy owner init. Your other devices warn you if an owner key appears on your account that you did not create.

2. On moochy.dev, open Claim and pick the repository. Moochy asks your code host, once, whether you are an admin of it. The sign-in token is used for that check and not stored.

3. Confirm on your own machine, in the repository folder:

   moochy claim --repo owner/repo
   

   Copy

   The app shows what it is about to sign, asks you to confirm, and asks for your owner key's passphrase. Your signature goes into the public key log. From then on, every donor or member accepted for this repository needs your signature.

4. In Project settings, set the monthly goal, a short public note on what you use the tokens for (donors read it before donating), and the default model.

Add a Donate tokens button to your README so donors find you: see Add a "Donate tokens" button.

Keep the claim active. Moochy keeps no code-host token. Your claim is re-checked each time you sign in on moochy.dev (your role: admin of the repository). Not signed in for 30 days: the claim pauses (no new requests use its donations; donors, approvals and history stay), with an email a week before; signing in resumes it at once. Not signed in for 90 days, or no longer an admin at a re-check: the claim ends, its approvals drop, you get an email, and any current admin can claim it.

Share your project#

The link to share is your project's page itself, https://moochy.dev/p/github/owner/repo (https://moochy.dev/p/gitlab/group/project on GitLab, https://moochy.dev/org/github/acme for an organisation): no redirect, no tracking parameter. moochy claim prints it when the claim is done (Share: https://moochy.dev/p/github/owner/repo), and so do moochy claim --org and moochy claim --person.

What the preview shows. Posted on X, Bluesky, Mastodon, LinkedIn, Facebook, Reddit, Slack, Discord, WhatsApp, Telegram or iMessage, the link unfolds into a card: the project's name and code host, its short description, this month's donations against the monthly goal as a big progress bar with the percentage, the number of donors, the tokens donated this month, and "Donate tokens · 100% free · moochy.dev". Without a goal it shows what was donated this month and the donors; an organisation's card shows its covered projects and its total. The card changes when the numbers do, so a link shared again shows today's progress. It never shows a donor's identity.

The Share button. The project page, the organisation page, and the page you see after a claim have a Share button: copy the link, or post it to X, Bluesky, Mastodon (it asks for your instance once and remembers it in your browser), LinkedIn, Reddit, Hacker News, Facebook, WhatsApp, Telegram, or email. On a phone it opens your system's share sheet. The message is prefilled and you can edit it: "owner/repo accepts donated AI tokens on Moochy, 100% free. Donate yours:". The links are plain links to those sites, with only the page and your message: no third-party script, pixel, or tracking. It works without JavaScript.

Own a GitHub organisation or a GitLab group? Claim it too, and one donation to the organisation funds every project you choose in it, with donors accepted once: see Donations for your organisation.

3. Accept or refuse donations#

New donations show waiting for the maintainer. Each request shows the donor's handle or pseudonym, the models, the monthly limit, and the limit per request, with useful signals: account age, other projects they donate to, past disputes. You decide in one of three places; every decision is recorded.

From the terminal, on your own machine:

moochy pending                                       # donors and members waiting for you
moochy accept ps_7hc2qz… --repo owner/repo           # or the donor's handle; `moochy approve` is the same command
moochy accept ps_7hc2qz… --repo owner/repo --revoke  # remove a donor you accepted

The app shows exactly what it will sign (the project, the donor, your owner key), asks you to confirm, and asks for the owner key's passphrase. In scripts and CI, --yes skips the question and the passphrase comes from MOOCHY_OWNER_PASSPHRASE; it is never read from standard input, so a tool piping into moochy cannot answer for you.

From an email. When a donor is waiting, Moochy emails you the request with Accept, Refuse, and Review buttons. A button never decides anything by itself (mail scanners open links): it opens the request on moochy.dev, where you must be signed in (within the last 2 hours) and press the button again. The link works once and for 7 days.

From the website, Repositories → the project → the request: the same page.

• Refuse is one click on that page, with an optional short reason the donor sees. A refusal grants nothing, so it needs no signature.
• Accept on the website or from an email needs a passkey: Touch ID, Windows Hello, or a security key registered as one of your owner keys. Your device signs the exact acceptance, and every member's app checks that signature in the public key log, as with the terminal. Moochy's servers cannot forge or replay it. To register your first passkey, you confirm with a link sent to your confirmed email address (or sign with an owner key you already have).
• A request nobody answers expires after 30 days, and the donor is told.

Approvals are always signed by you, never by Moochy. Whether from the terminal (owner key) or the website (passkey), the signature is made on your own device after you confirm. The background app cannot accept anyone, and a donor you did not accept never receives your project's requests.

Every decision is traced. Activity → Decisions shows each request and what happened to it (requested, accepted, refused, expired, stopped, lowered, resumed, revoked), who decided, when, and how (terminal, website, email link, passkey). The donor sees the same history for their donation. Both are in your data export, and acceptances are verifiable in the public key log.

Your own app warns you if the public key log ever shows a donor, member, or claim for your repository that you did not sign. If you get an email confirming a decision you did not make, treat it as a security problem: revoke the key or passkey it names.

Emails you get#

You confirm an email address when you first sign in; Moochy uses it only for these notifications.

Bursts are grouped (at most one email of a kind per hour). Emails never contain prompts, responses, keys, or tokens, and have no tracking pixels.

4. Members#

Members are the people (and CI machines) allowed to use your project's donations.

moochy members add alice --repo owner/repo --cap '$20'          # up to $20 a month
moochy members add --device d_01J… --repo owner/repo --cap '$5'  # a CI or server agent
moochy members remove alice --repo owner/repo

Write the amount with a dollar sign, in single quotes so your shell keeps the $. Each change is signed on your machine after you confirm, like an acceptance. Without --cap, a member may use 20% of what donors give each month by default; the owner has no limit. You can change limits later in Project settings. A donor's device serves a request only from a member you signed, or from you.

Give a CI or container agent its own device with its own monthly limit, so an agent running on its own can never use up the project's donations. See Run Moochy on a server or in CI.

5. Run your agent in the sandbox#

moochy run -- claude          # or opencode, aider, goose, …

Tool calls from donated tokens only reach agents inside moochy run. The sandbox lets your agent work on this repository and nothing else: no access to your other files or keys, and no network except Moochy. A tool started without moochy run still gets text answers, but each tool call is replaced by a [moochy] notice, unless you allow it for this project (moochy config set allow_unsandboxed_tools owner/repo, with a warning at every start). Details: Run your agent safely with moochy run.

6. Connect your tools#

moochy run sets everything up for the agent it starts. To configure a tool yourself, in the repository folder:

moochy connect list              # the tools it knows
moochy connect <tool>            # print the settings for that tool
moochy connect <tool> --write    # add them to the tool's user-level config, after showing the change

Tokens are never written into files tracked by git: --write refuses such files.

Two ways in, both on 127.0.0.1 only:

The raw values, for anything not listed:

moochy env --repo owner/repo            # shell exports: ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, OPENAI_BASE_URL, OPENAI_API_KEY, MOOCHY_MCP_URL
moochy env --repo owner/repo --json     # {"anthropic_base_url", "openai_base_url", "token"}
moochy env --repo owner/repo --rotate   # replace the project token

The token works for one repository and only on this machine. The port is chosen once and stays the same, so your settings keep working after a restart. Exact settings for every tool are in Connect your tools.

Model ids look like anthropic/claude-sonnet-5, deepseek/deepseek-chat, or x-ai/grok-4. GET /v1/models (and moochy_pool_status) list exactly what donors offer your project right now.

7. What protects you#

Donors' devices produce your model output, so treat it like any input you did not write:

• The sandbox (moochy run, above) keeps a bad command from reaching anything outside your project.
• Tool calls are checked before your agent sees them. Each tool call is held until complete, checked against the tool list and schema your tool sent, scanned for dangerous patterns (for example curl … | sh), and released only with a signature from the donor's device. Anything that fails is replaced by an error result.
• Responses are rebuilt, not copied. Your app re-creates every streamed event from checked, typed data, so no byte a donor chose reaches your tool's parser as-is. Terminal control characters are removed.
• Results from moochy_delegate are marked as untrusted content from a named donor.
• Secrets are removed from requests before they are encrypted, and secret files are hidden inside moochy run.
• Receipts are checked for you. If a donor's signed usage does not match what your app actually sent and received, your app files a signed dispute. When everything matches, you do nothing.
• Providers you exclude in Project settings (for example for data retention reasons) never receive your project's requests.

8. Errors your tools may see#

Errors come back in the provider's own format, so agents react sensibly:

9. Day to day#

moochy status                  # donations available to your projects, requests in progress
moochy pending                 # anything waiting for your signature
moochy journal --follow        # requests you made: model, cost, status
moochy verify <receipt_ref>    # check a public receipt of one of your requests: donor signature, link to the signed receipt, public key log

Project settings show how much donors gave this month and how much was used, usage per member and per model, the cache hit rate, and models your members asked for that no donor offers.

This page as Markdown: /docs/maintainer.md · for AI agents: /llms.txt