Connect AI & choose models

The first-run wizard connects your AI providers and picks the models Atelier uses, so a fresh install is ready to work in a couple of minutes.

A fresh install ships keyless, so the wizard runs automatically the first time you open the console. It has two steps.

1. Connect your AI

Connect one provider or several:

Paste each provider's API key (or, for Ollama, your server URL). Each credential is validated against the provider before anything is saved — Atelier asks it for its model list, so "Connected" means a real answer came back — and it is stored on your own server, never in code or git.

Something else that speaks the OpenAI API

DeepSeek, Groq, OpenRouter, a LiteLLM proxy, vLLM, LM Studio — Atelier serves all of them through the OpenAI-compatible endpoint row. It's the one provider that asks for two things: the base URL to call, and an API key.

Give it the service's root address — https://api.deepseek.com, or wherever your own proxy lives. Atelier appends /v1 itself, so leave that off. Then, exactly as with any other provider, it asks the endpoint for its model list before saving anything: connect succeeds only if a real catalogue comes back.

(OpenAI and Mistral don't need this row — they have their own above, and Atelier speaks each vendor's native API rather than the compatibility shim.)

2. Choose your models

Atelier works in roles, not per-chat model picks. There are three chat roles — high thinking, task, and fast — plus image description and image generation.

You only have to answer one question: what matters most to you?

• Best value — the cheapest models that still do the job. Good for high volume and low stakes.
• Balanced — good results at a sensible price. The right choice for most sites.
• Best quality — the most capable models available. Costs more per turn.

Atelier fills in every role from the profile you pick, choosing only models the providers you connected can actually serve. Nothing is bound that your key can't run.

Want to decide each role yourself? Choose per role opens a picker for every one. Touching any of them switches you out of the profile and into your own selection — nothing is overwritten behind your back.

Because you bind a model to a role (never to a single conversation), swapping one model rebinds every studio that uses that role. Choose once, and the whole console follows.

Keeping the suggestions current

Which model is the right one changes on roughly a weekly cadence — models get retired, prices move, a provider's fast tier overtakes another's mid tier. So the profiles come from a document we publish and keep up to date at aincient-labs.com/atelier/models.yml (plain text — read it before you trust it).

Your install ships with a snapshot of that document, which is what you see by default and what keeps a fully offline install working. Check for updates, under the profiles, fetches the current one. That fetch is the only time Atelier contacts us, it happens only when you click, and it sends nothing about your site — see Privacy.

Supplying a key from the environment

You can hand Atelier a provider key through an environment variable instead of the wizard. There are two forms, and the name you choose decides who owns the key afterwards.

A key the server owns

ATELIER_ANTHROPIC_API_KEY=sk-…

This key is read fresh on every request and never written to the database — it survives no backup, appears in no dump, and rotates by changing the variable and restarting. Use it when the secret must not live in the database at all: a platform with managed secrets, a Kubernetes cluster, or any image you build from a database dump.

A starting key the site owner owns

ATELIER_DEFAULT_ANTHROPIC_API_KEY=sk-…

This one is a default, not a rule. It's copied into the site's credential store once, on the first boot after you set it, and from then on it's an ordinary key: it appears in the wizard normally, the owner can replace it, and if they disconnect it, it stays disconnected — the next restart won't put it back.

Because it's applied exactly once, changing the value later has no effect; the site already has its copy. And unlike the form above, this key does live in the database, so it will appear in backups and dumps.

The pattern

Both forms use the provider's id in capitals — ATELIER_MISTRAL_API_KEY, ATELIER_DEFAULT_OPENAI_COMPATIBLE_API_KEY, and so on. Providers that need a base URL as well take ATELIER_<PROVIDER>_ENDPOINT (or ATELIER_DEFAULT_<PROVIDER>_ENDPOINT); for Ollama, where the URL is the credential, that variable is all you need.

Seeds are applied automatically when the container starts. On an install that doesn't use the Atelier container, apply them yourself:

drush aincient:seed-credentials

Changing providers or models later

You can revisit the wizard any time:

• Open the avatar menu (top-right) and choose Set up AI providers, or visit /atelier?onboarding=1.
• Already-connected providers show as Connected, so you only fill in what's new.

To rebind a role without the wizard:

• Reopen the wizard from the avatar menu → Set up AI providers.
• Or from your terminal: atelier ai model set <role> <provider> <model>.