onboard

name

onboard

description

Onboard onto the Akuity platform through its platform MCP endpoint: create Argo CD and Kargo instances, connect clusters, deploy an app to every environment through Argo CD applications, wire a Kargo pipeline to those apps, and promote an image release through the environments — all on the one endpoint. Use when asked to onboard onto Akuity, set up Akuity from scratch, or deploy a first app with a promotion pipeline — for the whole path or any part of it (a single instance, a cluster connection, or a pipeline onto instances that already exist).

You are onboarding someone onto the Akuity platform. The full path starts from an Akuity account, one or more Kubernetes clusters, a container image, and a git repository, and ends with Argo CD running, the clusters connected, the app deployed to every environment by an Argo CD application, and a Kargo pipeline that promotes the image through those environments by updating git and syncing the apps — without ever opening the Akuity UI for the build itself. Each environment maps to a cluster the user names (several environments may share one — e.g. dev and staging on cluster A, prod on cluster B) and gets its own namespace. Not everyone wants the whole path, and parts of it may already exist — so the first move is agreeing on scope, not creating anything.

The whole flow runs on one MCP endpoint — the platform endpoint, with the organization and instance named explicitly on every call. Its apply tools are composite: one call carries an instance together with what lives inside it — Argo CD Applications ride in the Argo CD apply, Kargo projects, warehouses, and stages in the Kargo apply — and the platform endpoint also serves the sync, freight, and promotion tools the later steps need. Each provisioned instance can additionally serve its own MCP endpoint, where the same in-instance work runs under the instance's own RBAC — but connecting one is never required: with the platform endpoint connected, everything in this flow and its day-2 follow-ons is already reachable (instances this flow creates allow platform MCP actions automatically; a pre-existing instance must have MCP access enabled before the in-instance tools reach it — and every Kargo instance, new or pre-existing, needs its authentication configured before Kargo's API answers at all: ../../references/endpoints-and-auth.md). It is a choice the user can make, mainly for teammates who hold instance access without organization access — see "The instances' own endpoints" below. Read ../../references/endpoints-and-auth.md and ../../references/manifest-kinds.md (paths relative to this file) before your first call — they carry the endpoint model and the manifest rules this skill depends on. Before writing an instance, cluster, Argo CD, or Kargo resource, also read the relevant section of references/official-docs.md. For a new instance, omit its version as manifest-kinds.md requires; after it becomes healthy, read the assigned version before writing its in-instance resources. Then read tools/list and the tool descriptions; this skill gives you the order and the platform-specific facts, not the full tool contracts.

Treat the flow below as a dependency order, not a script. Tool names and manifest shapes may have moved since this was written. The live tool description defines the MCP call envelope; the installed product version's official docs and CRD define the resource inside it. When they disagree with this skill, use those current sources and tell the user about the difference rather than forcing the text. If neither source defines a field, stop and ask or defer that setup — never try plausible field names or nesting until one happens to apply. The goal state is fixed even when the path is not: whatever scope the user chose, standing and verifiable from MCP reads at the end.

The one principle that shapes everything here

You never configure the user's credentials or logins for them, and nothing optional blocks the flow. Passwords, password hashes, OIDC client secrets, git and registry tokens — all of it is the user's own action, in the portal UI or their own shell, with you supplying the exact place or command and a placeholder. Your job is to keep building everything that does not depend on the missing piece, say plainly at the moment a piece is needed what it is for and what fails without it, verify by outcome once the user has acted, and close with a checklist of anything still unconfigured and its consequences. Never park the whole flow on a setup question, and never take a secret into the conversation to unpark it.

The milestones — offer them, let the user choose

These are the milestones, in dependency order — not an all-or-nothing script:

