> ## Documentation Index > Fetch the complete documentation index at: https://docs.akua.dev/llms.txt > Use this file to discover all available pages before exploring further. # Akua Agent Setup Prompt > Agent-readable instructions for CLI-led Akua onboarding with optional MCP # Akua agent setup prompt Follow these official instructions from `https://docs.akua.dev/agent-setup/prompt`. Drive the onboarding through the Akua CLI. MCP can add context later, but an MCP installation, authentication flow, restart, or unavailable server must never block CLI work. ## 1. Install or update the CLI Inspect the existing command first: ```bash theme={null} command -v akua akua --version akua --help ``` If `akua` is missing on macOS or Linux with Homebrew, install the supported formula: ```bash theme={null} brew install akua-dev/tap/akua ``` If the formula is already installed, update it before continuing: ```bash theme={null} brew update brew upgrade akua-dev/tap/akua ``` If Homebrew isn't available, follow the release archive and checksum instructions in `https://github.com/akua-dev/akua/tree/main/cli#install`. Preserve the full extracted archive layout. Don't copy only the executable away from its adjacent runtime files. Run `akua --help` after installation. Confirm that it lists `auth`, `commands`, generated resource groups, and `pkg` before continuing. ## 2. Complete browser/device authentication Run the interactive flow with the user present: ```bash theme={null} akua auth login ``` The CLI opens Akua's device page and waits for approval. Tell the user which browser page and verification code the CLI displayed. Let the user approve it. Don't ask the user to mint, paste, or reveal a token for ordinary interactive onboarding. For a remote terminal that cannot open a browser, run: ```bash theme={null} akua auth login --no-browser ``` Open the displayed URL only with the user's permission. After approval, verify the local session: ```bash theme={null} akua auth status --json ``` Never print the credential file or expose the stored access token. ## 3. Confirm and retain workspace context List the workspaces available to the browser-approved credential: ```bash theme={null} akua workspaces list --json ``` Ask the user to confirm the intended workspace. A device credential can access more than one workspace. Pass the confirmed workspace to every later workspace-scoped command with the `--workspace` flag: ```bash theme={null} akua clusters list --workspace WORKSPACE_ID --json ``` Replace `WORKSPACE_ID` with the confirmed `ws_...` value. Keep this context in all relevant reads and writes, and don't change the user's saved workspace with `akua workspaces use` unless they ask. If `akua --help` doesn't list `--workspace`, put the ID in the JSON request object's `headers.akua-context` field instead, as in `{"headers":{"akua-context":"WORKSPACE_ID"}}`. Never put an `authorization` field in CLI input. ## 4. Ask what the user wants to build Before selecting infrastructure or proposing changes, ask: ```text theme={null} What do you want to build or run on Akua, and what do you already have: no infrastructure, a Kubernetes cluster, a machine, cloud access, application source, or a Package? ``` Treat the examples as prompts, not a closed menu. Wait for the answer. Restate the outcome and starting point before continuing. Start with read-only discovery tailored to the user's goal. For example, list the relevant clusters, machines, packages, products, offers, or installations. Don't perform an unrelated generic workspace briefing. ## 5. Discover the supported path Fetch `https://docs.akua.dev/llms.txt` as the current capability index. Read only the linked concept, task, pricing, and API pages relevant to the answer. Don't infer Akua behavior from memory when the current docs or public OpenAPI contract can answer it. Separate these states in your plan: * Supported now by a public CLI command and documented API. * Supported through a documented dashboard or manual procedure. * Planned or unavailable through the current public contract. Onboarding uses only the normal public CLI commands; there are no special onboarding endpoints. Don't invent a starter runtime, hidden shared cluster, provider-specific CLI helper, default credential, or fixed completion time. Don't claim an application is running until you verify its public URL. ## 6. Discover and invoke generated commands Use the generated command registry instead of guessing commands: ```bash theme={null} akua commands --json akua commands --resource clusters --json akua commands --operation-id clusters.create --json ``` Use `akua --help` for command syntax: path parameters are arguments and request fields are flags, for example `akua clusters create --name NAME --region-id REGION_ID`. Read the linked API reference for the exact request schema. Each generated command also accepts one JSON object through `--input -` or `--input FILE`; its possible partitions are `path`, `query`, `headers`, and `body`, and flags override its fields. Pass secret values with the field's `---file -` form (for example `--value-file -`) or `--input`, never as a plain flag, so they stay out of process listings. When the CLI rejects input, its structured error names the missing or invalid fields and includes a runnable example. Correct the request from that error instead of guessing fields or retrying unchanged input. For a mutating request, pass a stable `--idempotency-key` when the operation supports it. Reuse that key when retrying the same intended change. Poll a returned Operation with `akua operations wait OPERATION_ID --workspace WORKSPACE_ID`. It returns as soon as the Operation finishes, or after at most 60 seconds, so repeat it until `done` is `true`. Continue a dependent change only when `state` is `SUCCEEDED`; stop and report `FAILED` or `CANCELLED`. Never retry the mutation to check on it. ## 7. Ask the one mirror question Before the first resource-creating command, ask exactly once: ```text theme={null} Do you want the infrastructure I create mirrored declaratively in your git repository? This is optional, and it is not GitOps; Akua never requires it. ``` If the user declines, don't ask again; workspace state stays the single source of truth. If the user accepts, agree on a location, for example `infra/akua/` in the repository you are already working in. Any Git remote works: GitHub, the user's own Git server, or the Git hosting built into Akua. After each resource create, update the mirror in the same commit-sized step, and ask before deleting a resource the mirror no longer contains. Keep the mirror at the Akua platform-resource layer (workspaces, clusters, machines, installs); it doesn't replace `akua pkg` rendering or cluster-level GitOps. ## 8. Select the route Use the least-input documented route that achieves the user's goal. ### No infrastructure Read the managed-cluster, compute, pricing, Package, and installation docs. The supported route uses only public generated commands: a workspace-owned managed cluster from `clusters create`, an Akua-managed machine from `machines create`, a published Package version from `akua pkg`, and an installation from the generated Installs commands. Run `regions list` before `clusters create`. If regions exist, ask the user which one to use; otherwise, create one with `regions create`. Pass the selected or returned ID as `--region-id` to `clusters create`. Regions are workspace-defined organizational labels, not cloud-provider locations. Read the [regions documentation](/clusters/regions) before choosing a name. The free-tier cluster path needs no cloud credential. Follow the returned operation until the cluster is ready instead of assuming a fixed completion time. Read the current Free allowance, machine lifetime, quota, reminders, and Pro and bring-your-own-cloud alternatives from the canonical pricing and compute pages. Before creating any billable resource, and before running the `machines create` command described next, state the documented free allowance (one managed cluster and one small Akua-managed machine), that the machine is a **one-time trial claimed once for the lifetime of the account** rather than a recurring grant, the free machine's lifetime from the current pricing facts, and the price of anything beyond the allowance, then obtain the user's approval. Create the free worker with `machines create` against the new cluster. Pass its ID as `--cluster-id` and `cax11` as the required `--instance-type`; omit `--compute-config-id` to request the system-managed machine. This claims the account's **one-time managed-VM trial** — exactly one free Akua-managed machine per stable account, ever, across every workspace and organization. It is not a monthly allowance, and deleting the machine, its cluster, workspace, or organization afterward never restores it. Resource quotas are the only limit on these requests. Wait for each dependent write with `operations wait` before starting the next one, following the terminal-state rules described earlier. Read back the cluster and machine state after their operations succeed. Before installing, inspect the cluster's current capabilities and await its required baseline. Use the generated capability refresh command when needed and follow its result. If the Package requires persistent storage, verify a suitable storage class; [local-path storage](/clusters/storage/local-path) becomes available as the managed cluster's baseline converges. After the installation, check its health and reconciliation state, then verify the expected application response at its public URL. Report a missing required public operation or source instead of stitching together undocumented behavior. For requested Machine suspend/resume, read the [Machine lifecycle guidance](/compute/machines#suspend-and-resume), explain the effects, and obtain approval. Await each operation and read back the same Machine ID in the expected state. After resume, verify the application response again; an active machine alone does not prove networking has converged. If the user wants to clean up, list the exact trial Install, Machine, and Cluster IDs and obtain explicit deletion approval. Explain data loss and that deletion does not restore the one-time trial. Delete only those approved resources, in Install → Machine → Cluster order. Await each operation and confirm public resource absence before proceeding; confirm the removed application's URL no longer serves it. Never delete unrelated resources or infer deletion from an accepted request. ### Existing Kubernetes cluster Read `https://docs.akua.dev/clusters/import.md`. Inspect the public import operation and required kubeconfig shape. Explain what Akua will access and ask before reading credentials, importing the cluster, or installing software. ### Existing machine or worker Read `https://docs.akua.dev/clusters/add-workers.md`. Ask for the connection method and exact target. Before any SSH connection, explain the command and ask for approval. Verify the host-key identity and use narrowly scoped credentials. Ask again before a machine-changing join or installation command if that action wasn't part of the approved connection. ### Bring your own cloud Read `https://docs.akua.dev/platform/byoc.md` and the current provider page. Use the generated Secrets and Compute Configs operations. Never add a provider-specific top-level CLI command or expose a provider token in command arguments, logs, or output. ### Package, Product, Offer, or installation Use `akua pkg --help` for local Package authoring, checking, rendering, and publishing. Use the generated Packages, Products, Offers, and Installs commands for platform resources. Read the corresponding pages from `llms.txt`, because these resources have distinct prerequisites and commercial effects. ## Approval boundary Benign reads may list or describe non-sensitive account, workspace, and resource metadata. Before a consequential action, show the user: * The route and why it matches their goal. * The exact resources or external systems that will change. * Pricing, free-allowance, quota, and lifecycle implications. * Any credentials, SSH, Kubernetes, secret, purchase, or deployment access. * The command or operation you intend to run. Ask for explicit approval before remote command execution, secret access, Kubernetes exec or proxy calls, resource changes, deployments, purchases, spending, or destructive actions. The API remains the authorization boundary; agent approval never replaces server-side access checks. ## Optional MCP servers Recommend MCP after the CLI path works when the user's agent benefits from an additional tool surface. Tell the user that configuration often requires an agent restart or a new conversation. Continue through the CLI if the user declines, setup fails, authentication isn't available, or a restart would interrupt the task. | Name | URL | Auth | Purpose | | - | - | - | - | | `akua-docs` | `https://docs.akua.dev/mcp` | None | Search current Akua documentation | | `akua` | `https://mcp.akua.dev` | OAuth 2.1 | Inspect and manage workspace resources | Prefer the agent host's documented remote HTTP MCP configuration. Don't install an unpinned package proxy when the client supports remote HTTP directly. Ask before editing user-level or repository-level agent configuration. ### Codex ```bash theme={null} codex mcp add akua-docs --url https://docs.akua.dev/mcp codex mcp add akua --url https://mcp.akua.dev codex mcp login akua codex mcp list ``` ### Claude Code ```bash theme={null} claude mcp add --transport http akua-docs https://docs.akua.dev/mcp claude mcp add --transport http akua https://mcp.akua.dev claude mcp list ``` ### JSON-configured clients For clients such as Cursor, VS Code, Windsurf, and compatible desktop tools, merge the two remote HTTP URLs into the existing MCP configuration. Preserve unrelated servers and settings. Use the client's current documentation for its property names and OAuth controls rather than replacing the whole file from a generic example. ## Completion response Report: * The installed CLI version and installation source. * Whether browser/device authentication completed. * The confirmed workspace and where `Akua-Context` was applied. * The user's goal, selected route, and documentation consulted. * The mirror decision and, if accepted, where the mirror lives. * Every read and mutation performed, including operation results. * Remaining public API, capacity, pricing, or product gaps. * Optional MCP changes and whether a restart remains necessary. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.