Run Moochy on a server or in CI
On this page
The same moochy app runs without a desktop: on a small server, in a container, or inside a CI job. Use it to:
- donate tokens around the clock from a machine you control (your key stays on it; Moochy never holds donors' keys), or
- run an agent in CI or a container on your project's donations.
You never run any Moochy server yourself. Moochy runs its own service at moochy.dev, and the app on your machine is all you need.
1. An always-on donation
1.1 Keys and home directory
Without a desktop keychain, the app keeps its keys in a file encrypted with a passphrase. Give the app its own directory, and pass the passphrase in the MOOCHY_PASSPHRASE environment variable (from a file only root can read, or from your secret manager; never typed into shell history):
read -rs MOOCHY_PASSPHRASE && export MOOCHY_PASSPHRASE # type it; stays out of history
moochy --home /var/lib/moochy login --roles worker --headless
# {"event":"device_code","user_code":"WXYZ-1234","verification_url":"https://relay.moochy.dev/device?code=WXYZ-1234"}
CopyOpen the printed link on any device, for example your laptop or phone, sign in to moochy.dev, check that the code matches, and press Add this device. --headless (or --no-browser) only stops the app from trying to open a browser on the server. The command then prints {"event":"logged_in","device_id":"d_…"}.
1.2 Provider key and limits
printf '%s' "$ANTHROPIC_KEY" | moochy --home /var/lib/moochy keys add anthropic --key-stdin # key from your secret store
moochy --home /var/lib/moochy safety --monthly-limit '$25' --accept-safety # the safety step: $25 a month from this machine
moochy --home /var/lib/moochy config set slots_max 4
CopyProviders: anthropic, openai, openrouter, deepseek, xai, or local for a model server on this machine or your network (Donate from your own GPU). Set a spending limit at your provider as well (how, per provider). Then donate:
moochy --home /var/lib/moochy donate --repo owner/name --cap '$25' --yes
moochy --home /var/lib/moochy donations # what each project used this month
CopyThe donation starts once the project's owner accepts you. The limit per request is the default ($5); change it, the models, or the schedule on moochy.dev.
1.3 Run it as a service
moochy service install sets up a user service (--system for a system unit, --print to see it first). To write the unit yourself, with its own user:
# /etc/systemd/system/moochy.service
[Unit]
Description=Moochy (donation)
After=network-online.target
Wants=network-online.target
[Service]
User=moochy
ExecStart=/usr/local/bin/moochy --home /var/lib/moochy up --foreground
# MOOCHY_PASSPHRASE=… in a file readable only by root (chmod 600)
EnvironmentFile=/etc/moochy/passphrase.env
Restart=on-failure
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/moochy
PrivateTmp=true
[Install]
WantedBy=multi-user.target
Copyup --foreground prints one JSON line when ready and writes /var/lib/moochy/state/node.json. Check on it at any time:
sudo -u moochy moochy --home /var/lib/moochy status
sudo -u moochy moochy --home /var/lib/moochy pause # stops serving immediately
sudo -u moochy moochy --home /var/lib/moochy journal --follow
Copy1.4 In a container
deploy/client/compose/ in the public repository runs a donor node with Docker Compose. It uses the release image ghcr.io/moochy-dev/moochy (the app alone on an empty base, an unprivileged user, state in a volume). Two profiles:
api: you donate with a provider API key.gpu: you donate with your own NVIDIA GPU. Ollama runs next to the app and listens on loopback only.
Get compose.yaml and .env.example from that folder, then:
cp .env.example .env # set MOOCHY_MONTHLY_LIMIT, and MOOCHY_PROVIDER or OLLAMA_MODEL
mkdir -m 700 secrets
(umask 022; head -c 32 /dev/urandom | base64 > secrets/passphrase)
(umask 022; read -rs -p 'Provider API key: ' k && printf '%s\n' "$k" > secrets/provider-key; unset k; echo)
docker compose --profile api up -d # or: --profile gpu
docker compose logs moochy # gpu: moochy-gpu
CopyThe log shows a code and a link. Open the link, sign in and confirm the code. That is the only manual step.
The container runs moochy start --headless. At each start it skips what is done:
- Sign in, when this device is new.
- Add the key from the secret file (
--key-file), or the model server (--local URL --model local/<id>=<server id>). - The safety step, from
MOOCHY_MONTHLY_LIMIT. Setting it confirms that you set a spend limit at your provider, or that you accept the risk. - Donate, when
MOOCHY_DONATE(a project) andMOOCHY_DONATE_CAP(dollars a month) are set and no such donation exists. - Run the app in the foreground, locked down as with
moochy up --foreground.
Keep secrets/passphrase: it unlocks the keystore in the moochy-data volume. To change the key, write the new one to secrets/provider-key and restart.
A machine that only donates needs outgoing HTTPS (to moochy.dev and to your provider) and opens no incoming port. The compose file publishes no port.
2. An agent in CI or a container
-
Add a device for the job, once, from your workstation:
Copyread -rs MOOCHY_PASSPHRASE && export MOOCHY_PASSPHRASE moochy --home ./ci-node login --roles gateway --headlessWhen you confirm the code in the browser, limit the device to one repository.
-
Make it a member with its own monthly limit. The repository owner runs
moochy members add --device d_… --repo owner/repo --cap '$5'on their own machine; it is signed with their owner key, so it needs their passphrase (keep the owner key off CI machines). An agent running on its own can then never use up the project's donations. -
Store the key file (
./ci-node, encrypted) and its passphrase in your CI secret store. -
In the job, restore the directory, start the app, and run the agent:
Copymoochy --home "$RUNNER_TEMP/ci-node" up --foreground & # prints {"event":"ready",…} when connected moochy --home "$RUNNER_TEMP/ci-node" run --repo owner/repo -- <agent command>moochy runstarts the agent inside the sandbox, already pointed at Moochy. Tool calls from donated tokens only reach agents insidemoochy run(why). On Ubuntu 23.10 and later runners, the sandbox needs the one-time AppArmor profile described in Linux. For MCP or API access without tool calls, usemoochy mcp --repo owner/repoor the settings printed bymoochy env --repo owner/repo: see Connect your tools. Everything stays on127.0.0.1inside the job.
There is no hosted endpoint to call instead, because a hosted endpoint would have to see your prompts. Running the small app next to the agent keeps end-to-end encryption everywhere.
3. Notes
- Server address.
moochy login --relay <url>exists only for developing and testing the app. Normal use needs no address: the app connects to moochy.dev. - Updates.
moochy update --from-file <file>installs a signed release and refuses unsigned files; or replace the app yourself and restart. Check new releases as described in the FAQ. A restart never serves an old request again: the app refuses requests created before it started. - Clock. Keep time sync (NTP) on. Requests more than 10 minutes old or ahead are refused, and
moochy doctorwarns about a wrong clock.
This page as Markdown: /docs/headless-node.md · for AI agents: /llms.txt