Providers and models

Connect your model accounts once, choose which models a Profile offers, and let the agent ask before it uses another one.

A connection is one named account with one provider. A Profile picks connections, enables their models and names the model new chats start with. That is all a Profile does: there is no routing table, no Smart mode and no backup model. Delegated work runs on the chat’s model unless the agent asks and you agree to another enabled one. Connections and Profiles belong to an organizational workspace; projects never configure them. Specialists are a separate catalog — see Definitions.

Connect a provider

Open Settings → Profiles & Providers and choose New Provider. The pop-up shows only the steps your provider needs:

1. Provider: pick a card, under Sign in with an account or Sign in with an API key. Cards carry the vendor’s icon.
2. Connect: choose how, such as Browser sign-in, API key, No key or AWS credentials. Skipped when there is only one way.
3. Details: the base URL, key or AWS region, as needed.
4. Name: keep the suggested name (Cursor, Cursor2, …) or type your own, such as CursorWork. Then Connect, Continue to sign-in or, for Claude, Install and sign in.
5. Models: Synoec lists the provider’s models with the limits it reports. Tick the ones you want and choose Activate; enter limits for any model the provider did not report. If the list fails, the step says why (rejected key, wrong address, server not running, untrusted certificate) and lets you fix it and retry.

Edit a saved connection, or add a model by name with Add a model manually, from its row. Model names come from the adapter, so the picker shows, for example, Codex’s gpt-6.1-sol as “Sol 6.1”.

Card	Connect with	Notes
OpenAI Codex	Browser sign-in (ChatGPT) or API key	The two billing domains never substitute for each other
Cursor	Browser sign-in or API key	Cursor’s agent runtime; sign-in opens a Synoec window
Claude	Browser sign-in	Optional Claude Code runtime, installed on sign-in
Google Gemini Agent	Browser sign-in	Google’s agent runtime in an isolated worker
Anthropic API	API key	Also Anthropic-compatible gateways
Google Gemini API	API key or Google developer sign-in	Developer sign-in is billed as API usage. Discovery lists only models the key can chat on: audio, video, image, managed-agent and retired families are left out, and each remaining model is checked with a free countTokens call
Amazon Bedrock	AWS credentials	Region and optional named AWS profile
Microsoft 365 Copilot	Sydney access token	Private BizChat protocol; may break without notice
OpenAI compatible	API key or No key	OpenAI/Mistral dialects, OpenRouter, Azure OpenAI, local servers
Ollama	No key or API key	Ollama on this computer, on another machine on your network, or Ollama Cloud
SystemOne compatible	API key or No key	Decision models, not chat — see Decision models

Your own endpoint. Choose OpenAI compatible, then No key or API key, and enter the base URL. On this Mac fills in the usual local address for LM Studio, vLLM and llama.cpp; with a key, Hosted covers services such as OpenAI, OpenRouter, Groq and Mistral. More services… searches the bundled models.dev directory by name or host and fills in the base URL. The search reads the snapshot shipped with Synoec, and lists only services whose base URL ends in /v1. Plain HTTP is accepted only for localhost and 127.0.0.1. Synoec reads /v1/models and shows any context and output limits the server reports for you to confirm. LM Studio reports no limits, so enter them yourself. A server whose /models entries each state capabilities.tools (and, if it has them, image generation and its controls) needs no catalog mapping: discovery builds one from what the server says, and a mapping you wrote is never replaced. A local model that writes a tool call as text, either a bare {"name": …, "arguments": …} object or one inside <tool_call> tags on their own lines, has it run through the ordinary tool path with the usual permissions.