1. Argo CD instance — provisioned and healthy (flow steps 1–2).
2. Clusters connected — every cluster the environments map to registered with the instance, agent installed, healthy (step 3).
3. Kargo instance — provisioned likewise, with an Akuity-managed Kargo agent linked to the Argo CD instance (step 4).
4. Apps created — deployment YAMLs per environment in git, one Argo CD Application per environment (steps 7–8). If the chosen scope stops here, this milestone also runs each app's first sync so the app is actually deployed; with a pipeline in scope, the tags come from the approved Stage-to-version plan and deployment is milestone 6's job.
5. Pipeline wired — Kargo Project, a Warehouse watching their image, and — after the user has seen what the Warehouse discovered and chosen the desired version for each Stage — one chained Stage per environment (steps 5–9).
6. Release promoted — the required Freight carried through the environments per a plan the user approved, each hop verified; in pipeline scope this is where each approved environment's first deployment happens (step 10).
7. Incident response wired (optional) — Akuity Intelligence enabled on the Argo CD instance with a resource-degradation trigger scoped to the new clusters and namespaces, so a degraded app opens an incident by itself instead of waiting for someone to notice (step 11).

Open by naming these and asking how far they want to go: the full path, one milestone, or just the missing pieces. Then establish where they already stand with read tools before creating anything. An instance, cluster, or pipeline that already exists and is healthy is a prerequisite satisfied, not something to recreate. One dependency to name up front: Kargo Project, Stage, Freight, and Promotion tools require the instance to have an admin account or OIDC configured. Platform lifecycle reads and applies remain available, so instance creation and platform applies of Project, Warehouse, and Stage do not depend on this setup. Authentication is the user's own action and can happen at creation or later. It gates the Kargo reads and promotions in milestones 5–6, but it must not stall independent work. See steps 4–6 and references/instance-access.md. Someone with a running instance and a connected cluster who asks to "onboard" needs milestones 4–6, not a second instance.

Ask in two rounds

Provisioning waits are the rhythm of this flow, so batch the questions: one round at scope time, and — only when a pipeline is in scope — one round after the Warehouse reports its discovered artifacts, when the versions on the table are real data instead of guesses. Never ask for a token, password, or password hash in chat: anything pasted into the conversation persists in tool-call data. Instance logins are deliberately not asked about here at all — they are the user's own setup in the portal UI, raised at the moment they matter (step 4) and again in the closing checklist.

Round one — at scope time. Any scope:

• Their Akuity organization. Call list_organizations to resolve its id, and offer the matching organization for confirmation before using it; never use a found candidate unconfirmed.
• A name prefix for the things you create.
• Confirmation that the MCP client reports the platform endpoint as connected and authenticated. Nothing in any milestone works without it.

Milestone 2 (clusters):

• Which Kubernetes clusters to connect, by kubectl context name, and which environments run on which cluster (e.g. dev and staging on A, prod on B — one cluster for everything is fine too). Confirm each context answers before relying on it: kubectl --context <ctx> get nodes.
• Whether the shell you run commands in has the akuity CLI installed and authenticated against their portal (akuity login, or the AKUITY_API_KEY_ID/AKUITY_API_KEY_SECRET environment variables). The agent installs run through it; if the CLI is missing or unauthenticated, the user runs those commands themselves or uses the install command shown in the web UI.

Milestones 4–6 (apps, pipeline, promotion):

• The container image repository, whether the registry is public, and how its tags are ordered — semantic versions, build timestamps, or lexical names — so the Warehouse gets the right selection strategy. When a pipeline is in scope, do not assume or ask them to approve latest here: let the Warehouse's discovered artifacts be the source of truth in round two. Only a scope that stops at apps, with no Warehouse or pipeline, needs the user to name the tag here. A private registry will need an image credential before the Warehouse can see it — named again at the moment it matters.
• The git repository for the deployment YAMLs (URL, and whether it is private), whether it already has an environment/branch layout that must be preserved, and whether you may commit the scaffolding yourself or should hand them the files. In app-only scope the scaffolding can land during the first provisioning wait; in pipeline scope it waits for round two so the approved Stage-to-version plan supplies the tags. The push runs on the git credentials already on their machine, and it happens exactly once: promotion commits are later pushed by Kargo itself with the Project's own credential, never from their machine.
• Which environments they want, in promotion order (e.g. dev → staging → prod), each mapped to one of the clusters above, and which of them count as production — those get an extra explicit confirmation before any promotion reaches them.
• How the Argo CD Applications and the Kargo pipeline resources should be managed: direct apply (the default — this skill applies them through the platform endpoint) or GitOps bootstrap (they live in the repo and Argo CD syncs them — see "GitOps mode" below). In either mode, offer to write the generated manifests into the repo so it records what exists: in direct-apply mode that is documentation, in GitOps mode it is the mechanism.

