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 plus a small skills configuration form. The platform, not you, generates the full agent service (env vars, volumes, healthcheck, sibling-discovery glue) at deploy time.

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.

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 ships with the AI Assistant, and the flat AI Assistant fee is added to your pricing.

Switching the toggle on reveals a small form with the skills source URL, optional Git credentials, and a collapsed "Advanced" section.

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:
    client: claude-code
    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.
`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`.
`skills.git.username`	No	Optional. Rendered as a `static` env var. An empty string is omitted and the image provides defaults.
`advanced.client`	No	`"claude-code"` is the rendered default. `null` omits `MAGNETO_AGENT_CLIENT` so the client is picked at runtime.
`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 60s 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.

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 labeled for discovery by aiAssistant.isAgentPod (see thermo/src/utils/manifests/aiAssistant.js)
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_PASSWORD env var and SSH wiring so the agent can reach every sibling's clouve-ops user
Four standard agent volumes
A healthcheck configured for the agent's HTTP probe
Resource defaults of memoryBase: 4 (4 GB) and cpuBase: 1. The platform sets these, not the developer, and they do not aggregate into the container resources shown in the Infrastructure & Pricing step

Pricing

The AI Assistant fee is a flat add-on, charged once when x-clouve-agent.enabled === true. It does not roll up from the synthesized agent's memory/CPU base: the pricing calculator (calculatePricingTiers in thermo) treats it as a single line item, separate from your container aggregate.

The fee appears as its own line in the developer dashboard (on the Application card) and in Step 3 (Infrastructure & Pricing) of the wizard. Make sure your customers expect this if they enable the assistant.

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
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)