Skip to main content

​
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:
If akua is missing on macOS or Linux with Homebrew, install the supported formula:
If the formula is already installed, update it before continuing:
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:
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:
Open the displayed URL only with the user’s permission. After approval, verify the local session:
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:
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:
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:
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:
Use akua <resource> <action> --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 --<flag>-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:
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 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 7-day lifetime, 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 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, 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. 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

​
Claude Code

​
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.