1. Why does this exist? The API key pain.
Normally to use AI you need to:
- Go to Google AI Studio, create an account, and generate a key
- Or go to OpenAI, add billing, and generate a key
- Or install Ollama locally and pull 4GB models
That's annoying for a 30-second test. Puter.js is Accelerated Logic's free tier.
Think of it like this: Puter runs a shared proxy that already has access to a bunch of frontier models — GPT, Claude, Gemini, DeepSeek, Qwen, Llama — and lets you call them directly from your browser without your own key. No signup for you, no credit card, no environment variables.
✓ You SHOULD use it to:
- Test the app in the first 10 seconds
- Compare 3-4 models side-by-side for free
- Do quick coding / writing tasks where you don't need 1M token context
✕ You SHOULD NOT rely on it for:
- 24/7 production agent loops (it has community quotas)
- Ultra-long context — like dumping an entire 500-page codebase at once
- Anything where you need guaranteed uptime and 100x requests per minute
That's when you'll want a direct key — covered in Parts 3 and 4.
2. Where to find it — Model Organizer
Everything about models lives in one place: Model Organizer.
Click the model name in the bottom composer — the pill that says something like DeepSeek V4 Flash or Select AI. Or click the brain icon in the header.
It opens a modal with steps at the top: Choose Provider -> Equip Models.
Step 1 is Choose Provider. You'll see provider cards:
- Gemini Nano (Built-in) — green Active badge if Chrome supports it
- Puter.js — Free cloud proxy for multiple AI models
- Gemini API — Direct access using your own API key
- WebLLM — Run models locally in browser via WebGPU
- Ollama — Run models locally via Ollama
- OpenAI / Anthropic Compatible — Custom API endpoints
Click Puter.js. That's it for provider selection.
3. Equipped Models vs Active Model — this concept matters
This confuses everyone at first.
Think of this as your toolbox. You can equip up to 15 models if you want. They show in the "Equipped Models" grid at the top of organizer. These are the models that appear in your composer dropdown for quick switching.
The ONE model actually answering right now. Shown in a bold blue pill in the composer. Your last selected equipped model becomes active.
You equip DeepSeek V4 Flash, Claude 3.5 Sonnet, GPT-4o-mini, and Llama 3.1 8B. Your Active model is DeepSeek. You chat for 10 minutes. You hit a coding bug — you click the model pill and switch to Claude 3.5 for this answer only. Now Claude is Active. You can switch back anytime without re-equipping.
If you only have one equipped model, that one is always active.
4. Actually equipping free Puter models
After you click the Puter.js provider, you proceed to the Equip Models step.
Top displays: X models equipped with a Clear All button.
Below: Available Models — X Found. Each model card shows:
- Model name: e.g., DeepSeek V4 Flash 0731, Gemini 3.5 Flash-Lite, GPT-5.5 Omni, Claude Opus 4.8, Llama 3.1 8B
- Provider badge: Puter.js in blue
- Visual Badge: Displays an eye/image icon if it can see images
- Context window: CTX: 128k, 1000k, 1M — how much context it can hold
- Pricing info: Informational token rate indicators
- Selection Checkbox: Click anywhere on the card to equip. It turns blue with a checkmark and moves to the Equipped grid.
Don't equip 30 models at once. Equip 3-4 you actually use:
- DeepSeek V4 Flash: Cheap, fast workhorse for coding
- Gemini 3.5 Flash-Lite: Best free vision for screenshots
- Claude 3.5 Sonnet or Opus: Best for reasoning / complex planning
Now click Save & Close. Your composer pill immediately updates.
5. Custom Puter Model IDs — the hidden power feature
At the top of the Puter provider view, you'll see an input box: Custom Puter.js Model ID.
Puter's proxy supports hundreds of models that aren't listed in the default cards because they rotate fast. If you know a model string ID like anthracite-org/nebulite-72b or meta-llama/Meta-Llama-3.1-405b, you can type it there and click Equip.
Type the ID, press Enter or click Equip — it will instantly create a new equipped card puter:that-id and make it Active. This is how you test brand-new releases on day one before card listings are added.
If you typo the ID, you'll get a "Model not found" error when chatting — simply remove it from the Equipped grid using the trash icon and try again.
6. Switching models inside a chat
You have two convenient places to switch models:
Click it to open your compact equipped list. Click any model — future messages will use it. Previous messages remain unchanged.
Hover under any assistant response. Click Model: [Name] -> select a different model. It immediately Regenerates that specific answer with the new model for instant A/B testing.
7. Vision, context, and speed — what the badges mean
Means you can upload images. Try uploading a website screenshot and prompting "Clone this UI in React". If a model is not visual, images are omitted automatically with a warning in Thinking Trace.
4k = ~3 pages of text. 128k = ~90 pages. 1M = entire codebase. If context reaches 95%+, start a New Chat or clear attached files.
Puter models route through a shared cloud endpoint (first token ~2-3s). WebLLM after initial model download runs in local RAM (<100ms response).
8. The Puter Sign-In Flow — what to expect
The first time you invoke a Puter model:
- Browser popup:
puter.com wants to open... Allow popups?-> Click Allow. - A popup window opens: "Sign in to Puter to continue". Create a free Puter account in 10s or sign in with an existing account.
- After sign-in, the popup window closes automatically, and your chat response streams instantly.
If popups are blocked, check your browser address bar's popup-blocked icon, allow popups for this site, and click Regenerate on your prompt.
You only need to sign in once per browser session.
9. Privacy, quotas, and limits
Puter routes prompts through its service to the model provider. Some other remote providers also use the Accelerated Logic proxy, while local models process prompts on the configured local runtime after setup. Check the data path before sending sensitive information; a local model does not make unrelated app traffic offline.
Because Puter.js is a free community service, fair-use rate limits apply. If you hit a 429 limit, the client auto-retries with exponential backoff.
10. When to graduate from free to paid/direct
Prototyping, learning React/TypeScript, occasional coding, and screenshot vision tasks.
You need 1M token context windows, daily high-volume agent loops, or Imagen image generation.
Running an already-downloaded local model or keeping a prompt out of a hosted model provider's request path.
11. Troubleshooting Puter
You have 0 equipped models. Open Organizer -> Puter -> equip at least one model card.
The sign-in popup was blocked or closed prematurely. Click Regenerate to trigger the popup again.
Ad blockers or firewall rules may block js.puter.com. Whitelist the domain and refresh.
Try DeepSeek V4 Flash or Gemini Flash-Lite for faster inference. Disable Auto Memory to lower input token size.
Equip a model with an active 👁️ Visual badge. Text-only models will skip image attachments.
12. The Built-In AL Router — Free Inference Without Even Puter
Puter.js is not the only zero-setup path. A fresh workspace ships with AL Router as its default connection — a built-in route across a rotating pool of free, no-credential model services. No account, no API key, no signup popup: your first message just works.
Three AL Router modes appear in the Model Organizer like any other model:
AL Router · Fast— one free service answers; if it is rate-limited or unavailable, the request is routed to another free service. This is the default for new workspaces and is the same model that answers anonymous/fresh-install chats.AL Router · Reviewed— one model drafts, a second independent model reviews the draft and writes the final answer. Two model calls; slower, but noticeably better on reasoning-heavy questions.AL Router · Multi-agent— two independent drafts are compared and refined by a final model. Up to three model calls; the slowest mode, reserved for difficult prompts where you want built-in cross-checking.
How it behaves under the hood, verified against the built-in router implementation: on a rate limit (429) or connection failure the request is retried on the next free service automatically, and the response records which service answered. A partial response is never silently spliced with output from another service — if the stream fails mid-answer, the error surfaces instead of corrupting it. An invalid request (400) is not fanned out across the pool, and cancelling a stalled request stops it immediately rather than failing over. Treat every mode as best-effort free capacity: no uptime guarantee, no private SLA, and prompts are processed by third-party services.
When to pick what: Fast for daily driving and instant first impressions; Reviewed for homework, plans, and tricky debugging; Multi-agent for high-stakes answers where you would otherwise equip several models yourself. Equip Puter models alongside AL Router — they are independent entries in the Model Organizer.
13. Reading Provider Error Messages Like a Pro
Every model error the app surfaces falls into a small set of buckets. Knowing the bucket instantly tells you whether the problem is your key, your quota, your prompt, or the provider:
| Signal | What it usually means | What to do |
|---|---|---|
| 400 / invalid request | The request itself is malformed — bad parameters, context too long, unsupported payload | Shorten the prompt, detach oversized files, remove unsupported options. Retrying unchanged will not help. |
| 401 / 403 | Authentication rejected — missing, expired, or wrong-scope key; or the model is gated for your account | Re-enter the key in the Model Organizer; confirm the key has access to the specific model; check Puter sign-in state. |
| 404 | Model ID does not exist at that endpoint (wrong tag, retired model, typo in a custom ID) | Check the exact model ID; for Ollama run ollama list; for Puter custom IDs, remove and re-add the card. |
| 429 | Rate limit or quota exhausted — the free tier is doing its job, not a bug | Wait and retry, switch to another equipped model, or reduce request size. AL Router modes already fail over between free services on 429. |
| 5xx / network error | The provider (or the path to it, or an ad-blocked domain) is down or unreachable | Retry once; try another model; whitelist js.puter.com if you use an ad blocker; check provider status pages. |
| Context overflow | Prompt + history + files exceed the model's context window | Start a New Chat, unpin heavy files, or let the relevant-snippet optimizer shrink large attachments (Part 5). |
14. A/B Testing Two Models on the Same Task — A Method That Works
Free tiers make model comparison cheap. Do it methodically instead of vibes-based:
- Pick one representative prompt. Use a real task you care about (e.g. "Refactor this 40-line function and explain the tradeoffs"), not a toy trivia question.
- Fork the chat twice. Get one complete answer from model A, click Fork on your original user message, and ask model B the identical prompt. Each branch holds exactly one model's answer to the identical context.
- Score on three axes: correctness (does it run / is it factually right?), instruction-following (did it do all the asks?), and style (format, tone, concision). Resist letting a pretty answer beat a correct one.
- Repeat on a second, different prompt before declaring a winner — model rankings flip across task types. A model that wins on code may lose on long-form writing.
- Commit and declutter: keep the winning branch, delete or archive the other, and equip the winner. Re-run the comparison monthly — free-tier models rotate and improve silently.
For systematic testing, the Model Organizer's Provider Test Arena runs the same prompt across equipped models concurrently per provider and sequentially within a provider, reporting first-token latency and tokens per second — ideal for performance, less so for judging answer quality (Part 23).
15. Fair-Use Limits — What They Look Like in Practice
Free services are subsidized capacity, not a utility. Three practical consequences:
Ten prompts in ten seconds will trip rate limits sooner than ten prompts spread over ten minutes. The queue backoff (Part 8) exists precisely to pace queued work through free tiers.
Community free tiers degrade at global peak times. If everything feels sluggish, switch models rather than assuming your setup broke — and avoid diagnosing "bugs" at 9am on a weekday.
Free tiers often enforce tighter effective limits than the advertised window. Anthropic-style 1M-token prompts are plan-dependent; treat >100k-token prompts on free routes as unreliable and trim context instead.
None of this makes free tiers worse value — just bounded. The moment you notice the boundary weekly instead of monthly, that is your signal to graduate to Part 3 direct keys or Part 4 local models.