AI Assistant
The AI assistant adds a chat panel to the admin where you can ask an agent to create, edit, reorder, or remove content. Every tool the agent calls is one operation on the CMS server, so it reaches exactly what the interface reaches, is validated exactly as your own edits are, and routes every change through your draft branch and pull/merge request.
How it works
Section titled “How it works”The agent loop and the chat interface run in the browser; the tools it calls and the credential it spends do not.
A tool call is an ordinary CMS API request, authenticated by the same session cookie everything else uses.
Model requests go to a relay the integration serves at /_astronaut-cms/api/ai/chat/completions, which adds your gateway credential and forwards the request.
The relay holds no secret of its own: credentials come only from the server environment, most of it injected by your platform.
Keeping the loop in the browser is deliberate. Each relay call is a single model round-trip rather than a whole multi-step conversation, so no serverless duration limit can cut a turn in half.
Requirements
Section titled “Requirements”The CMS needs an Astro server adapter regardless (@astrojs/node, @astrojs/netlify, @astrojs/vercel, @astrojs/cloudflare), so the assistant adds no new deployment requirement beyond the gateway itself.
Where the relay runs decides what it costs
Section titled “Where the relay runs decides what it costs”This is the single biggest cost decision the assistant involves, and it is a hosting choice rather than a setting.
The relay is a Fetch-API streaming proxy that does almost no work of its own: it attaches a credential, forwards a request, and pipes bytes back. But it is held open for the whole model response, because that is what proxying a stream means. The agent loop runs in the browser, so no single call spans a whole turn — but a turn of n steps is n calls, each held for one model response.
What that costs depends entirely on how your host bills a function that is waiting rather than computing:
| Host | Runs as | Billed on | What a long generation costs |
|---|---|---|---|
| Cloudflare | Workers, at the edge | CPU time | Effectively nothing: waiting on the model is not CPU time, and there is no duration cap to plan around |
| Vercel | Serverless function | Wall-clock duration | The full length of every model response, on every step |
| Netlify | Serverless function | Wall-clock duration | The same, and capped at 10s on the free plan, which one long single-shot generation can hit |
The Astro adapters run on-demand routes at the edge only for Cloudflare; Netlify and Vercel run them in serverless functions (edge is for middleware only), which is why the three differ.
Bring your own key
Section titled “Bring your own key”By default the deployment holds one gateway credential and every model call is proxied through the relay, which is what lets the deployment enforce the model list, the output ceiling and the per-editor rate.
The alternative is to ask each editor for their own key:
cms({ ai: { enabled: true, credentials: "byok", gateway: { type: "custom", baseUrl: "https://gateway.example/v1" }, models: ["anthropic/claude-opus-4.7"], },});The key is entered in the assistant panel, kept in sessionStorage, and sent straight to the gateway.
It never reaches your server, and the relay route is not part of a byok build at all.
What you get. No function invocations for inference, so none of the billing above applies. No shared budget for a compromised session or a runaway loop to drain. No gateway credential on your server to hold, rotate, or leak.
What you give up. The deployment enforces nothing — not the model allowlist, not limits, not the per-editor rate — because none of it is protecting anything of yours any more. Each editor’s key is spent against their own account, capped by their own provider, and theirs to rotate. Each editor also has to have one.
The models list is still what the model picker offers, but the browser talks to the gateway directly, so an editor can reach any model their key allows.
Under byok, choosing a model that meets your transparency obligations is the editor’s responsibility, or that of whoever issues their keys, for example by restricting models in the gateway.
byok needs a gateway a browser can call with the editor’s key, so cloudflare or custom. The netlify gateway resolves its base URL from the server environment, the vercel gateway is not known to answer a browser, and the build fails with a message if you ask for byok with either. The gateway’s origin is added to the admin’s connect-src, and nothing else is.
Enable it
Section titled “Enable it”Everything is declared statically in the integration config: the gateway, the model list, and (via your adapter) the host. There is nothing to set at deploy or run time. The first model is the default, and the relay rejects any request that names no model or one not in the list.
import netlify from "@astrojs/netlify";
export default defineConfig({ adapter: netlify(), integrations: [ cms({ storage: { type: "github", repo: "owner/repo", clientId: "..." }, ai: { enabled: true, gateway: { type: "netlify" }, models: ["anthropic/claude-opus-4.7", "openai/gpt-5.2"], }, }), ],});import vercel from "@astrojs/vercel";
export default defineConfig({ adapter: vercel(), integrations: [ cms({ storage: { type: "github", repo: "owner/repo", clientId: "..." }, ai: { enabled: true, gateway: { type: "vercel" }, models: ["anthropic/claude-opus-4.7"], }, }), ],});import cloudflare from "@astrojs/cloudflare";
export default defineConfig({ adapter: cloudflare(), integrations: [ cms({ storage: { type: "github", repo: "owner/repo", clientId: "..." }, ai: { enabled: true, // A Cloudflare API token with AI Gateway permission comes from the // CLOUDFLARE_API_TOKEN environment variable. gateway: { type: "cloudflare", accountId: "..." }, models: ["anthropic/claude-opus-4.7"], }, }), ],});cms({ storage: { type: "github", repo: "owner/repo", clientId: "..." }, ai: { enabled: true, // Any OpenAI-compatible gateway. The key comes from the // ASTRONAUT_CMS_AI_API_KEY environment variable. gateway: { type: "custom", baseUrl: "https://your-gateway.example.com/v1" }, models: ["anthropic/claude-opus-4.7"], },})| Property | Type | Default | Description |
|---|---|---|---|
enabled |
boolean |
false |
Enable the assistant and inject the relay route |
gateway |
AiGateway |
required | Which gateway to reach, and where its credential comes from |
credentials |
"relay" | "byok" |
"relay" |
Whose key is spent: the deployment’s, or each editor’s |
models |
string[] |
required | Gateway-qualified model ids; the first is the default |
maxSteps |
number |
24 |
Maximum model/tool round-trips per turn |
limits |
AiLimits |
see below | Request and output ceilings the relay applies |
Collection names
Section titled “Collection names”Each collection gets its own writeEntry_<collection> and editEntry_<collection> tool, so its name has to be one a tool can be named after: letters, digits, _ and -, with the whole tool name at most 64 characters.
A collection named otherwise ("blog posts", "news.de") is left out of the agent’s tools and reported when you build.
It stays fully editable by hand, and the agent can still read it through listEntries and getEntry — it just cannot write to it.
Renaming the collection is the fix.
Components
Section titled “Components”The agent knows the components of your cms.config.ts.
Its prompt lists each one with its label, description, kind and allowed children, and the getComponents tool returns their props as JSON Schema on demand, with the titles, descriptions and defaults of your .meta() calls.
Describing components and props well therefore helps the agent as much as it helps editors.
Reviewing what the agent did
Section titled “Reviewing what the agent did”The agent never asks for approval before a tool call, and it cannot publish or discard. Instead every change it makes joins the pending changeset, which you review and then accept or throw away as a whole.
Each write shows up in the conversation as a line saying what changed, with a link to the entry, so you can follow along while the agent works. The Changes screen lists the full changeset: every file added, edited, renamed or deleted since the last publish, each with its diff. Publishing and discarding act on all of it at once, from that screen or from the bar at the bottom of the admin.
Publishing is only possible after every change has been opened on the Changes screen. A change that is edited again after it was opened, by a human or an agent, has to be opened again. Publishing then asks for an explicit confirmation that the editor has reviewed the changes, checked their facts, and takes full editorial responsibility for them. The server refuses the publish if the changeset differs from the one the editor reviewed, for example because an agent wrote to it in the meantime. Review state lives in the browser tab, so a reload, a publish, or a discard starts the review over. Files without a diff, such as images, show no preview, so open them to review their content. On GitLab, such a file counts as unreviewed again after any later commit to the draft branch.
The gate is a step in the editorial process, not a security control. An editor with write access can still merge the pull or merge request directly on GitHub or GitLab.
This works the same way in local development, where there is no draft branch: the CMS reads the changeset from git and discards by restoring the files it manages. Only the collection directories, file-collection files and the media directory are ever touched, so discarding pending content changes never reverts your own source edits.
Safety
Section titled “Safety”Every change the agent makes is written to your per-user draft branch (cms/<username>) and surfaces as a pull or merge request, just like edits made by hand.
Nothing reaches your default branch until you publish, so a change is never final on its own and a single tool call cannot do damage that discarding the changeset would not undo.
Writes are validated before they land, in the storage layer itself, so the check applies to the assistant and to hand edits alike. The entry has to satisfy its collection’s schema, referenced entries have to exist, images and files have to be in the media library, and MDX components have to match their prop schemas. A blocked write returns the reason to the agent, which corrects it and retries. This matters most in development: Astro refuses to start when a content file does not match its schema, so an unchecked write could otherwise leave your dev server unable to boot. For the same reason a new entry is held in the editor until you first save it — it appears in its collection once it is valid, not before.
What the agent may reach
Section titled “What the agent may reach”The agent reads content: entry bodies, media listings, documents you attach. Any of that can try to instruct the model, so what matters is not whether a model can be fooled but what a fooled model could do.
The answer is bounded by the server rather than by the tool list:
- Content writes land in the changeset, so nothing a discard would not undo.
renameMediaanddeleteMediaare refused while any entry still references the file. That is a rule of the library, not caller discipline: only a human who has been shown those references in the media view can acknowledge them and proceed.- An object-store deletion moves the file to the library’s
.trash/prefix rather than dropping it, so even an acknowledged one is recoverable. - Publishing is not offered at all. The agent says what it changed and leaves that decision to you.
Cost controls
Section titled “Cost controls”These apply to the default relay mode. Under bring your own key there is nothing here to configure, because the editor’s own provider account is the ceiling.
The relay holds your gateway credential, so a session is otherwise a licence to bill your account without bound.
ai.limits caps what one editor can spend:
cms({ ai: { enabled: true, gateway: { type: "netlify" }, models: ["anthropic/claude-opus-4.7"], limits: { maxRequestBytes: 1024 * 1024, // request body cap (default: 1 MiB) maxOutputTokens: 8192, // clamped onto max_tokens, set whether asked for or not }, },});How often an editor may call is not configured, it follows from maxSteps.
A turn is up to maxSteps relay requests, so the per-minute ceiling is four turns’ worth and a raised maxSteps cannot make a single turn throttle itself halfway through.
Concurrency is capped at four in flight per editor, each slot held until its stream ends.
AI transparency
Section titled “AI transparency”The EU AI Act (Article 50) sets transparency duties for AI generated content. The CMS supports them as follows, but whether a deployment complies depends on the models you choose and on how you publish, so review it for your own site.
- Interaction notice. The chat is labelled as an AI assistant and says it is an AI system before the first message, in both credential modes.
- Machine readable marking.
The CMS does not mark or detect generated text itself, it relies on the model provider.
List only models in
modelswhose provider marks generated text and offers a detector. In relay mode, the relay enforces that list. Under bring your own key, it does not. - Editorial review. Text published to inform the public on matters of public interest needs either a disclosure or human review under someone’s editorial responsibility. The review gate implements the second route as a workflow: every change is shown to a human, who confirms responsibility before publishing. It applies equally to changes from the assistant, from browser agents, and from hand edits. Name the person or organisation holding editorial responsibility on your site, for example in the imprint. If you choose disclosure instead, add it in your site’s templates.
- Local storage. There is no publish step, writes land in the working tree directly. Review them in git before you commit.
Local development
Section titled “Local development”During astro dev the CMS uses local storage, which has no sign-in at all, so you can try the assistant without a provider login.
For netlify and vercel gateways, run the dev server through the platform CLI (netlify dev or vercel dev) so credentials are injected; cloudflare and custom gateways work directly from the config.
Testing against a local model
Section titled “Testing against a local model”The custom gateway points at any OpenAI-compatible server, so you can develop entirely offline against llama.cpp.
Start llama-server, which exposes /v1/chat/completions on port 8080, then enable the assistant with a matching custom gateway:
llama-server -hf ggml-org/Qwen3-4B-GGUF --jinja --port 8080ai: { enabled: true, gateway: { type: "custom", baseUrl: "http://localhost:8080/v1" }, models: ["local"],}No secret is needed: local storage has no sign-in and llama-server requires no API key.
The model id is arbitrary because llama-server serves whichever model it loaded, so any value in models works as long as the agent picks it.
Use --jinja so the server applies the model’s tool-calling chat template, which the agent relies on.
