Skip to content
PerficaPerfica docs

First run on free models

You do not need a paid key to try Perfica. The first screen of the setup walkthrough asks one question: Start free or I have a key.

Start free

Section titled “Start free”

Start free sets you up on free models in about two minutes. It asks for two free keys, each made on the provider’s own site, and neither needs a card:

  • OpenRouter. Sign in at openrouter.ai, press Create Key and copy the key it shows you once.
  • Google Gemini. Sign in with a Google account at aistudio.google.com, press Create API key and copy it.

Paste each key into its row and press Save. Keys stay on your computer. One key is enough to start; with both, Perfica moves to the other provider when the first one runs out for the day.

When you press Continue, Perfica puts the free models into one pool, Free models, and makes it your default model. Every bubble you place starts on it, and so does the Manager. The pool holds:

  • Laguna S 2.1 and Nemotron 3 Ultra on OpenRouter. These are the free models Perfica’s own model check found using its tools correctly.
  • Gemini 3.8 Flash and Gemini 3.5 Flash-Lite on Google’s free tier.

Start free stays in Settings (the gear, top right) › APIs › Free models, and in simple mode’s key prompt, if you skip it now.

The rest of the walkthrough

Section titled “The rest of the walkthrough”
  1. Language. What the app is written in for you, when the app offers more than one.
  2. A model. Start free, or I have a key: add a key for a provider you already pay for (or pick a local runner) and choose the default model. See Add a provider key.
  3. Your first loop. Name it, choose a starting shape, and pick the project folder it works in. The folder is optional, but without one the agents can talk to models and cannot touch files. If the folder is not a git repository yet, the walkthrough says Perfica will make it one.
  4. The Manager. Pick the mode the chat opens in.

A first loop that works

Section titled “A first loop that works”

Your first loop is your own idea:

  1. Open the Manager in Plan and describe what you want, in a sentence or two.
  2. Answer its questions. On free models the Manager plans a small first version, at most five cards, that can run end to end today, and it tells you what it left for later. Once you agree, it writes the cards into the Task Book as Approved.
  3. Switch to Build. The Manager proposes one loop with two or three bubbles; press Build it.
  4. Press Play. Watch the bubbles take turns; the Manager’s Log tab shows each pass.

When a free tier runs out

Section titled “When a free tier runs out”

Free tiers allow a few dozen requests a day. When one runs out in the middle of a run:

  1. Perfica moves to the other free provider, if you added both keys.
  2. When both are out, the loop pauses where it stopped, and a notice says when it will try again. No error is counted and nothing is lost.
  3. The loop then starts again by itself: at the time the provider gives for its reset, or otherwise after 5, 10, 20 and 40 minutes and then every hour. It keeps trying for as long as you leave the board alone, so a run you leave overnight carries on when the allowance comes back. Pausing or stopping the loop stops the retries.
  4. The notice has an Add a paid key button, and Play tries again straight away.

Perfica keeps running while its window is closed, from the tray. Quitting the app stops the retries; press Play when you open it again.