Connecting a provider
Window → Customize → AI, or Settings → AI.
Two ways to power it
| Option | Status |
|---|---|
| Motion AI — the first-party provider account, metered and billed, nothing to manage | Disabled while in development. The server says so if you try |
| Your own key — OpenAI, Anthropic or Gemini | Works today |
How your key is handled
You paste it once
In Settings → AI, choose a provider and paste the key.
It goes to the gateway
The key is sent once to the backend gateway.
It is stored encrypted
AES-encrypted against your account, server-side.
The renderer never keeps it
It is not held in the renderer process and not written to browser storage.
Streaming is proxied
The server’s /ai/stream endpoint proxies the provider’s byte stream. The agent
loop itself runs in the renderer, against your live scene.
This design exists for a reason. The renderer holds your account token; a provider key sitting beside it in local storage would be one more thing worth stealing. The same reasoning is why plugins run in a Worker with no storage access at all.
Choosing a model
The composer has a provider and model picker. Which model to use is a cost-versus-capability trade-off you make per task:
- Structural work — “build a five-card layout, stagger them in” — a smaller model handles well.
- Creative direction — “make this feel like a premium hardware launch” — benefits from a larger one.
Credits and billing
When the first-party provider is enabled, AI usage is metered per plan through the gateway. The plan catalogue, the credit balance and whether checkout is open all come from the server — nothing about billing is decided client-side.
With your own key, you are billed by your provider directly and Premation meters nothing.
If it is not working
| Symptom | Likely cause |
|---|---|
| The panel says the assistant is unavailable | The companion server is not running. It is expected on port 4000 |
| The provider is rejected | The key is wrong, or the account has no quota. The error text comes from the provider |
| Motion AI is greyed out | Expected — it is disabled during development. Use your own key |
| A run starts and nothing lands | Check the mode: Manual waits for you to press Apply |