Models and providers
An agent needs a model provider: an API key, a local model server, or a Claude, ChatGPT or Grok subscription signed in on the daemon.
On this page
An agent needs a model provider: an API key, a local model server, or a Claude, ChatGPT or Grok subscription signed in on the daemon.
API keys and local servers
/provider add (or the welcome’s “Connect a model”, or the palette) lists
every provider Studio knows: subscriptions first (they open the sign-in
dialog), then APIs (Anthropic, OpenAI, OpenRouter, Gemini, Groq, …), local
servers (Ollama, LM Studio, …) and any OpenAI-compatible URL. / filters.
The form asks for a name, the base URL when needed, the API key (as dots,
with where to get one) and an optional default model.
The key goes once to the daemon, which keeps it in its secret store: the OS keychain, or the owner’s passphrase file where there is none. It is never written to the settings file, never shown again, and never returned (only “has a key”). When that store is locked, the identity dialog opens first.
| Command | Action |
|---|---|
/provider add [preset] | Add one |
/provider list | Runtime › Providers: every provider and which agents use it |
/provider remove <id> | Remove it and its key (asks) |
Studio reads keys added here from the same keychain entry, so the provider works in both apps. Keys added in Studio stay in Studio’s settings file as before.
One-shot: adf providers (providers and which agent resolves to which).
Subscriptions
Agents on a subscription need the daemon to be signed in. The daemon’s ChatGPT and Grok sign-ins are its own, separate from Studio’s. Claude’s is not: it is the sign-in of the Claude Code installed on the daemon’s machine, shared with Studio and with Claude Code itself.
| In the app | One-shot | How |
|---|---|---|
/login chatgpt | adf auth login chatgpt | Opens your browser; the URL is shown too (c copies it) in case it does not open |
/login grok | adf auth login grok | Shows a device code and URL; approve in any browser |
/login claude | adf auth login claude | Runs claude auth login, which opens your browser; the URL is shown too. Paste the code if the page shows one |
/auth | adf auth | Status of each, and which providers have keys |
/logout <provider> | adf auth logout <provider> | Sign out (the app asks first) |
Claude requires Claude Code 2.1.248
or newer on the daemon’s machine. adf auth logout claude runs claude auth logout, which signs Claude Code out on that machine too.
When the daemon runs on another machine, ChatGPT’s browser callback is
received on your machine and handed to the daemon (relay mode, chosen
automatically for a remote --url; --relay / --loopback override it).
Grok’s device code works anywhere. For Claude, open the shown URL in any
browser and paste the code the page shows. Details:
Remote daemon.
An agent whose subscription is not signed in shows signed out on the Fleet
and ChatGPT not signed in — /login chatgpt in Chat.
Pick a model
- New agent: the wizard (
/new) takes an optional provider and model;adf new --provider <id> --model <id>. - Existing agent:
/modelopens a picker (providers with their sign-in state, then models; type to filter), or/model [provider/]model. - Per loop: on
main,/modelchanges the agent config. On an inner loop it sets that loop’s own model override;/model inheritclears it.
adf usage [agent] and Runtime › Usage show token usage by model.
Media when changing models
The table below is what ADF can send to each provider. It says nothing about
whether a model understands that media. That is your choice: set
model.multimodal.image, .audio, and .video per agent to match the
model you selected. ADF does not detect model capabilities. The toggles can
only narrow the table, never widen it:
| Provider | Image | Audio | Video |
|---|---|---|---|
| Anthropic, Claude subscription | yes | no | no |
| OpenAI, ChatGPT subscription | yes | no | no |
| Grok subscription | yes | no | no |
| OpenRouter, OpenAI compatible | yes | yes | yes |
A new chat message with an attachment the model cannot take is refused with
the reason (400 media_unsupported on POST /agents/:id/chat). It is never
sent without the attachment. Studio’s composer refuses such a file before
upload and shows the reason. GET /agents/:id/status answers each loop’s
effective set as media.
Attachments are files
Every attachment is a file in the agent’s Files. A message stores a reference
to the file (a file_ref content block), never the bytes:
- Studio uploads, and
adf chat <agent> --attach <file> <message>, write the file toloop-upload/first. A taken name gets a number (cat-2.png). The text you type is stored as typed; each file is its own part of the same message. Studio shows the files as chips under your text, the terminal app as one line each ([image: cat.png]). - Images, audio and video sent inline to
POST /agents/:id/chat(data URIs) are saved toloop-upload/and replaced by a reference. Afile_refthat names no file in the agent’s Files is refused with400 file_not_found. - Attachments from other agents and channels are saved under
imported/. - When the agent reads an image, audio or video file (
fs_read,catinadf_shell, MCP tool media), the tool result is followed by a reference.
Each request loads the referenced files from Files. A model that takes the
kind receives it, however old the message is. Before each attached file the
request carries one line for the model with the file’s path, type and size
([Attached file: loop-upload/cat.png (image/png, 48.2 KB). Read it with fs_read.]), so the agent can open it with a file tool. That line is built
from the reference on each request and never appears in your text.
Messages stored before this change hold [Uploaded file: …] lines in their
text. They are not rewritten; Studio and the terminal app show those lines as
chips too. For any other model the request
carries a placeholder, and the first request of a turn that leaves any out adds
a System row to the loop that names them and why. Switching models back and
forth therefore never loses an attachment.
A request leaves a reference out, with a placeholder that gives the reason, when:
| Case | Placeholder |
|---|---|
| The file was deleted | [deleted: photo.png] |
The file is over its size limit (limits.max_image_size_bytes, max_audio_size_bytes, max_video_size_bytes) | [image not sent: photo.png is 7.2 MB, over the 5.0 MB limit] |
| The request media limit is reached | [image not sent: photo.png, outside the request media limit (20 files, 20.0 MB)] |
Request media limit
One request carries at most 20 referenced files and 20 MB of them, counting only the files it would send as media. Providers refuse larger requests: Anthropic takes at most 100 images and 32 MB per request.
| Field | Default | Meaning |
|---|---|---|
context.max_request_media_files | 20 | Most files one request carries |
context.max_request_media_mb | 20 | Most MB (MiB) one request carries |
Both are positive whole numbers with no upper bound. ADF does not lower them to fit a provider; a provider that refuses the request fails the turn with its own error, shown in the chat. In Studio: agent Config › Context › Media.
Past either limit, the oldest files are left out until the rest are within
half of both limits. The newest file is always sent. Every request that
leaves files out for this reason starts its turn with a System row that
counts them, for example [System] Not sent to this model: 11 images (older than the request media limit: 20 files, 20.0 MB). History keeps every
reference.
Dropping to half protects the prompt cache. A window that moved by one file on every new attachment would change an early part of every request and miss the cache each time. With the drop to half, the files sent stay the same for the next half a limit of attachments (10 with the defaults), so those requests repeat the same bytes and hit the cache. The window depends only on the history, so it is the same after a restart.
Renaming or moving a file updates every reference to it. Deleting a file
keeps the reference as a tombstone: the request and every chat view (Studio,
the terminal app) show [deleted: name], and turns run as before. A file
overwritten in place is sent with its new contents.
A reference resolves to the same bytes on every request, so older messages stay byte-identical and the cached prompt prefix holds. Deleting or changing a referenced file changes the prefix once. Changing models requires a separate cache warmup.
Prompt caching
Direct Anthropic and Claude models selected through OpenRouter cache the
system instructions and the end of conversation history before temporary
runtime hints. OpenAI and ChatGPT subscription requests carry a
prompt_cache_key that is stable per agent loop. Compaction summaries and
model_invoke calls are not sent again, so they get no cache markers. Cache
hits still depend on the provider’s minimum token count, retention window, and
matching prompt prefix. Explicit raw cache_control request parameters
override this default policy; an empty value disables the default markers.
Claude subscription sessions use Claude Code’s own caching.