> ## 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/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. Every later workspace-scoped generated command must include the confirmed workspace wire ID in the request object's `headers.akua-context` field: ```json theme={null} { "headers": { "akua-context": "WORKSPACE_ID" } } ``` Replace `WORKSPACE_ID` with the confirmed `ws_...` value. Keep this context in all relevant reads and writes. 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. Read the linked API reference for the exact request schema. Each generated command accepts one JSON object through `--input -` or `--input FILE`; its possible partitions are `path`, `query`, `headers`, and `body`. 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, include a stable `idempotency-key` in `headers` when the operation supports it. Reuse that key when retrying the same intended change. Poll a returned Operation with `akua operations get`, passing its ID under `path.id` and the confirmed workspace under `headers.akua-context`. Repeat until `done` is `true`. Continue a dependent change only when `state` is `SUCCEEDED`; stop and report `FAILED` or `CANCELLED`. Don't use `akua operations wait` with the browser-approved credential: the current generated request omits workspace context. Treat that missing long-poll path as a public API gap instead of retrying the mutation. ## 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. Akua fulfills free-tier `clusters create` requests from a pre-warmed pool, so the cluster is typically ready in seconds and needs no cloud credential. Create the free worker with `machines create` against the new cluster and omit `compute_config_id`; omitting it explicitly requests the system-managed free machine. Resource quotas are the only limit on these requests. 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, state the documented free allowance (one managed cluster and one small Akua-managed machine), the free machine's lifetime, and the price of anything beyond the allowance, then obtain the user's approval. Poll each dependent write with `operations get` before starting the next one, following the terminal-state rules above. After the installation, verify the application's public URL before reporting that it is running. If a required public operation or source is unavailable, report that gap instead of stitching together internal or undocumented behavior. ### 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.