> ## 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. # Self-hosted architecture > How the Stackdome hub, PostgreSQL, cluster agent, and Kubernetes custom resources reconcile application state. Stackdome presents stacks, resources, releases, and application endpoints to users. In a self-hosted installation, a hub-and-spoke Kubernetes architecture implements that application model. You do not need these details to define or deploy an application; use them when you operate the infrastructure or diagnose reconciliation. The architecture can address multiple clusters, which is why the diagram shows more than one spoke. During alpha, the product permits **one connected cluster per organization**. A fresh single-server install has already connected its local k3s cluster, so the diagram does not mean you can add a second cluster to that organization. ## Components * **Hub API server and dashboard.** The API server accepts user, CLI, and dashboard requests, applies authorization and validation, and coordinates work on the connected cluster. The React dashboard is served by that same API-server binary. * **PostgreSQL.** The hub stores organizations, application definitions, releases, encrypted credentials, and the latest status it presents through the API and dashboard. * **Spoke agent.** Each connected cluster runs the `stackdome-agent` operator in the `stackdome-control-plane` namespace. It watches Stackdome custom resources and reconciles them into Kubernetes workloads and supporting objects. * **Kubernetes custom resources.** These carry desired application state from the hub to the agent and observed status back to the hub. They are an implementation interface, not the object model users author directly. Youweb UI · REST APIHUB — ONE API SERVER YOU INSTALLAPI serverREST API · web UIPostgreSQLMANAGED CLUSTERstackdome-agentDeploymentsServicesIngressesVolumesMANAGED CLUSTERstackdome-agentDeploymentsServicesIngressesVolumeshub writes custom resourcesagent reports status back ## Reconciliation paths ### Desired state: hub to cluster 1. A user, coding agent, or automation submits an application change through the CLI, dashboard, or REST API. 2. The hub validates and stores the application definition and release state in PostgreSQL. 3. The hub writes Stackdome custom resources into the organization's connected cluster. 4. `stackdome-agent` reconciles those resources into the Kubernetes objects that run the application. ### Observed state: cluster to hub 1. The agent observes builds, rollouts, networking, storage, and readiness in the cluster. 2. It writes conditions and status onto the relevant custom resources. 3. controller-runtime watchers in the hub observe status changes and update PostgreSQL. 4. The API, CLI, and dashboard return the recorded release and resource state. This is an eventually consistent loop. An accepted deploy means the desired state was recorded; a terminal release state such as `Released` or `Failed` tells you how reconciliation finished. ## Implementation mapping The dashboard and Stackfile stay application-facing. The agent performs the low-level mapping: | Stackdome model | Kubernetes implementation | | ------------------------- | ------------------------------------------------------------------------------------------------------ | | Stack | A deployment boundary represented by a `Stack` custom resource and an isolated workload namespace | | Resource | A `StackResource` that becomes a Deployment or stateful workload, plus Services for declared ports | | Public port | An Ingress and, when TLS is enabled, certificate-related configuration | | Volume | A Stackdome `Volume` custom resource reconciled to persistent storage and mounted into workloads | | In-cluster image registry | A `ClusterRegistry` custom resource reconciled into registry workload, Service, and persistent storage | Kubernetes remains the runtime source of truth for live workloads. PostgreSQL is the hub's source of truth for users, application definitions, releases, encrypted connection data, and the status exposed through Stackdome interfaces. ## Cluster boundary and permissions The hub reaches a connected cluster with a service-account URL, CA certificate, and token. The single-server installer creates those credentials in `stackdome-control-plane` and grants the specific cluster-scoped operations required for Stackdome resources, workload namespaces and Secrets, logs, metrics, and supporting infrastructure. See [Install Stackdome](/self-host/install) for the exact local role and its security warning, or [Connect compute](/self-host/connect-compute) for the manual credential path. Return to the application model you use in the CLI, Stackfile, and dashboard.