Milestone 7 (incident triggers):

• How long an app must stay degraded before an incident fires (degradedFor — a duration like 5m or 1h30m; suggest 5m as a starting point), and whether the trigger should cover all the new namespaces or only some (e.g. prod only).

Round two — after the Warehouse reports discovered artifacts (step 6). Show the candidate versions from the Warehouse status and any Freight already produced, then ask for the desired end state as a complete Stage → version table. Every new Stage gets an explicit version; an existing deployed Stage may instead say "keep current." Separately ask which Stages should actually be promoted today; latest is valid only when the user says it, and must be resolved to the explicit tag and Freight currently discovered before confirmation. "Wire the pipeline but do not promote today" is valid. A skipped Stage cannot sit in the middle of an approved path to a downstream Stage — the normal chain must promote and verify Freight in every Stage it crosses — so surface that conflict instead of silently bypassing it. Compute the distinct versions required by the table, make sure the Warehouse has produced one Freight for each, then derive the ordered promotion hops needed to end at that table. A single Freight still moves through a contiguous Stage path, but one plan may use several Freight — for example, prod=v1 and staging=v2 means promote v1 through prod first, then v2 only through staging. Show every Freight, version, and hop and confirm the whole plan. references/pipeline-facts.md covers discovered artifacts, producing older Freight, and restoring the Warehouse's steady-state subscription afterward.

The flow

Every MCP call below runs on the platform endpoint. The user-owned moments are the agent installs (step 3), the instance login setup (raised at step 4), the git scaffolding (step 7), and the credentials (steps 6, 8, and 10 — each raised only when actually needed).

1. Create the Argo CD instance. The platform's Argo CD apply tool is composite: one call carries the instance manifest, plus every cluster registration as clusters entries (shapes in ../../references/manifest-kinds.md). Instances created through this endpoint get MCP access enabled automatically. spec.instanceSpec.mcpServer.enabled serves the instance's own /mcp endpoint and lets platform tools target the instance; carry it explicitly only when updating a pre-existing instance. Do not send admin-account or OIDC config with the initial request. The platform endpoint's Argo CD tools work without an instance login. A login is needed for people using the instance UI, CLI, or direct MCP endpoint, and the user can set it up later in the portal (references/instance-access.md and the closing checklist). Children in the same call as their instance are safe. Any other call that references the instance id must wait for health; see step 4. Creation returns when the request is accepted, not when the instance is usable.
2. Poll a read tool until the instance reports healthy. A fresh instance may first read unknown ("failed to get tenant status") and then progressing — normal. Healthy usually lands within a couple of minutes; use background waits and report progress rather than going silent. If the instance disappears from list reads instead of going healthy, its creation failed: re-apply it and re-read its id — the recreated instance gets a new id, so never reuse an id recorded before the instance reported healthy. In app-only scope, the git scaffolding (step 7) needs no platform, so do it during this wait; in pipeline scope, wait for round two's Stage-to-version plan.
3. Install the cluster agent with the akuity CLI — once per cluster. The platform apply tool's description names the exact command (akuity argocd cluster install-agent --org-id=… --instance-id=… <cluster name>). Run it once for each registered cluster, each with --context set to that cluster's context. Pick the branch that fits: (a) if your shell has the akuity CLI authenticated and kubeconfig contexts for their clusters, run them yourself; (b) otherwise hand them the commands to run in their own shell; (c) if they are not using the CLI at all, tell them to copy the install command from each cluster's page in the web UI and run that. Always pass --organization-id explicitly — the CLI silently falls back to the default organization in its own config file, which may not be theirs. Never pipe or filter install-agent's output — piping wedges it silently, doing nothing for minutes; run it in the background with output redirected to a log file and read the log. And never fetch or print the raw install manifests — they contain live credentials; streams them straight into kubectl without ever putting them on stdout. Then poll until every cluster reports healthy — before its agent is installed a cluster reads unknown with "Did you install the agent manifests?".

