Freebuff provider for magpie & DeepSeek Harness

Freebuff's free models in magpie and
DeepSeek Harness — through the account's own
browser sign-in, with a multi-account pool that rotates when a daily quota
runs out, and streaming tool calls.

Freebuff is Codebuff's free tier. It costs nothing to use, but the allowance is
small and time-boxed: 5 freebucks buys a one-hour session, one account gets 25
freebucks a day.

Unofficial. Not affiliated with Codebuff or Freebuff.

> Status: beta (0.3.0-beta.1). The tool-calling path is implemented and
> covered by 38 assertions, and its wire format was checked against Freebuff's
> own client — but it has not been exercised end to end against a live
> Freebuff account (the one available during development is suspended).
> Install with @beta; the stable tag is held until that test runs.

The three packages

One repo, one protocol core, two thin shells:

freebuff-core ──┬──> magpie-freebuff-provider
└──> dsh-freebuff-provider

Why two shells and not one package: magpie wants a plugin object with hooks;
DSH wants an HTTP endpoint it talks OpenAI to. The protocol underneath — device
signature, session admission, account rotation, tool-call parsing — is identical,
so it lives once in freebuff-core.

Install

Published to npm, as @beta:

magpie

magpie plugin add magpie-freebuff-provider@beta
magpie plugin login freebuff

Or from a packed tarball:

npm pack --workspace magpie-freebuff-provider --pack-destination dist
magpie plugin add ./dist/magpie-freebuff-provider-0.3.0-beta.1.tgz

DeepSeek Harness

dsh plugin --profile desktop add dsh-freebuff-provider@beta

The package ships a gateway binary. Start it:

npx freebuff-gateway
# or
node node_modules/dsh-freebuff-provider/gateway.mjs

Then point a DSH provider at it. Add to ~/.dsh/profiles//cordis.patch.yml:

- id: llm-pi-ai
name: "@deepseek-ai/dsh-llm-pi-ai"
config:
providers:
freebuff:
displayName: Freebuff
apiKeyEnv: FREEBUFF_LOCAL_KEY
api: openai-completions
baseURL: http://127.0.0.1:8937/v1
models:
- id: freebuff/solar-pro4
name: Solar Pro 4 · 0fb
contextWindow: 1048576
maxTokens: 32768
input: [text, image]

set FREEBUFF_LOCAL_KEY=local-freebuff

patchEntry() in dsh-freebuff-provider generates this block programmatically
if you would rather not hand-write it:

import { patchEntry } from 'dsh-freebuff-provider'
console.log(JSON.stringify(patchEntry(8937), null, 2))

Sign-in

Two ways, both work in magpie and in the gateway:

Browser sign-in. Freebuff's own login page opens; sign in and the account is
picked up. Repeat to add more accounts — the pool holds them all.

Token. Paste an existing Freebuff authToken (a 36-character UUID). Sends
nothing at sign-in, so it works headless. Get it from
~/.config/manicode/credentials.json → default.authToken, written by the
official CLI after one sign-in.

Models

Captured from the account's catalog at call time, so it follows what Freebuff
actually offers. Locked rows (paid plans) are filtered out.

The four 0fb models cost no freebucks but still consume one of the day's
session windows. The 5fb–20fb models spend freebucks.

Tool calls stream through: tools, tool_choice and parallel_tool_calls go
to Freebuff; tool_calls come back as standard OpenAI deltas.

Quota

1. 5 freebucks = one hour. Fixed, non-pausable, non-refundable.
2. 25 freebucks a day, resets at Pacific midnight (≈15:00 Beijing).
   At most 5 sessions per account per day.
3. One premium session at a time per account. Opening a second takes the
   first away.

The plugin never opens a session it cannot pay for: a model priced above the
remaining balance is blocked with a readable reason. 0fb models stay openable
at zero balance.

Running both hosts at once

Don't share one Freebuff account between them. Freebuff allows one session
per account, so magpie and the DSH gateway using the same account will take each
other's session away — you will see a stream of 409s.

Pick one:

• One host only. Disable the other (magpie plugin off freebuff, or stop the
  gateway).
• Two accounts. Sign a different Freebuff account into each.

There is also a second, quieter cost: each shell generates its own Ed25519 device
key, so one account talking through both looks like two machines. That is one of
the patterns that gets an account flagged.

Keeping the account alive

• One client per account — not the plugin, the desktop app and the CLI at once.
• Do not rebuild the device key. It is created once and reused; replacing it
  registers a new device.
• Space out model switches. Several within a minute is the kind of pattern
  that draws attention.
• 403 account_suspended means the account is gone. Stop; do not keep
  probing. Appeal through the Freebuff account page.

Troubleshooting

Develop

npm install          # links the three workspaces
npm test             # 26 assertions across all three packages
npm run pack:all     # tarballs into dist/

scripts/test-installed.mjs additionally installs the tarballs into a scratch
directory and re-checks them, so packaging mistakes surface before publishing.

Notes on the protocol

Requests are signed with an Ed25519 device key over a six-line payload: version,
method, path, timestamp, body SHA-256, fetch id. The user message content is an
array of {type:"text",text} parts rather than a bare string, and role:"tool"
carries an underscore tool_call_id — both match what Freebuff's own client
sends. Sessions are released on the /attempt endpoint, which is what the
official client uses; the other one invalidates the whole session chain.

License

MIT. See LICENSE.