Setup

CoDev Desktop needs a model provider before it can do anything, and it will not let you past that. On a fresh install it opens a setup dialog that cannot be dismissed until a provider exists — no half-configured state, and no quietly chatting against something you did not choose.

The first-run dialog

It offers the same three paths as the CLI's codev configure:

Login with SSO — signs you in with your CoDev account in the browser, then asks which model to make the default. If the machine cannot open a browser, the dialog offers the link to paste somewhere that can.

Connect provider — Anthropic, OpenAI and the other providers CoDev knows about, each asking for whatever it needs (usually an API key). See Providers.

Custom provider — any OpenAI-compatible endpoint. It asks for a display name rather than an id: type "Acme AI Gateway" and the id is slugged from it (acme-ai-gateway), previewed live under the field, while the model picker shows the name you typed.

The gate applies to the local server only — a remote server you add has its own providers. Escaping any of the three sub-flows returns you to the dialog rather than past it, and finishing setup somewhere else (another window, or codev configure in a terminal) closes it on its own.

Signing in reaches your sandboxes too

A sandbox is handed its model provider when it starts, so a sandbox that was already running when you finished setup would otherwise have no model. Finishing setup restarts the sandboxes that are up, so the model you just picked is there in Work as well.

Only running sandboxes are touched, and nothing is interrupted: setup is only offered while no provider is configured, so those sandboxes had nothing to work with either.

Each sandbox also asks the gateway for the full model list when it starts, so Work offers what Code offers rather than the single model recorded at sign-in. The answer is reused across sandboxes and looked up again only when you sign in again; a gateway that cannot be reached costs you a shorter model list, not a sandbox that refuses to start.

Getting a new API key

Gateway API keys expire on a schedule CoDev does not set. When yours does, the app handles it two ways.

By itself. The app checks the key when it starts. If the gateway has rejected it, the app quietly fetches a new one using your existing session, and you never see it happen. Only when that is impossible — no key at all, or a session too old to renew — does it ask you to sign in again.

On demand. Get a new API Key... fetches one whenever you want:

• macOS — the CoDev menu, next to Settings
• Windows and Linux — the File menu, next to Settings
• Every platform — the command palette

A gateway that cannot be reached is never treated as a bad key, so a flaky network or a VPN that is still connecting will not sign you out.

Changing it later

Everything the first-run dialog does is available afterwards from Settings → Providers, and from codev configure in a terminal — both write to the same config, so it does not matter which you use.