freebuild-sponsor
v0.0.20
Published
Paid sponsored plan plugin for Freebuild on OpenCode: license activation, broker provider, and sponsor panel.
Maintainers
Readme
Freebuild OpenCode sponsor panel
A V2 TUI plugin for the paid Freebuild Sponsored plan. It adds a
host-managed sponsor panel while the agent works, automatically connects the
freebuild model provider, and shows plan and token usage.
┌────────────────────────────────┬────────────────────────────────┐
│ │ FREEBUILD · Acme │
│ normal OpenCode session │ │
│ reflowed to half width │ SHIP FASTER │
│ │ Acme CI runs your tests... │
│ │ │
│ │ │
└────────────────────────────────┴────────────────────────────────┘Panel labels
SPONSOREDfor paid campaignsAFFILIATEfor affiliate campaignsFREEBUILDfor house inventoryADVERTISEfor advertising inventory
Paid campaigns outrank affiliates, and affiliates outrank house inventory.
Paid plan
There is no free or ad-free tier. The plugin is inactive until a sponsored license is connected:
- No license: no panel, no ads, no broker tokens.
- Active sponsored license: broker tokens plus the mandatory sponsor panel.
- Canceled or unpaid subscription: the broker rejects requests and the panel stays closed.
Install
Install the published package with OpenCode V2:
opencode plugin add freebuild-sponsor@latestRestart OpenCode so it loads the plugin. To update later:
opencode plugin updateFor local development from this repository, install the directory directly:
powershell -ExecutionPolicy Bypass -File .\opencode-plugin\install.ps1bash ./opencode-plugin/install.shTo build the npm tarball before publishing:
cd opencode-plugin
npm packThe package contains src/tui.tsx, package.json, and this README. Test the
tarball with a clean OpenCode config before publishing.
Connect a license
Inside OpenCode, with no key connected:
/freebuild-licenseThe plugin asks the app for a one-time activation code, opens
/terminal/activate.html in the browser, and polls until Stripe Checkout
finishes. When the webhook issues the license, the plugin:
- stores the key in
~/.config/freebuild/credentials.json, - writes a
freebuildprovider to~/.config/opencode/opencode.json(c), - refreshes entitlement and enables the sponsor panel,
- shows the license key and the remaining setup steps.
Finish the connection with OpenCode's native credential flow:
/connectChoose Freebuild, paste the license key, then run:
/freebuild-setup
/models/freebuild-setup selects Freebuild → DeepSeek V4.1 Flash 1017 for the
current session. The model has the same thinking levels as DeepSeek's own API:
none, low, high, and max. Use /thinking to switch levels without
changing models. The provider points at the Freebuild broker; the license key
is the broker API key.
When a key is already connected, /freebuild-license checks it first and offers
reconnect, paste a replacement, open the account page, or buy
another license. It never starts a second checkout on its own, and a rejected
key (rotated, revoked, or cancelled) only offers a replacement or the account
page.
To move this terminal to a key recovered at /account:
/freebuild-keyThe plugin prompts for the key, checks GET /api/me/entitlement before saving
anything, then saves it and shows the /connect instructions. An inactive key is
reported and the current license is left untouched. A network failure also
leaves the current key in place.
Useful commands:
/freebuild-license— connect, reconnect, replace, or buy a license./freebuild-key— paste and validate a replacement key./connect— choose Freebuild and paste the license key./models— select the Freebuild provider model./thinking— choosenone,low,high, ormaxthinking for DeepSeek V4.1 Flash 1017./freebuild-plan— show plan, used tokens, reservations, and the monthly limit./freebuild-billing— open the Stripe customer portal./freebuild-setup— repair the provider configuration./freebuild-sponsor,ctrl+o,ctrl+shift+o, oralt+o— open the sponsor link currently on screen. Clicking anywhere on the sponsor panel does the same. If no campaign is cached yet, Ctrl+O resolves one with a non-counting preview request so it still opens a link instead of a menu or document. Ctrl+O keeps its normal OpenCode meaning when no sponsored license is active; use/openfor the picker while a sponsored license is active./freebuild-adtest— preview the panel for 8 seconds without a run.
Behavior
- Opens on the first agent step and closes when the run ends. Each run fetches one authenticated sponsor for a fresh run ID and keeps it for the whole run; the server counts one impression when that run's panel opens. Repeated panel fetches and duplicate events are idempotent, so a long run stays one impression. There is no mid-run carousel.
/freebuild-adtestuses the preview endpoint. Preview requests never count an impression and never emit trackable open, close, or click events.- The panel measures its own box and fits the campaign wordmark and copy to it.
Larger logo tiers are only used when both width and height leave room, and
body and hint rows drop out as the panel gets smaller. A fixed
wordmarkFontfalls back to Auto when it does not fit;showWordmark: falsehides the big text entirely. - OpenCode uses a split layout at 108+ columns; narrower terminals render the panel fullscreen and show a resize hint.
- The panel content comes from the sponsor feed. Image ads render a static image above the copy; text-only ads render the wordmark and formatted copy. Image-only ads render the image across the whole creative area with no kicker, headline, body, or wordmark. GIFs are flattened to their first frame. If the feed or image is unavailable, a bundled house ad or text fallback is used.
- Clicking the panel resolves the sponsor destination through the authenticated
click endpoint. The TUI sends the license, install, session, and run IDs, then
opens the returned URL. Direct anonymous click URLs return
401. - The panel cannot be hidden with a keybinding. Ads are part of the sponsored plan.
- In the experimental Freebuild Terminal wrapper, the TUI panel stays closed and the plugin writes busy and entitlement state for the wrapper's side pane. The wrapper is not part of the first launch.
Wrapper mode
Set FREEBUILD_WRAPPER=1 and FREEBUILD_WRAPPER_STATE to a writable file path.
The plugin then writes:
{
"busy": true,
"panel": true,
"sessionId": "c13792d2135744c5bb309fa7",
"updatedAt": 1793480000000
}busy drives the wrapper's status line. panel is the entitlement decision:
true for an active sponsored license. The wrapper keeps the sponsor pane
visible for the whole app session whenever panel is true.
updatedAt is Unix milliseconds. It is refreshed every 10 seconds while a run
is active. A run that finishes in under 3 seconds keeps busy: true for the
remainder of a 3-second minimum window so a short run is not missed. The wrapper
clears the file before starting OpenCode and ignores a stale busy flag older
than 90 seconds.
Without FREEBUILD_WRAPPER_STATE, FREEBUILD_WRAPPER=1 is ignored and the
normal TUI panel remains available.
Entitlement
The plugin reads a license key from:
FREEBUILD_LICENSE_KEYorFREEBUILD_API_KEY,~/.config/freebuild/credentials.json, or- the legacy
freebuildprovider entry in OpenCode'sauth.json.
On OpenCode V2, provider calls use the credential connected through the
integration API. The plugin keeps credentials.json so it can refresh
entitlement and the sponsor panel across launches.
Credentials file:
{
"installId": "a stable installation id",
"licenseKey": "fb_...",
"apiUrl": "https://freebuild.dev",
"brokerUrl": "https://freebuild.dev/broker",
"sponsorUrl": "https://freebuild.dev/api/sponsor/panel"
}It calls:
GET {brokerUrl}/api/me/entitlement
Authorization: Bearer <licenseKey>
X-Freebuild-Install: <installId>sponsored: true→ the panel may open during runs.sponsored: false→ the panel never opens.- No license key → inactive; run
/freebuild-license. 401for a connected key → rotated, revoked, or cancelled; run/freebuild-keywith the replacement from/accountor/freebuild-licensefor the recovery menu. The plugin does not start a new checkout automatically.- Broker unreachable with a license key → the panel stays closed and the license is not discarded.
/freebuild-adtestforces a preview without changing entitlement.
The generated provider also sends X-Freebuild-Install and
X-Freebuild-Client. The install ID lets broker usage line up with a
license, and the client ID records which surface made the request.
Sponsor feed
The plugin fetches:
GET {sponsorUrl}
Authorization: Bearer <licenseKey>
X-Freebuild-Install: <installId>
X-Freebuild-Client: opencode/<pluginVersion>Expected response:
{
"campaign": {
"id": "acme-2026-11",
"brand": "Acme",
"kicker": "SHIP FASTER",
"title": "Acme CI runs your tests in 30 seconds.",
"body": "Use code FREEBUILD for 3 months free.",
"url": "https://acme.example/freebuild",
"clickUrl": "https://freebuild.dev/api/sponsor/click?id=acme-2026-11",
"eventUrl": "https://freebuild.dev/api/sponsor/event",
"accent": "#39d98a",
"wordmark": "ACME",
"wordmarkFont": "block",
"showWordmark": true,
"imageOnly": false,
"titleStyle": { "bold": true, "italic": false, "underline": false },
"bodyStyle": { "bold": false, "italic": true, "underline": false },
"align": "center",
"imageUrl": "https://freebuild.dev/ads/acme.webp"
},
"serverTime": 1793480000
}imageUrl is optional. When present, the panel and wrapper render it as a
static image above the copy; when absent, the panel shows the wordmark and the
formatted text. imageOnly: true requires an imageUrl and renders the image
across the full creative area without a kicker, headline, body, or wordmark.
wordmark defaults to FREEBUILD; wordmarkFont accepts
auto, huge, block, slick, shade, tiny, grid, or pallet;
showWordmark: false hides it. Uploads from /admin/ads.html are normalized to
static PNG; GIFs use their first frame. titleStyle and bodyStyle accept
bold, italic, and underline; align accepts center or left.
videoUrl is legacy and ignored.
Panel events are posted as:
{
"campaignId": "acme-2026-11",
"sessionId": "c13792d2135744c5bb309fa7",
"installId": "fa0515ea6e0c419db3f00901ea697316",
"runId": "run-0001",
"client": "opencode/0.0.20",
"event": "open",
"durationMs": 0,
"tokens": 75
}close events include the visible duration. The client field is
client-reported, not verified. Use it to split events by surface, not as proof
that the panel was visible.
Environment
FREEBUILD_LICENSE_KEY broker license key
FREEBUILD_API_KEY fallback license key
FREEBUILD_BROKER_URL broker base URL (default https://freebuild.dev/broker)
FREEBUILD_API_URL app base URL for activation (default https://freebuild.dev)
FREEBUILD_SPONSOR_URL sponsor panel feed
FREEBUILD_CREDENTIALS alternate credentials JSON path
FREEBUILD_AD_DEMO=1 preview the panel on startup
FREEBUILD_AD_DEMO_MS preview duration in milliseconds
FREEBUILD_WRAPPER=1 suppress the TUI panel and emit wrapper busy state
FREEBUILD_WRAPPER_STATE busy-state file for the desktop wrapper
FREEBUILD_WRAPPER_DEBUG optional log file for plugin/wrapper diagnosticsDevelopment
OpenCode 2.2.0 requires removing the resize listener with renderer.off(...);
calling the return value of renderer.on(...) crashes the plugin during cleanup.
The TUI loads plugins live, so a setup or cleanup exception can take down the
host terminal. Test changed plugins in a separate OpenCode process before
replacing the copy used for daily work, and keep FREEBUILD_WRAPPER unset
unless the desktop wrapper is actually launching OpenCode.
Validation used in this repository:
wrapper\node_modules\.bin\esbuild.cmd opencode-plugin\src\tui.tsx --bundle `
--loader:.tsx=tsx --external:* --outfile=$env:TEMP\plugin-check.jsTest
- With no license key, no panel opens during a run.
/freebuild-licensecompletes Stripe Checkout and writes the provider config.- After checkout,
/connectstores the credential,/freebuild-setupselects the model. - With an existing key,
/freebuild-licenseasks before buying and never opens a second checkout. /freebuild-keyrejects an inactive key and keeps the current license; an active key is saved and shown with the/connectsteps./accountreveals, rotates, and opens billing for licenses owned by the signed-in email.- With a sponsored license, the panel opens and shows the fetched campaign.
/freebuild-planshows used, reserved, and limit tokens.- A canceled subscription makes
/api/me/entitlementreturn401and the panel stops opening.
License
Proprietary. Copyright (c) 2026 Freebuild. All rights reserved.
This package is licensed under the Freebuild Proprietary License. See LICENSE.
