> ## 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 from an image > Run an existing container image, including images from private registries. ## Outcome Deploy an existing container image as a Stackdome resource and wait until the release is healthy. This path pulls an image that was built elsewhere; it does not clone a repository or run an image build. A public port produces a URL you can return to the user. ## Prerequisites * The image reference, including its registry host and a tag or digest. Prefer a digest when the deployed bits must not drift. * Evidence about the container's listening ports, command, environment requirements, dependencies, and storage paths. * The URL of Stackdome Cloud or a self-hosted installation, plus an API token. See [authentication and API tokens](/reference/authentication). * A registry reachable from both the Stackdome hub, which probes the image before release, and the deployment destination, which performs the pull. * For a private image, a registry credential already configured through the dashboard or API. The current public CLI cannot create, update, or verify registry credentials. If you need a managed Postgres database, use [Postgres](/guides/postgres) instead of running `postgres:16` as an ordinary resource. ## Agent prompt ```text theme={null} Deploy this container image to Stackdome: . Use the supplied requirements and repository evidence for its command, ports, environment, dependencies, and storage. Run stackdome init before editing stackfile.yaml, set the generated resource's image reference, validate every edit, authenticate only with an API token, deploy with stackdome deploy --wait -o json, retain the returned release ID, verify that the converged release ID matches it and converged health is ok, and return the public URL. If the image is private and no registry credential is configured, stop and tell me that credential setup currently requires the Stackdome dashboard or API. ``` ## Agent actions Confirm the exact image reference, listening ports, command, environment values, dependencies, and storage. Do not assume that a container exposes a public HTTP port. Run `stackdome init` before editing. It creates `stackfile.yaml` or converts a supported Compose file in the current directory. Edit the generated resource so `image` contains the full reference. Remove any `build` key from that resource because a resource accepts exactly one source. Add only the ports and runtime configuration supported by evidence. Run `stackdome validate`, then authenticate with `stackdome login --url https:// --token ` and confirm the active scope with `stackdome whoami -o json`. Run `stackdome deploy --wait -o json`, retain its non-empty `release.id` as the deployed release ID, then run `stackdome status -o json`. For a public service, run `stackdome open -o json` and return an entry from `urls`. ## Success criteria * `stackdome validate` exits successfully for the generated `stackfile.yaml`. * `stackdome deploy --wait -o json` exits successfully, returns a non-empty `release.id` that is retained as the deployed release ID, and returns `release.state` as `Released`. * `stackdome status -o json` returns `converged_release.id` equal to the deployed release ID, `converged_release.state` as `Released`, and `converged_release.health` as `ok`. * A public service returns at least one entry in the `urls` array from `stackdome open -o json`. * No registry password or token appears in the Stackfile, shell history captured for support, screenshots, tickets, or chat messages. ## CLI workflow Initialize from the working directory, then edit the generated file: ```bash theme={null} stackdome init ``` Replace the generated resource with an image-backed definition based on the container's requirements: ```yaml theme={null} name: postgrest resources: api: image: postgrest/postgrest:v12.2.0 ports: - name: http port: 3000 protocol: HTTP public: true ``` Use a fully qualified reference such as `ghcr.io/acme/api:1.4.2` for another registry. A resource must contain exactly one of `image` or `build`. See the [Stackfile reference](/reference/stackfile) for runtime fields and current release gaps. Validate, authenticate, deploy, and inspect the terminal state: ```bash theme={null} stackdome validate stackdome login --url https:// --token stackdome whoami -o json stackdome deploy --wait -o json stackdome status -o json stackdome open -o json ``` For a private image, configure its registry credential through the dashboard or API first. The public CLI has no image-registry management command, and the Stackfile has no field for registry passwords or tokens. ## Troubleshooting Start with the release and resource data returned by the CLI: ```bash theme={null} stackdome status -o json stackdome release events --follow stackdome logs --tail 100 ``` Use the release ID returned by `stackdome deploy -o json`. An image release validates its source against the registry before rendering the workload. A release validates every image source against its registry before it renders anything, and the **Deployments** tab narrates it: | Event | Means | | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------- | | **Validating release** | The checks started. | | **Release checks passed** | Every check genuinely passed. | | `Check source.image.ref: failed for : ` | One check failed. The release then fails with `release validation failed: N error(s)`. | Three failures are specific to pulling an image, and the distinction between the first two is the whole point: | Code | Message | Do this | | ------------------------------- | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | `registry_credentials_required` | `image 'ghcr.io/acme/api:1.4.2' requires credentials for registry 'ghcr.io', but none are configured` | No credential resolved and the registry refuses anonymous access. Add one for that host. | | `registry_auth_failed` | `registry 'ghcr.io' rejected the configured credentials for image 'ghcr.io/acme/api:1.4.2'` | A credential *was* found and refused. Verify it, then rotate it through **Update credentials**. | | `image_not_found` | `image 'ghcr.io/acme/api:1.4.2' does not exist or is not accessible` | Usually a typo in the repository or a tag that was never pushed. | Successful probes are remembered, so redeploying an unchanged reference with unchanged credentials does not re-probe the registry. Change either and it is checked again. On self-hosted Kubernetes compute, one reference is deliberately skipped: an image whose host ends in `.svc.cluster.local` lives inside that cluster, where the hub cannot reach it. Those go straight through to the destination's own pull. ### Registry rate limits Unauthenticated pulls from Docker Hub are throttled. When the registry answers the hub's probe with a rate-limit signal instead of an answer, Stackdome does **not** fail the release — a limit can persist for hours, and the image would most likely have pulled fine. It logs a warning, skips that check, and lets the deploy continue. The observable symptom is an absence. The deploy runs normally, but **Release checks passed** never appears in that release's timeline. That line asserts every check genuinely passed, so a single skipped check withholds it for the whole release — the other resources in the stack may well have been verified, and you cannot tell from the timeline which were which. Two things follow: * **Early failure detection is gone for the image that was skipped.** A typo in that reference is no longer caught before the deploy; it surfaces later as the resource failing to start. * **The destination still has to pull.** The hub's probe is not the pull. A destination whose own unauthenticated pulls are being throttled will stall on the image no matter what the hub concluded, and the deploy runs to its timeout. The fix in both cases is to stop pulling anonymously: add a Docker Hub credential with a purpose that covers pulling. It attaches by host, so nothing in the drawer needs editing. ## Related tasks Reach for an image source when you did not write the thing you are running, or when your build already happens somewhere else and publishes to a registry. Reach for a git source when the code is yours and you want the deploy to start from a commit rather than from an image you have to remember to build and push — that path pins revisions per release, so a rollback is exact. Follow the complete agent operating contract, verification rules, and failure routes. Configure image sources, ports, environment values, dependencies, and storage. Let Stackdome build a repository and pin its resolved revision per release. Create and handle API tokens safely for agent and CLI sessions.