Ollama. Choose Ollama, then No key for a server on this computer or another machine on your network (for example http://192.168.1.20:11434), or API key for Ollama Cloud (https://ollama.com). Plain HTTP is accepted for a private-network address only without a key. Synoec reads each pulled model’s context, tool, image and thinking support from Ollama’s own model list and leaves out embedding models. Chats use Ollama’s native API, which lets Synoec ask for each model’s context window on every request instead of relying on Ollama’s default.

Advanced provider settings on a connection holds Simultaneous AI requests, the endpoint, catalog mapping, Private HTTPS certificate and, for Cursor, Usage reporting. Adapter READMEs under packages/providers own exact protocol and authentication details.

Images. Any chat model can make an image, including one whose provider makes none: GenerateImage sends the request to an image model on the chat Profile’s connections. A Google connection lists its image models apart from its chat models, and a Codex connection uses its own model: an API-key connection shows up to two progressive previews, a ChatGPT sign-in goes straight to the finished image, and the finished PNG, JPEG or WebP is kept with the chat and comes back when you reopen it. Say which provider you want in the chat, or pin one with Image model in the Profile; Automatic tries the chat’s own provider first. Under Approve for me, using the chat’s own provider or the pinned model just runs; going to another provider asks which you meant, once per provider if you choose Always allow. Image requests count toward the serving connection’s budget and appear under it in Usage. Google’s image models have no free tier.

A compatible image service can declare internal optionsSchema, maxInputImages and mask in its image-tool binding. The agent can then select conversation images and rendering controls through GenerateImage; your prompt and model choices stay the same.

Thinking levels. Anthropic API models report their levels through Anthropic’s Models API. Google’s list only says whether a model thinks, so Gemini levels come from a table in its adapter; a thinking model missing from it still thinks and shows its reasoning, with no level to pick.

Credentials stay in Synoec. Keys and sign-ins live only in Synoec’s own credential store. Synoec never reads or changes the Codex, Cursor or Claude Code apps’ logins, so signing in or out of those apps does not affect a Synoec connection.

Claude account. At the Name step, agree to install the official Claude Code runtime (up to 284 MiB; not part of the base app), then Install and sign in. Its login and settings are private to this connection and separate from your own Claude setup; Re-authenticate and Sign out are on its provider row. Models are listed by the ID each selector resolves to for your account (such as claude-opus-5-5), so their limits fill in. Usage shows the account’s five-hour and weekly limits. The CLI’s estimated API cost is not a subscription charge.

synoec setup --provider cursor --connection CursorWork --connect-only
synoec setup --provider openai-compatible --connection local \
  --base-url http://localhost:11434 --credential-mode none --connect-only
synoec auth login --connection CursorWork
synoec models list --connection CursorWork --json
synoec models use <model> --profile Personal --connection CursorWork --add
synoec connections rename CursorWork CursorOffice
synoec connections remove CursorWork
synoec doctor

Add --manual --context-window <tokens> --maximum-output <tokens> to models use when limits are unknown. synoec providers discover and synoec models discover --provider <catalog-provider> browse public catalogs; they do not prove your account can use a model.

Removing a connection also deletes its stored key, dashboard session and OAuth client file (unless another connection shares that file), so a later connection with the same name starts signed out. It does not revoke the key with the provider; for Cursor, revoke the key named “Synoec” on its dashboard.

Simultaneous requests

Each connection’s Simultaneous AI requests limit is shared by every chat, subthread, Task, window and CLI run that uses it. Providers that own their endpoint start at 4 (Microsoft 365 Copilot at 2). An OpenAI-compatible, Ollama or SystemOne endpoint has no adapter default: on your machine or local network it starts at 1, elsewhere at 4 until you set it. Work beyond the limit shows Waiting for capacity and runs in turn; a slot held by an engine that exited is released on its own. When a service answers with Retry-After, or a local server says its model is loading, its GPU is busy or its queue is full, the next request on that connection waits as long as it asked, at most two minutes. Running threads under Settings → General → Focus & delegation caps how many conversations run at once.

Private HTTPS endpoints

For a self-hosted server with a private certificate, open the connection’s Private HTTPS certificate and choose Get from server, or paste the public PEM. Reading trusts nothing and sends no request; compare the SHA-256 fingerprint shown with what the operator sees, then save.

synoec connections trust-certificate decisions --certificate server.pem
synoec connections remove-certificate decisions

Trust is bound to the workspace and the exact HTTPS origin. Hostname and expiry checks stay on, redirects stay forbidden, and the system trust store is not touched.

Create a Profile

In Settings → Profiles & Providers, choose New Profile: name it, tick the Included Providers, choose the Default chat model, then Save Profile. Pick the active Profile from the picker at the bottom of the left rail. The composer’s model picker can still choose any enabled model per chat.

Profiles saved with the retired Manual, Smart, Smart Max or Off routing load with the same chat model and drop the rest; the original file is kept beside it as provider-configuration.json.pre-agent-routing.

Which model does the work

Work	Model
A new chat	The Profile’s Default chat model
A chat after you pick a model in the composer	That model, for every later turn of that chat
A Task (hidden subagent)	The chat’s model and options, or the Profile model you approved for it
A subthread	The model you chose when it started; fixed while it works

Each chat keeps its own model. Chats in a workspace share one engine, and every turn, queued turn and continuation carries its chat’s model, so one chat never inherits another’s. Picking another enabled model, effort or fast mode keeps the chat’s engine, with its tools, MCP connections, storage and history; the next turn runs on the new choice with no provider setup.

When the agent thinks another enabled model is clearly worth it, it asks in a box inside the running turn; the composer stays free.

• For a Task: Keep using this chat’s model, Use connection model, or Other to pick any enabled Profile model. The Task returns its result inline either way.
• For a subthread: first New thread or Do it here, then the suggested model or Other, which also lists this chat’s model. A subthread on another model starts fresh with only its brief.

Several questions in one turn are answered back to back, counted 1/2, 2/2; Tasks naming the same model share one answer. The box appears only in a turn you started; elsewhere only a remembered “always” preference can pick another model.

Your answers become one project memory per kind of work (a Task’s role, such as search, else its Specialist), tagged specialist-model, for example “Model preference for search work, from 4 choices: cursor · composer-2.5 chosen 3 times; codex · gpt-6.1-sol kept 1 time.” The agent reads that tally when it next suggests a model. An answer that says to always use a model is kept on its own and skips the box for that model. Edit or forget either like any memory.

Context work follows the chat: compaction, document summaries, session commits and lesson validation run on the chat’s model, and recall before a turn uses only local models.

When a provider cannot answer

A provider failure reads as an ordinary reply saying what would help, with no error mark or status code: the provider can’t be reached, its rate limit or quota is hit, the key or sign-in was refused, the model is unavailable, or the chat has grown too long for the model. The saved receipt keeps the exact code. A server that took the request but did not answer in time is reported as slow, not as unreachable (“A local model may still be loading; send your message again”). Nothing moves a chat off the Profile and connection you chose: a connection whose sign-in was never finished still starts the engine, and only its own turns report the missing sign-in. Send the message again, or pick another model.

Instructions placed after the conversation (the presentation tail behind the newest message, the guidance added in a full window) reach each provider in place: Codex as developer messages, and Anthropic, Gemini, Bedrock and OpenAI-compatible servers as user text marked as coming from the host, since those take no system role mid-chat or hoist a later one to the top. Merged into the system prompt, each change to them would re-read the whole chat. On OpenAI’s own endpoints the chat’s session id is sent as prompt_cache_key, so its steps reach the server holding the cached prefix.

Limits

• A saved credential, a discovered model and a successful request are separate facts; a credential alone does not prove access.
• Model limits come from discovery, then published metadata, then editable defaults; published limits may differ from serving limits.
• Choosing a model never grants tools or authority; a Task or subthread on another model keeps the usual permission prompts.
• Saved changes apply to new work; running work keeps the model it started with.
• A connection a Profile includes cannot be removed until you take it out of that Profile.

Related

• Usage and pricing · Decision models
• Tasks and subthreads · Operations
• Provider routing contract (attempt binding and admission)

Decisions behind this page: 0124, 0185, 0197, 0198, 0205, 0207, 0221, 0222, 0226, 0228, 0229, 0239, 0254, 0255, 0265, 0266, 0268 — see the decisions index.