Skip to content
PerficaPerfica docs

First run on free models

You do not need a paid key to try Perfica. Three kinds of model cost nothing:

  • OpenRouter’s free models. Make a free OpenRouter account and create a key. Free models have a :free suffix on their name, and you can type the name straight into the model picker.
  • Google’s free tier. A Gemini API key from Google has a free allowance on several models.
  • Local models. Ollama and LM Studio run models on your own machine. Perfica finds them at their usual addresses (127.0.0.1:11434 for Ollama, 127.0.0.1:1234 for LM Studio) and needs no key for either.

Free tiers are slow on purpose: they allow a small number of requests a minute and a day. Perfica knows the published limits for OpenRouter’s free models and Google’s free tier and spaces its calls to stay inside them. See Models, keys and limits for what happens when a day’s allowance runs out.

The setup walkthrough

Section titled “The setup walkthrough”

The first time Perfica opens, a short walkthrough sets up four things. You can skip it and do each later.

  1. Language. What the app is written in for you. Change it later in Settings.
  2. A model. Add a provider key (or pick a local runner) and choose the default model: what every new bubble starts on. This is the only step that needs anything from outside the app.
  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.
  4. The Manager. Pick the mode the chat opens in.

A first loop that works

Section titled “A first loop that works”

The smallest useful board is one loop with a folder:

  1. Create a loopspace from the Basic Loop template (an Architect and a Coder) and give it an empty folder.
  2. Open the Manager, switch to Plan, and describe something small: a single-page to-do list in plain HTML and JavaScript. Answer its questions. Once you agree, it writes cards into the Task Book.
  3. Check the cards. Cards the Manager writes in Plan start as Approved. Cards you type yourself start as Draft, and loops never take a Draft.
  4. Press Play on the loop. Watch the bubbles take turns; the Run Log shows each pass.

When you want the full team (designer, reviewer, tester, a fixer on failure), ask the Manager in Build mode to lay out the board for you. See The Manager and Build.