How FreeFlow works

Getting started

1. Create an account with your email.
2. Open API keys in the dashboard and create a key.
3. Download the Harness, paste the key when it asks, and open a project folder.

Using the Harness

Describe what you want changed, and the agent works in the folder you opened. New tasks start on Ling 3.1 Flash, which is unlimited. Switch models from the picker at the top of the chat.

What it can do

• List, read and search files in your project. These run without asking.
• Create and edit files. You see a diff first and choose Allow or Deny.
• Run commands like tests and builds, in your project folder. You approve each one first.

Choose how much it asks in the Harness settings: before every edit and command (the default), only before commands, or never. The agent can't open files outside the folder you chose.

Project instructions

Put conventions in an AGENTS.md file at the root of your project (build commands, code style, things to avoid). The agent reads it with every message. If there's no AGENTS.md, it reads FREEFLOW.md, CLAUDE.md or .cursorrules instead. It also sees your git branch, uncommitted files and recent commits. The chips under the message box show what it picked up.

Checkpoints and undo

Before the agent changes a file, the Harness saves a copy. Each message ends with a checkpoint card listing the files it changed: Undo there reverses that message (and anything after it), and Undo changes at the top reverses the whole task. Files it created are removed. If you edited a file yourself afterwards, undo leaves it alone and tells you. Changes made by commands it ran aren't tracked, so keep git handy for those.

@-mentions

Type @ in the message box to pick files. Their contents go along with your message, so the agent starts with the right context.

Plan mode

Choose Plan only in the approval menu and the agent can read and search but not edit or run anything. It replies with a numbered plan. Click Carry out this plan to switch back to your usual mode and have it build.

Cost and reliability

Each task shows the tokens it has used and what they cost from your weekly credit (unlimited models show Free). If the connection drops or a provider is busy, the Harness retries on its own, and it updates itself when a new version is out.

API keys

Keys start with ff-. You see the full key once, when you create it, so paste it straight into the Harness or a password manager. You can have up to 10 active keys: one per device makes it easy to revoke just one if a laptop goes missing.

Anyone with your key can spend your credit. If a key leaks, revoke it in the dashboard; it stops working at once.

Weekly credit

Every account gets $50 of credit each week. It refills every Monday at 00:00 UTC, and unused credit doesn't carry over. Each request on a credit model costs its input and output tokens at the rates on the models page.

When the credit runs out, those models return weekly_allowance_used until the next refill. The unlimited models (ling-3.1-flash, muse-spark-1.3, glm-5.3-flash) never count against it.

API reference

The API follows OpenAI's request and error formats. Send your key as a Bearer token. Base URL:

https://freeflow.surf/v1

GET/v1/models

Lists every model with its id, provider, credit tier, price and whether it's available.

curl https://freeflow.surf/v1/models \
  -H "Authorization: Bearer ff-your-key"

GET/v1/account

Shows how much of this week's credit is left and when it refills.

{
  "object": "account",
  "email": "you@example.com",
  "allowance": {
    "limit_usd": 50,
    "used_usd": 12.4,
    "remaining_usd": 37.6,
    "resets_at": "2026-10-12T00:00:00.000Z"
  },
  "unlimited_models": ["ling-3.1-flash", "muse-spark-1.3", "glm-5.3-flash"]
}

POST/v1/chat/completions

Checks your key, the model and your credit. Model requests run only in the FreeFlow Harness; requests from anywhere else get harness_required with a link to the download page.

HTTP/1.1 403 Forbidden

{
  "error": {
    "message": "FreeFlow models run through the FreeFlow Harness. Download it at https://freeflow.surf/download and sign in with this API key.",
    "type": "permission_error",
    "code": "harness_required",
    "param": null,
    "download_url": "https://freeflow.surf/download"
  }
}

Errors

Errors use the shape { "error": { "message", "type", "code", "param" } }. Check code in your logic; the message is written for people.

Stuck? Email support@freeflow.surf.