Start with one prompt
Give your coding agent this instruction:What happens next
Install the CLI
The agent checks for If Homebrew isn’t available, the agent follows the checksummed release archive
instructions in the CLI repository.
akua, installs or updates the supported CLI, and runs
akua --help to confirm the command surface. The supported Homebrew path is:Sign in together
The agent runs: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.Describe what you want to build
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 and the pages
relevant to your goal.
Decide on the optional mirror
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 for
what yes means.
Approve the one-time trial
Before creating anything billable, the agent explains the documented
free allowance (one managed cluster and one Akua-managed
machine, claimed once, for the lifetime of your account), the free
machine’s 7-day lifetime, 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.Create the cluster
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 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.Add the free machine
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 is available.Package and install your app
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.Verify it's live
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. 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 toSUCCEEDED 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 and
Machine 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.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 withakua commands instead
of relying on a fixed list or provider-specific CLI helpers.
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. 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 — not a monthly
allowance, and not restored by deleting the machine, cluster, workspace, or
organization afterward. Resource quotas enforce the
free allowance. 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 lists the optional documentation and platform MCP servers.Related topics
CLI reference
Install, authenticate, select context, and run generated commands.
Agent setup
Review agent instructions and optional MCP configuration.
Managed clusters
Create a workspace-owned Kubernetes control plane.
Pricing
Review Free, Pro, and bring-your-own-cloud terms.