Magneto Agent / AI Assistant
Prerequisites: Containerization guide, Container configuration
The AI Assistant is an optional agent sidecar that ships alongside your application. From the developer's point of view it is a single on/off toggle and a small skills configuration form, plus your AI Assistant fee on the pricing step. The platform, not you, generates the full agent service (env vars, volumes, healthcheck, sibling-discovery glue) at deploy time.
On a paid plan, Clouve provides the AI model access. Customers never enter an API key or pick an AI tool: the assistant opens ready to work, with a monthly AI usage allowance that Clouve sets. A free trial, or an organization with free services, gets the AI Assistant at no charge but with no AI usage included. Those customers sign in to it with their own Claude subscription.
This doc describes the developer-facing surface: the UI tab, the manifest extension, and what to expect at runtime.
Why it exists
In the original publishing flow, every marketplace manifest that wanted an in-workspace AI Assistant had to include a hand-written magneto-agent service block: fifty-plus lines of env vars, volumes, healthchecks, and x-clouve-* metadata, copied across every app with only a small per-app subset edited in place.
The optional Magneto Agent feature turns the agent into a first-class toggle on the developer publishing form. You provide the minimum input, primarily a Skills source URL, and the platform synthesizes the full agent service at deploy time. The platform injects the cross-cutting glue (CLOUVE_OPS_PASSWORD, the agent volumes, CLV_SIDECAR_HOSTS) itself. App-specific env vars that used to be copied onto the agent (GIBBON_HOST, MOODLE_DB_PASSWORD, and so on) are now discovered from sibling containers when the agent boots.
Hosts, database names and users reach the agent as environment variables. Passwords and keys, MOODLE_DB_PASSWORD among them, do not, so a skill that reads one from the environment gets nothing. A variable counts as a password or key when its name has an underscore-separated word such as PASSWORD, KEY, TOKEN or SECRET, so name your app's password and key variables that way. Put ${NAME:-$(clv-secret NAME)} inside the command that needs it, which also works on older agents. clv-secret --list shows the names. Never print a value. Build an AI Assistant skill has an example.
Your saved manifest ends up shorter, the per-app boilerplate is gone, and the platform is the single source of truth for the agent's shape.
Where to configure it
Open the submission wizard and go to Step 2 (Container Configuration). Alongside your container tabs sits a permanent tab labeled AI Assistant, which cannot be removed.
- Tab badge (off): your application ships without the AI Assistant. Nothing about the agent is added to your manifest or your bill.
- Tab badge (enabled): your application offers the AI Assistant. Customers can add it for its own monthly price (see Pricing).
Switching the toggle on reveals a small form with the AI Assistant connect timeout, the skills source URL and optional Git credentials. Above the form, a line says how much AI usage the AI Assistant includes each month. Clouve sets that allowance, so there's nothing to enter for it. You set your AI Assistant fee on Step 3 (Infrastructure & Pricing); see Pricing.
Schema
The form persists into your saved manifest as a top-level extension (a sibling of services:, not nested in a service):
x-clouve-agent:
enabled: true
skills:
url: https://github.com/Clouve/magneto-skills.git?plugins=gibbon
git:
token: "{{secret:MAGNETO_AGENT_SKILLS_GIT_TOKEN}}"
username: ""
advanced:
isPublic: true
sidecarHosts: null
sidecarHostsExclude: []
sidecarPullTimeout: 300
Field reference
| Field | Required when enabled | Purpose |
|---|---|---|
enabled | No (Boolean) | Drives the toggle. Optional so partial updates do not have to re-assert it. |
developerFee | No | Your monthly AI Assistant fee in USD: 0 to 500, at most two decimals, 0 if left out. Set it on Step 3. Customers pay Clouve's fee plus this; you receive it. |
skills.url | Yes | Skills repo URL. Stored verbatim, with no fetch at submit time; validation is static only. |
skills.git.token | No | Optional. Rendered as a secret-typed env var MAGNETO_AGENT_SKILLS_GIT_TOKEN. Write-only: once saved, it is never shown or downloaded again. |
skills.git.username | No | Optional. Rendered as a static env var. An empty string is omitted and the image provides defaults. |
advanced.isPublic | No | Defaults to true. Toggle for internal-only agents (no Ingress). |
advanced.sidecarHosts | No | null (the default) auto-derives the list from non-agent services. An array is an explicit allow-list. |
advanced.sidecarHostsExclude | No | Container names to subtract from the auto-derived list. Ignored when sidecarHosts is set. |
advanced.sidecarPullTimeout | No | Seconds (max 1800). Renders as CLV_SIDECAR_PULL_TIMEOUT. Override the image's 300-second default when a sibling's first install takes longer to background its sshd. |
Round-trip
dockerComposeDownload.js preserves the x-clouve-agent block byte-for-byte (modulo YAML normalization), and dockerComposeUpload.js reads it back into the form. You never need to hand-edit the block; the UI is the source of truth.
Saved credentials are the exception. A download writes the Git token and every advanced.passthroughEnv value blank, keeping their names, because Clouve never sends a saved credential back. When you upload that file again and save, a blank value keeps the one you saved; a value you write into the file replaces it. Secret defaults work the same way.
An upload never changes your AI Assistant fee. A quota field in an older manifest is ignored: Clouve sets the usage allowance now.
What the platform synthesizes
At deploy time the manifest generator inflates x-clouve-agent into a real magneto-agent Deployment / Service / Ingress in the namespace. None of this appears in your saved YAML; the synthesis happens server-side. The agent gets:
- A pod with the label Clouve uses to find it (
aiAssistant.isAgentPodin Clouve's backend) - A dedicated
hostPrefix, which decouples the agent's Ingress hostname from sibling container DNS (see the strato DNS prefix discussion in Bundles) - The
CLOUVE_OPS_PASSWORDenv var and SSH wiring so the agent can reach every sibling'sclouve-opsuser - Four standard agent volumes
- A healthcheck configured for the agent's HTTP probe
- Resource defaults of
memoryBase: 4(4 GB) andcpuBase: 1. The platform sets these, not the developer, and they do not aggregate into the container resources shown in the Infrastructure & Pricing step
Pricing
Your listing's price is your developer fee plus Clouve's hosting for each tier. The AI Assistant has its own monthly price on top, which customers pay only if they add it. That price is Clouve's AI Assistant fee for the tier plus your AI Assistant fee, which you set on Step 3 (Infrastructure & Pricing): from $0 to $500 a month, the same on every tier, and $0 unless you change it. It does not roll up from the synthesized agent's memory/CPU base: the pricing calculator (calculatePricingTiers in thermo) prices it separately from your container aggregate.
You earn your AI Assistant fee every month from each customer who pays for the AI Assistant, and it's paid out to you monthly with your Developer Monthly Fee. When a customer turns the AI Assistant on partway through a billing period, they pay for the rest of that period, and you earn the same share of your fee. You earn nothing from organizations that get the AI Assistant free from Clouve.
Clouve's fee covers the AI Assistant itself and its usage allowance. Every paid deployment with the AI Assistant gets a monthly AI usage allowance that Clouve sets. When customers run out, they can buy more usage, which Clouve sells at cost. Usage they buy earns you nothing.
On a free trial, or in an organization with free services, there is no AI Assistant price and no usage allowance, so you earn nothing from it. Those customers sign in to the AI Assistant with their own Claude subscription.
What makes customers pay for the AI Assistant is how well it knows your app. A skill teaches it that: see Build an AI Assistant skill.
The marketplace card, plan pickers and checkout show the base price with one "AI Assistant +$X/mo" line. The developer dashboard (on the Application card), Step 3 (Infrastructure & Pricing) of the wizard and the reviewer's overview also show how that price splits, for example "AI Assistant $120.00 = $100.00 Clouve + $20.00 you", and the usage allowance.
Customers decide for each deployment:
- Checkout has an Add the AI Assistant box, checked by default. On a free trial, and in an organization with free services, the install form has the box instead, marked Free during the trial or Free for your organization. When a trial deployment subscribes, checkout offers the box, checked only if the trial has the AI Assistant on.
- The deployment's AI Assistant tab turns it on or off later. On a paid plan, turning it off takes effect at the end of the paid period. On a free trial or with free services, turning it on or off is free and takes effect at once.
- On a paid plan, when the monthly usage runs out, customers can buy more from the same tab, or wait for the monthly reset. Free trials and free services have no allowance, so their tab has no usage meter and no Buy more.
When to enable it
Enable the AI Assistant when:
- Users will configure or extend your application conversationally (LMS course authoring, CRM tweaks, content authoring)
- You ship skills (plugins) that automate workflows specific to your app. Build an AI Assistant skill shows how to write one
- You want a deployer-facing chat surface without owning the underlying agent infrastructure
Leave it off when:
- Your application is purely operational (databases, internal APIs)
- You expect to ship to organizations that want minimum cost and minimum surface area
- You have not authored a skills repository yet (you can always enable it later)
Related documentation
- Build an AI Assistant skill
- x-clouve-agent reference in the Containerization Guide
- Strato DNS prefix override in Bundles
thermo/docs/OPTIONAL_MAGNETO_AGENT.md(backend implementation notes)