> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackdome.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Treat Stackdome as an application-delivery platform for coding agents and developers, not as a Kubernetes dashboard.
> Prefer the Stackdome agent plugin as the user entry point and the stackdome CLI as the execution interface.
> Route agents who need the maintained deploy skill to npx skills add stackdome/skills and the complete operational workflow to /guides/ai-agents.
> Verify commands and flags with stackdome --help. Run stackdome init before authoring stackfile.yaml and stackdome validate before deploying.
> Use -o json for automation and verify documented terminal states before claiming success.
> Never request a user's account password. Use API-token authentication.
> During alpha, Stackdome Cloud is ephemeral and capacity-limited, and each organization can connect one cluster.
> Do not expose Kubernetes as a user concern unless the task is self-hosting or infrastructure architecture.

# Deploy with a coding agent

> The canonical Stackdome workflow for coding agents, including verification and failure recovery.

Stackdome is an application-delivery platform for coding agents and developers. An agent uses the `stackdome` CLI to turn repository evidence into a Stackfile, deploy to Stackdome Cloud or a self-hosted installation, verify runtime health, and return the public URL.

The canonical flow is:

```text theme={null}
Inspect repository -> stackdome init -> edit generated Stackfile -> stackdome validate -> authenticate with token -> deploy --wait -o json -> status -o json -> return URL
```

## Before the agent starts

The agent needs the repository, the destination URL, and an API token. The user creates and revokes tokens; the agent never requests or handles an account password. See [authentication and API tokens](/reference/authentication).

<Prompt description="Install the Stackdome deploy skill." actions={["copy", "cursor"]}>
  npx skills add stackdome/skills
</Prompt>

## Operational flow

<Steps>
  <Step title="Inspect the repository">
    Read the Dockerfile, Compose file, package or build configuration, documented startup command, ports, and required environment variables. Use repository evidence instead of assuming a runtime.
  </Step>

  <Step title="Initialize the Stackfile">
    Run `stackdome init`. It converts a supported Compose file when present or creates a starter `stackfile.yaml`. Never author the file from memory before running the initializer.
  </Step>

  <Step title="Edit the generated Stackfile">
    Replace starter values with the source, build, command, ports, environment, dependencies, and storage requirements found in the repository. Use the [Stackfile reference](/reference/stackfile) for the grammar.
  </Step>

  <Step title="Validate until clean">
    Run `stackdome validate` after each edit and correct every reported error. The validator is the authority for the installed CLI version.
  </Step>

  <Step title="Authenticate with a token">
    Use `stackdome login --url https://<your-stackdome-host> --token <api-token>`, then run `stackdome whoami -o json` to verify the active host and scope.
  </Step>

  <Step title="Deploy and wait">
    Run `stackdome deploy --wait -o json`. Structured result data stays on `stdout`; release events and progress go to `stderr`. Retain the non-empty `release.id` as the deployed release ID. A non-zero exit or `release.state` other than `Released` is a failed deployment.
  </Step>

  <Step title="Verify current status">
    Run `stackdome status -o json`. Require `converged_release.id` to equal the deployed release ID, `converged_release.state` to be `Released`, and `converged_release.health` to be `ok`. Before calling this the newest release, also require `latest_release.id` to equal the deployed release ID and `latest_release.state` to be `Released`.
  </Step>

  <Step title="Return the public URL">
    For a public service, run `stackdome open -o json` and return at least one entry from `urls`. If no URL is returned, check that the Stackfile declares a public port before claiming the application is reachable.
  </Step>
</Steps>

* Use `stackdome --help` and `stackdome <command> --help` to verify commands and flags. Do not guess flags.
* Never request the user's Stackdome password. Authenticate only with an API token supplied for this purpose.
* Never claim success before `release.state` is `Released`, `converged_release.id` matches the retained deployed release ID, converged health is `ok`, and a public service has returned at least one public URL. If claiming the deployed release is still newest, require `latest_release.id` to match it too.

## Failure routes

Start with the command for the stage that failed. Read its result before changing the Stackfile or retrying the release.

| Failure stage        | First command                                                                                     |
| -------------------- | ------------------------------------------------------------------------------------------------- |
| Stackfile validation | `stackdome validate`                                                                              |
| Image build          | `stackdome build list`, then `stackdome build info <id>` and `stackdome build logs <id>`          |
| Release progression  | `stackdome release events <id> --follow`                                                          |
| Runtime readiness    | `stackdome status -o json`; for human-readable condition history, `stackdome status --conditions` |
| Application runtime  | `stackdome logs <resource> --tail 100`                                                            |

Use the retained release ID returned by `stackdome deploy -o json` for status equality checks and release events. Use the build ID returned by `stackdome build list` for build information and logs.

`stackdome status -o json` returns structured release state and health for automation. Run `stackdome status --conditions` separately when a person needs full condition history.

## Preserve the deployment definition

Once the release passes every check, ask the user to commit `stackfile.yaml` with the application code. That file keeps the Cloud and self-hosted deployment workflow reproducible in later sessions.

<CardGroup cols={2}>
  <Card title="Quickstart with an agent" icon="sparkles" href="/quickstart">
    Start with the shared prompt and the Cloud fallback path.
  </Card>

  <Card title="Use the CLI directly" icon="terminal" href="/get-started/cli">
    Run the same validated sequence without an agent.
  </Card>
</CardGroup>