If a step misbehaves — a Warehouse that never produces Freight, a Promotion that fails at clone or push — check references/troubleshooting.md before retrying anything; most of these failures are silent misconfigurations with exact fixes, not transient errors.

GitOps mode (optional)

The default flow direct-applies the Applications and the Kargo pipeline, which leaves the repo holding only the deployment YAMLs. If the user chose GitOps at scope time, the control resources live in the repo instead and Argo CD syncs them — the layout Akuity's own demo uses (github.com/akuity/akp-demo, akp-demo/bootstrap). The flow above still holds; these are the deltas:

• Bootstrap the control resources before choosing versions. At step 5, bootstrap/kargo/ holds only the Project and Warehouse, while bootstrap/argocd/ holds one bootstrap Application whose destination is the Kargo control plane, source path is bootstrap/kargo/, and sync policy is automated with prune. After round two, the step-7 commit adds the environment directories pinned to their approved Stage versions, step 8 adds the per-environment Application manifests (authorized-stage annotations included, no automated sync), and step 9 adds the complete Stage chain. Credential Secrets never enter git; they stay a user-shell action exactly as in references/pipeline-facts.md.
• Register the Kargo control plane as an Argo CD destination. A clusters entry on the Argo CD apply can name the Kargo instance as a direct cluster. Resolve its exact shape from the live apply schema and the Akuity docs routed by references/official-docs.md; the id exists only after step 4, so this registration lands as an instance update once the Kargo instance is healthy. If those sources do not define the direct-cluster shape, do not invent wrappers around directClusterSpec: tell the user the GitOps bootstrap destination cannot be registered from the available contract and ask whether they want to register it in the portal or use direct-apply mode.
• Steps 5 and 9's Kargo applies become commits and syncs: apply only the contents of bootstrap/argocd/ through the platform apply — the bootstrap Application first, then the per-environment Applications after the Stage-to-version plan — and the Project, Warehouse, and later the complete Stage chain arrive by sync from git. (For everything-in-git, wrap bootstrap/argocd/ itself in one more app-of-apps Application and direct-apply only that.) Credentials, artifact discovery, round two, and promotion verification are unchanged.
• After bootstrap, git is the write path. Changing or removing a GitOps'd Application or Kargo resource means a commit, not an MCP apply or delete — an MCP write would fight the bootstrap app's sync and be pruned or reverted. The MCP tools stay the read, verify, and promote surface.

The instances' own endpoints

Each provisioned instance can serve its own MCP endpoint at https://<hostname>/mcp (hostname from the platform read tools), where calls authenticate as an instance user under the instance's own RBAC and tools take no instance id. Never require or steer toward connecting one. The platform endpoint already covers this whole flow and the day-2 work after it — the instance endpoints work the same in-instance resources, just under instance-scoped auth. Bring one up only when the user asks, or when it solves an access problem worth naming when you finish: a teammate with Argo CD or Kargo roles and no organization membership cannot use the platform endpoint at all, and creates, syncs, and deletes apps, or promotes freight, there instead. Instances this flow creates already allow MCP access — the same mcpServer.enabled that lets platform tools target them serves their own /mcp — and gain a browser login as soon as the user finishes the instance-login setup (SSO, or the admin account they enable in the portal), so bringing an endpoint up is just registering it and logging in. references/instance-access.md covers the two access modes end to end.

Boundaries

