> ## 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. # Quickstart > Start from one prompt and let your coding agent install, authenticate, and operate the Akua CLI with you This quickstart is for people who want a coding agent to drive Akua setup from the first prompt. You don't need to install the CLI, configure MCP, or choose infrastructure before you start. The agent installs the CLI, signs you in, asks what you want to build, then guides the supported path with you. ## Start with one prompt Give your coding agent this instruction: ```text theme={null} Fetch https://docs.akua.dev/agent-setup/prompt and complete the Akua CLI quickstart with me. Install the CLI, sign me in through the browser, then ask what I want to build and what infrastructure I already have. Use the CLI for authentication and platform operations. Treat MCP as optional and do not wait for an agent restart. ``` The fetched prompt tells the agent how to install the CLI, complete browser sign-in with you, select a workspace, discover generated commands, and request approval before consequential actions. ## What happens next The agent checks for `akua`, installs or updates the supported CLI, and runs `akua --help` to confirm the command surface. The supported Homebrew path is: ```bash theme={null} brew install akua-dev/tap/akua ``` If Homebrew isn't available, the agent follows the checksummed release archive instructions in the [CLI repository](https://github.com/akua-dev/akua/tree/main/cli). The agent runs: ```bash theme={null} akua auth login ``` The CLI opens Akua's device page and waits. You approve the displayed code in your browser. The agent never needs to read, request, or print the resulting access token. It then lists your workspaces with `akua workspaces list`, asks which workspace to use, and passes the confirmed workspace to later commands with `--workspace`. The agent asks what you want to build and what you already have. You can start with only an application idea, or with an existing Kubernetes cluster, a machine, cloud access, or a software package. It reads [the documentation index](https://docs.akua.dev/llms.txt) and the pages relevant to your goal. The agent asks once whether you want the infrastructure it creates mirrored declaratively in your git repository. Answer no and nothing changes. See [the mirror section](#optional-mirror-your-infrastructure-as-code) for what yes means. Before creating anything billable, the agent explains the documented [free allowance](/pricing) (one managed cluster and **one Akua-managed machine, claimed once, for the lifetime of your account**), the free machine's [trial lifetime](/pricing#free-tier), and the price of anything beyond the allowance, then asks for your approval. This is a one-time lifetime trial, not a monthly allowance: it is granted once per account across every workspace and organization, and deleting the machine, its cluster, workspace, or organization later never restores it. The agent asks for this approval before running the `akua machines create` command in the next step. The agent runs `akua regions list` before creating the cluster. If regions exist, you choose one; otherwise, the agent creates one with `akua regions create`. It passes the selected or returned ID as `--region-id` to `akua clusters create`. Akua [regions](/clusters/regions) are workspace-defined organizational labels, not cloud-provider locations. A free-tier cluster needs no cloud credential. Creation is asynchronous. Before adding a machine, the agent follows the returned operation to `SUCCEEDED` and reads back the cluster as active. A failed or cancelled operation stops the sequence. The agent creates a worker with `akua machines create`, passing the new Cluster ID as `--cluster-id` and `cax11` as the required `--instance-type`. It omits `--compute-config-id` to request the system-managed machine. This consumes the account's one-time managed-VM trial approved in the previous step; it is not reissued later if the machine, cluster, workspace, or organization is deleted. Before installing an application, the agent waits for the machine's operation to succeed and reads back its active state. It checks the cluster's current capabilities and waits for the required baseline to be ready. If the application needs persistent storage, it also verifies a suitable [storage class](/clusters/storage) is available. The agent packages the application with `akua pkg`, publishes a version, and installs it on the cluster through the generated install commands. It follows the publish operation to success before creating the Install. The agent follows the Install operation to `SUCCEEDED`, then confirms the Install is healthy and no longer reconciling. It opens the application's public URL and checks the expected response before reporting that it is running. Successful creation alone is not that check. ## Suspend and resume your machine To pause compute while preserving machine data, ask the agent to follow the [Machine suspend and resume guidance](/compute/machines#suspend-and-resume). The agent asks for approval before changing the machine. After resuming, it waits for the operation to succeed, reads back the machine as active, and checks the application's public URL again. Networking can still be settling when the machine becomes active; the application response is the final check. ## Clean up the trial resources When you have finished, you can ask the agent to remove the resources created for this trial. Before deletion, it lists their exact IDs and asks you to confirm. Deletion can permanently remove application and machine data. The agent deletes the trial Install first, then its Machine, then its Cluster. It follows each returned operation to `SUCCEEDED` and confirms the resource no longer appears before continuing. It also confirms the deleted application's public URL no longer serves the workload. Other resources in the workspace remain untouched. See [Installation lifecycle](/installs/lifecycle#delete-an-installation) and [Machine deletion](/compute/machines#deletion) for the consequences. Deleting these resources does not restore the account's one-time trial. ## Optional: mirror your infrastructure as code During onboarding the agent asks one optional question: **"Do you want the infrastructure I create mirrored declaratively in your git repository?"** Answer no and nothing changes; the platform state in your workspace stays the single source of truth, and you can revisit the choice later. Answer yes and the agent keeps a second artifact alongside every resource it creates through the Akua API: a typed definition in your repository. Create a cluster, attach a worker, install a product, and the agent writes the matching code in the same commit-sized step, so your repo replays what exists in your workspace. You review infrastructure the way you review any other pull request, and a future agent session can read the mirror instead of rediscovering state through API calls. This path is for power users who already treat every artifact as code. It is not required for any Akua feature, and the platform never blocks on the mirror being present or current. This is not GitOps, and it does not replace it. `akua pkg` still renders deterministic Kubernetes manifests that a reconciler applies to a cluster. The declarative mirror covers a different layer: the Akua platform resources themselves (workspaces, clusters, machines, installs) as reviewable code driving the public API. Other tools can manage the same resources through that API; the agent-maintained mirror is one convenient default, not a required format. If you opt in, tell the agent where the mirror lives (for example `infra/akua/` in the repository it is already working in). Any Git remote works: GitHub, your own Git server, or the Git hosting already built into Akua. The agent proposes the layout, keeps it current as it works, and asks before deleting any resource the mirror no longer contains. ## Paths the agent can guide The agent discovers the current command surface with `akua commands` instead of relying on a fixed list or provider-specific CLI helpers. | Starting point | Supported direction | | - | - | | No infrastructure | Create a workspace-owned [managed cluster](/clusters/create), add the free Akua-managed machine, then package and install the app. The agent checks [quota](/platform/quotas) and [pricing](/pricing), then asks before creating anything. | | Existing Kubernetes cluster | Follow [Import a cluster](/clusters/import), validate the kubeconfig path, and ask before connecting or installing software. | | Existing machine | Create or select a managed cluster, then follow [Add workers](/clusters/add-workers). The agent asks before any SSH connection or machine-changing command. | | Your cloud account | Follow [Bring your own cloud](/platform/byoc) and the generated Secrets and Compute Configs operations. The CLI stays provider-neutral. | | Application or package | Use `akua pkg` for local Package work, then discover the Packages and Installs operations. | | Product or Offer | Read the [Product](/products) and [Offer](/marketplace/offers) docs, then use the generated Products and Offers operations. | Every path uses the same public CLI commands and documented APIs; there are no special onboarding endpoints. A managed-cluster request requires a workspace-defined [region](/clusters/regions). Ready pool capacity can fulfill eligible free-tier requests without a cloud credential. The `machines create` command without a compute configuration requests the system-managed free machine, consuming the account's [one-time managed-VM trial](/platform/quotas#the-one-time-managed-vm-trial) — not a monthly allowance, and not restored by deleting the machine, cluster, workspace, or organization afterward. Resource [quotas](/platform/quotas) enforce the [free allowance](/pricing). An installation needs an existing Product or Package version, which is why the agent packages your application before installing it. The agent stops when a prerequisite is unavailable and verifies each public operation before reporting that an application is running. ## Add MCP later if useful MCP can give compatible agents additional documentation and workspace context, but it is not part of the critical path. Configure it after CLI authentication works. Many agent hosts need a restart or a new conversation before newly added MCP servers appear, so the agent must continue through the CLI instead of waiting. The [agent setup guide](/agent-setup) lists the optional documentation and platform MCP servers. ## Related topics Install, authenticate, select context, and run generated commands. Review agent instructions and optional MCP configuration. Create a workspace-owned Kubernetes control plane. Review Free, Pro, and bring-your-own-cloud terms. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.