The almanac

Setting up, running and troubleshooting the farm.

Written for the operator installing the app. Growers need none of this — see For growers instead.

1. Install

The Clip Farm ships as an Electron desktop app. From a clone or an unpacked release:

cd theclipfarm
npm install
npm start

On macOS an unsigned build is quarantined by Gatekeeper on first run. Clearing the quarantine attribute on the bundled Electron binary resolves it — the included launcher does this automatically, along with freeing the loopback port if a previous instance is still holding it.

Closing the window does not quit the app on macOS. The process keeps running, so a restart meant to load new main-process code silently does not. Quit properly before restarting.

2. Connect the platforms

TikTok

Register an app in the TikTok for Developers console and add Login Kit. There is no separate Display API product — the video.list and user.info.* scopes are Display API access.
Request scopes user.info.basic, user.info.profile, user.info.stats, video.list.
Register both redirect URIs: the loopback address under the Desktop platform for your own accounts, and the relay callback under the Web platform for grower invites.
Paste the client key and secret into Settings → Connections. They are encrypted at rest.

TikTok's PKCE is non-standard. The code challenge is the SHA-256 of the verifier encoded as hex, not RFC base64url. Standard OAuth libraries get this wrong and fail with an opaque error. The Clip Farm always sends the hex form.

The Sandbox has its own name and icon. Renaming the production app does not rename the sandbox — and since unapproved apps must demo against sandbox, the sandbox name is what appears on the consent screen. Rename both.

Instagram

Create a Meta app with the "Manage messaging & content on Instagram" use case, then set it up under API setup with Instagram login — not the Facebook login variant.
The value that goes into Settings is the Instagram app ID, not the Meta app ID. They are different numbers and mixing them up is the most common setup failure.
Add both instagram_business_basic and instagram_business_manage_insights. Basic alone silently returns empty view counts — the connection succeeds and likes and comments flow, but every view reads as blank.
Instagram accounts must be Business or Creator. Personal accounts cannot connect at all.
Instagram accounts — including your own — cannot use the desktop "Connect account" button, which uses a loopback redirect Instagram rejects. Use Onboard a grower instead.

3. Deploy the invite relay

The relay is a small Cloudflare Worker with a KV namespace and one secret. It is what lets a grower connect from their own device.

wrangler login
wrangler kv namespace create INVITES     # paste the binding into wrangler.toml
wrangler deploy
wrangler secret put CLAIM_KEY            # must run after the first deploy

Then put the relay URL and claim key into Settings → Connections, and register <relay-url>/callback as a redirect URI in both the TikTok and the Meta app.

The KV binding must be in wrangler.toml before the deploy that matters. Creating the namespace only prints the snippet; if the binding is missing, the callback fails at runtime with "storage is not configured" while the deploy itself reports success. Check the deploy output lists the KV namespace.

4. Run a field

Set the start date correctly. Payouts come from the change in views since the baseline snapshot at or before the start date. A wrong start date is the single most common cause of a wrong payout.
Refresh during the season, not just at the end. Every refresh is one snapshot and one data point; the day-by-day replay is only as sharp as the cadence. Background refresh in Settings → Automation handles this.
Pause before settling. Pausing freezes each clip's view count so figures do not drift while you reconcile.
Watch the overflow figure. If clips are earning zero because the fence was reached, the uncapped "would-be" number tells you what a top-up would cost.

5. Import TikTok Studio data

Retention curves, watch time, completion rate, audience demographics and traffic sources are not available in any API — only in TikTok Studio. Export the CSV from Studio and import it from the account's Retention or Audience tab. A dated Studio export can also seed growth history from before the app was installed.

These tabs hide automatically for Instagram accounts, where the equivalent data does not exist.

Troubleshooting

Symptom	Cause and fix
Instagram views all blank, likes and comments fine	The token was issued without `instagram_business_manage_insights`. Fix the scopes, restart fully, then delete and recreate the invite — invite URLs bake in their scopes at creation time.
A grower says the tester invite tab does not exist	It is web-only. Send them to `instagram.com/accounts/manage_access/` in a desktop browser.
Grower accepted the tester invite but still shows Pending	Two separate things. The tester role is a prerequisite; status only moves when they open the invite link and complete the consent screen.
Port already in use on start	A previous instance is still running — closing the window does not quit it on macOS. Quit fully, or use the launcher, which frees the port.
Callback returns "storage is not configured"	The Worker's KV binding is missing from `wrangler.toml`. Add it and redeploy.
Growth tab shows no trend	Trends need at least two snapshots on different days. Refresh again tomorrow, or seed from a dated TikTok Studio export.
Changes do not appear after a restart	Renderer changes reload with a window reload; main-process changes need a full quit and relaunch.

Anything not covered here: Support.