• Use MCP endpoints for Akuity Platform and instance operations. The platform endpoint carries this whole flow; direct instance endpoints serve instance-scoped users. Do not operate the portal on the user's behalf or run kubectl against provider-managed components. Git operations against their repository, kubectl against their clusters, and akuity CLI commands in their shell are user-owned actions. Use only the repository and contexts they named, with their consent. Send users to the portal for their own login, password, and credential setup.
• The akuity CLI is never a substitute for an MCP tool. With MCP connected it exists in this flow for exactly two jobs an MCP call must not do: the agent installs (live credentials, step 3) and the secret-bearing credential applies (steps 6, 8, and 10). Everything else — instances, clusters, apps, pipeline, reads — goes through the MCP tools, even when the CLI is authenticated and could do it.
• Installing an agent into their cluster is their action, not yours, unless they named the context and your shell has the akuity CLI ready — then running install-agent yourself is fine; say so. Never run manifest-fetching tools bare, never curl the manifests endpoint, and never write install manifests to disk: they contain live credentials, and install-agent exists precisely so they never touch stdout.
• Secrets never transit the conversation, including password hashes. Do not ask for tokens, passwords, or hashes, and do not place a secret value in any tool argument. Credentials and logins are created by the user in their own shell or the portal or instance UI, with you supplying the exact place or command and a placeholder. If the user pastes a secret anyway, do not use it in tool calls. A secret that entered the conversation is exposed; for a password, have them pick a new one and set it themselves. If the client refuses a secret-bearing call, do not work around it. Route the action to the user.
• Promotion is consequential and needs the user's decision, not just their earlier scope choice. Execute only the multi-Freight plan the user approved after seeing the discovered versions (round two), and re-confirm explicitly before any environment they named as production. Never promote "the rest of the way" on your own initiative.
• Never guess an identifier, value, field, or nesting you were not given. The live tool schema defines the call envelope; the actual product version's official docs define the resource. After a manifest-shape or validation failure, consult those sources and make one evidence-backed correction — do not try field-name variants. If you still cannot resolve it, stop and say what is missing.
• If a call fails and the error does not tell you enough to fix it, say that plainly and stop. Do not retry the same call hoping for a different answer; two attempts with no new information is a stop condition. A permission denial is an authorization answer — the organization's RBAC on the platform endpoint, the instance's own RBAC on an instance endpoint — report it as such rather than retrying.

When you finish

Give them a short summary of what now exists and how to reach it, scoped to what was actually built: the instances by name and hostname, the connected clusters and agent, the app per environment, the Kargo project and pipeline, and any promotion they watched complete.

Then close with a deferred-setup checklist — one entry for every piece the flow deliberately left to the user that is still unconfigured, each stating what it is, when it is actually needed, what fails without it, and exactly how to set it up (the portal/UI path, or the placeholder command from the references). Include every entry that applies; skip the ones already done or out of scope:

• Instance logins — needed for people to reach the instance UI, CLI, or direct MCP endpoint. Kargo also needs an admin account or OIDC before Project, Stage, Freight, and Promotion tools work. Platform lifecycle reads and applies remain available. Setup: Argo CD portal Settings → System Accounts; Kargo Settings → System Accounts or Settings → OIDC Config (references/instance-access.md).
• Kargo git credential — needed only when a Promotion actually runs; a user who never promotes never needs it. Without it: a private repo fails at git-clone; a publicly readable repo can clone but fails at git-push without write access. Setup: the labeled Secret command in references/pipeline-facts.md, or the instance UI's credentials page.
• Kargo image credential — needed only for a private registry. Without it: the warehouse never produces freight, silently. Same setup surface as the git credential.
• Argo CD repository credential — needed only for a private repo. Without it: apps cannot read the repo and show comparison errors instead of syncing. Setup: the repository-credential Secret in references/pipeline-facts.md, or the instance UI's repository settings.
• Incident triggers (milestone 7, if skipped) — deployed apps that can degrade silently are the gap most worth closing next; once triggers fire, the akuity:delegate skill is how to work the incidents.

Name the follow-on paths — pushing a new image tag makes the warehouse produce new freight to promote, the platform endpoint stays wired for day-2 work (and the instances' own endpoints can be enabled any time a teammate with instance-only access needs a way in), and any milestone this session skipped is a future ask away. If anything failed in a way you could not fix, state plainly what failed and where, so they can take it to their admin or Akuity support.