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/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. Every later workspace-scoped generated command must include the confirmed workspace wire ID in the request object’s headers.akua-context field:
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:
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. 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:
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. 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.