Running without an AI provider key

A fresh install ships with one provider switched on — poolside — and its laguna model selected as the default. Everything else is off, because a list of vendors you have no key for is not a working state.

The one thing that catches people

Putting the key in .env is not enough on its own.

The key is read from the provider's row in the database, not from the environment at the moment of the call. The environment is only where the seeder gets it from. So a key added to .env after the install has already been seeded is a key nothing has copied anywhere yet, and every call still fails.

Either re-run the seeder, which copies it across:

php artisan db:seed --class=AiProviderSeeder

…or paste it straight into the provider in the admin panel, which writes the same row. A later re-seed will not overwrite a key entered there.

What a missing key looks like

Not a message about keys. The provider answers HTTP 403, the platform turns that into a failure, and what you see depends on where you were:

• •in the support chat, "I cannot reach my assistant service at the moment"
• •in an agent run, a step in the trace marked Error

If you see either, check the model screen first. A model with no key reads Not usable, and that badge is the fastest answer to "why is nothing answering".

The fallback, and what it is not

With no usable provider at all, agents fall back to heuristic-dev — a rule-based planner that matches your words to tool names.

It exercises the entire pipeline: planning, validation, policy, approval, execution, tracing and metering. Everything you see is real behaviour, not a simulation, which makes it genuinely useful for local development.

What it is not is a language model. It matches verbs and nouns, so "show me today's orders" works and an unusual phrasing may not. It refuses to run in production, deliberately — a keyword matcher quietly standing in for a model on real traffic is worse than an outage, because nothing about the answers says so.

Using a different vendor

Anthropic, OpenAI and Google are all in the catalogue, switched off. Enable the one you want in the admin panel, add its key, and point the default at one of its models.

One caveat worth knowing before you enable a second vendor: re-running the seeder resets which providers are on to the shipped state. Your models, prices and keys are left alone, so switching it back on is one click — but it is a click, and it is easy to lose an afternoon to it after a routine re-seed.