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 includes the
confirmed workspace ID as headers.akua-context in later CLI request
objects.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
body.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;
the verification step below follows the returned operation.Add the free machine
The agent creates a worker with
akua machines create, omitting the
compute configuration to request the system-managed free 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.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.Verify it's live
The agent polls each returned operation with
akua operations get and
confirms the application’s public URL responds before reporting that it
is running.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.